Patches Submission Guidelines

Before submitting a patch, check if there is an already existing patch for the current version or a previous version. If there is a patch for the previous version that applies without an error (Note: Getting an offset/fuzz when applying the patch is not an error) just drop a note on the list and the patches maintainers will copy the file over to the new version.

A suggested command for creating the patch file is:

LC_ALL=C TZ=UTC0 diff -Naur [old...] [new...] > [patch name...].patch

Note that this is not an absolute requirement and you are free to create the patch any way you like as long as the following requirement is satisfied. When creating the patch, you should be in a directory just above the package directory so that the resulting patch can be applied with patch -p1 as per the current instructions in the book.

The patch file name should be in the following format:

${packageName}-${packageVersion}-${patchName}-${patchVersion}.patch

packageName
Official name of the package. Be sure to follow the same capitalization that is followed by the official tarball for the package (i.e. cracklib would be cracklib,2.7, gcc would be gcc-3.3.4, etc.). changing conventions (e.g. ',' or '-' or differing package names) shouldn't be a consideration - it's up to upstream how they package their tarballs and we should reflect their naming convention. Where package descriptions have multiple words, those words should be '_' separated to differentiate between the '-' separated fields we have on the patches project at present.
packageVersion
Version against which the patch applies.
patchName
Short name for the patch (also include architecture if the patch is for a particular architecture).
patchVersion
Version of the patch (starting at 1, if there is no previous version). This field is mandatory.

The patch should have the following information, each item on a seperate line and in the same order (Be sure to follow the capitalization of the headers so that it is easier for scripts to parse the fields):

Submitted By
Name and/or E-mail of submitter.
Date
Date Patch Submitted in YYYY-MM-DD format. It is easier for everyone to comprehend the international format, please do not use any other.
Initial Package Version
Version against which the patch was initially prepared.
Upstream Status
Whether the patch has been submitted to and/or accepted by the original developers. The following are some suggestions for this field along with the explanations:
Not submitted - LFS Specific
The patch is specific to LFS and has no value upstream. This should generally be avoided.
Not submitted - [Test Version, Hack, Maintainer AWOL, ...]
The patch has not been submitted upstream for some reason - e.g. the patch needs to be properly tested, the patch is a hack that will not be acceptable upstream, the maintainer is AWOL, ...
From Upstream
The patch is submitted upstream (not necessarily by you) and will be available in a future release.
Submitted Upstream
The patch has been submitted upstream (not necessarily by you) but there is no word yet from the maintainers.
Rejected Upstream
The patch was submitted upstream (not necessarily by you) but was rejected by the maintainers.
If someone other than you had submitted the patch upstream, please acknowledge the person in the Description section. Also, it is always useful to add an URI for the relevant discussion.
Origin
Where the patch originated. This is useful for the users when considering whether to apply the patch. Please keep this field short and restricted to a single line. A URI to a mailing-list discussion on the patch is the best fit for this field. Another option, if the patch is taken from a distro package is to write the name of the distribution and the package name (e.g. Redhat mozilla-1.4-12.src.rpm). If the patch is created by you and there is no URI to reference, just add your name in the field.
Description
Description of what the patch does, links to more information related to the patch, etc. The more information you give to potential appliers of the patch, the better chance it has of being used. If you are modifying an existing patch, be sure to credit the original author.

Note: See the sample patch.

Patches should be mailed to the patches mailing list. The patches maintainers prefer receiving download URIs also along with the patches. Even if you include a URI, please attach the patch along with your submission for the archives. Please gzip or bzip2 the patches so that it is easy for people to download the patches directly from the list archives. At the same time it saves some bandwidth. The patches will be gunziped or bunzip2ed before uploading so that they can be viewed online.

You can use this script to automatically generate and e-mail the proper patch. You may also use the checkPatch script to verify that all the required headers are available in the patch.

Refer to the mailing list information page for details on the mailing list.