Submitting patches¶
Submitting patches¶
These guidelines apply to any projects that I maintain regardless of whether they are work or personal projects. Patches that don’t conform to the guidelines may well be silently dropped, I know this sounds harsh but my workload is already too high.
Transport method¶
Mail¶
If you are emailing a patch it is important that you include the name of the project somewhere in the subject line of the mail, it doesn’t matter where but it helps to automatically sort mail before I even get around to reading it.
There is no requirement, or need, to add a [PATCH] prefix to the subject, but you can do so if you wish.
Inline patches, MIME encoded or uuencoded patches are all acceptable.
BTS¶
All patches that are submitted through the AST BTS must follow the rules defined in the “Help with submissions” information page which is linked to from the toolbar on every page of the BTS.
Please be careful with your status attribute, having to reclassify patches severely eats in to my time and as such makes me take longer to reply. In general “Fix” or “New feature” should be picked, unless you are sure of the meaning of another category.
Legal issues¶
Make sure you are aware of the licensing requirements for any project you submit a change to, and that you have the legal right to submit the changes.
There are more stringent content requirements for packages licensed under the APL, and you will be presented with the options in the BTS for such packages.
Please state your personal licensing requirements in the body of your mail or BTS entry. It is totally acceptable, and encouraged, for you to place a header at the top of all files you create which explicitly defines the license your work in released under.
Making the patch¶
- Patches should be in unified format(the -u option to GNU diff).
- The use of GNU diff’s -p or an appropriate --show-function-line is encouraged. For a list of --show-function-line arguments for most common filetypes read the dforce documentation.
- The extraneous output from CVS diff, mkpatch, etc is fine. The only requisite is that GNU patch is not confused by the extra data.
- Patches must be relative to the directory above the top source directory. It does not matter what the name of the first stripping level is.
- Stripping levels must be equal for the source and destination, this is very important.
- Patches, mails or BTS entries must contain only one logical change. One fix or one new feature only! If you need to submit patches which depend on each other use mail threads or the “link” feature in the BTS.
Note
An example GNU diff command for for generating acceptable patches is diff -pruN old-tree/ new-tree/
Important
Taking dot_bash as the example that drove me to write this, changes to the top level README file should appear as dot_bash/README in the patch. Once again it does not matter what the first stripping level is, but it must be there.
Sending the patch¶
Try to write a short 2-3 line description for the patch. If the patch needs more explanation then follow the short description with an in-depth description, but still include a short 2-3 line description.
Note
The short 2-3 line description will most likely be used as the ChangeLog entry so should be totally self-contained.
If you are sending a mail and your MUA is incapable of producing content flowed mail then you should pre-wrap the text to 72 columns. If you MUA does content flowed mail then wrapping is unimportant.
If you are mailing the patch include the full version string somewhere in the mail of the form $project_name v$Major.$Minor.$Micro, and if you are using the BTS be sure to select the correct project version from the interface.