LTSI kernel tree
================

Table Of Contents
=================

	Introduction
	Building the Tree
	Patch Headers


Introduction
============

This is the LTSI kernel tree.  It is developed as a set of patches, that
apply to the specified kernel version.  The tree can be used directly as
a quilt tree for development, or it can be exported as a git tree, a
single compressed patch, or as an RPM source package that will
successfully build in an OBS instance.

For questions about the LTSI project, and how it operates, please see
the documentation at http://ltsi.linuxfoundation.org/what-is-ltsi

For discussions about these patches, or anything else related to the
LTSI project, please contact the partipitants at the ltsi-dev mailing
list.  Instructions on how to post to it can be found at:
	https://lists.linuxfoundation.org/mailman/listinfo/ltsi-dev


Building the Tree
=================

The tree is maintained as a quilt tree of patches, all of which are
applied in a sequence described in the file, 'series', to a specific
kernel tree.

The current version of the kernel tree that the sequence is to be
applied to can be found in the file KERNEL_VERSION.

The tree can be exported in a variety of different formats, to help you
integrate it into your build system.  The currently supported formats
are:
	- quilt tree
	- git tree
	- single compressed patch
	- OBS source repo

Quilt Tree
----------

The tree is already in a quilt tree format, and can be developed in this
manner.  It is recommended that you create a kernel tree based on the
version described in the file KERNEL_VERSION and then change your
QUILT_PATCHES environment variable to point to the location of this
tree.  quilt will see the series file, and you can easily push and pop
the various patches directly.


Git Tree
--------

The tree can be exported as a git tree, based on the kernel.org upstream
release described in the file KERNEL_VERSION.  To do this run the
scripts/generate_git script.  For more details on the environment
variables this script expects and how it works, please see the built in
help in the script by running:
	scripts/generate_git --help


Single Compressed Patch
-----------------------

The tree can be exported as a compressed single patch, based on the
kernel.org release described in the KERNEL_VERSION file.  To do this,
run the scripts/generate_patch script.  For more details on the
environment variables this script expects and how it works, please see
the built in help in the script by running:
	scripts/generate_patch --help


OBS source
----------

The tree can be exported as a set of files that can be used as an OBS
source package.  These files can then be used by OBS to generate both a
kernel source and kernel binary package, for a specific configuration.
To do this run the scripts/generate_obs script.  For more details on the
environment variables this script expects and how it works, please see
the built in help in the script by running:
	scripts/generate_obs --help


Patch Headers
=============

Each patch must have a RFC822-style header that at a minimum describes
what the patch does, who wrote it, and who can be contacted for any
questions about the patch.  The rules for patch headers are:

 * Each patch must have a From: tag that identifies the author of the
   patch.

 * Each patch must have a Subject: tag that briefly describes what
   the patch does.  A brief summary is it could show up in a change
   log makes the most sense in most cases.

 * The patch MUST include a Signed-off-by: address that identifies the
   person or people who have reviewed the patch, and can be available if
   there are any questions or problems about the patch.  For more
   details on exactly what "Signed-off-by:" means, see the file,
   Documentation/SubmittingPatches in the Linux kernel source tree.

 * If the patch is already upstream, or has been submitted for inclusion
   in the upstream kernel project, it must include a Patch-mainline: tag
   that identifies where the patch came from (for backports from
   mainline), or when it is expected to be added to mainline. The format
   is Patch-mainline: <upstream version>
   or Patch-mainline: Submitted <timestamp - destination>
   or Patch-mainline: <guess followed by a question mark>
   or Patch-mainline: Never <reason>

   If applicable, please also include
   Git-commit: <git hash> (there can be more than one if the patch is an
   aggregate of multiple commits)

   If the commit is from a maintainer repository or some other repository
   that isn't Linus's:
   Git-repo: <url to git repo>

 * The patch header may (and often, should) include a more extensive
   description of what the patch does, why, and how.  The idea is to
   allow others to quickly identify what each patch is about, and to
   give enough information for reviewing.


Minimal Requirements
====================

o  patch              2.6.1.64            # patch --version


patch
-----

The tree makes extensive use of git formatted patches, which are not
fully supported by older versions of patch.  Older versions will silently
discard parts of the diff they don't understand (such as renames), leading
to inconsistent state with some patches only being partially applied.


----------------------

Many thanks for the SUSE kernel team for their kernel patch rules, upon
which these rules are closely based.