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.9.7, gcc would be gcc-10.2.0, etc). changing conventions (e.g. ',' or '-' or different 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 undeerstand 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.
- 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 blfs-dev 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.