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.
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 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.