Note! The below is the “legacy” way of creating a patch eg. for submission to the mailing list. For contributions to Jumbo, a Pull Requested on GitHub is preferred.
If you have modified our software and would like to submit or otherwise distribute a patch for others to use, please use the following command on a Unix-like system (or on Cygwin if you use Windows) to generate the patch file:
First, delete any irrelevant files. Make “clean”, for a starter.
make -s clean
Then, use these options to diff(1) for creating the patch:
TZ=UTC diff -urpN NAME-VERSION.orig NAME-VERSION > NAME-VERSION-WHAT-REVISION.diff
For example, revision 12 of the jumbo patch for John the Ripper 1.7.2 was generated with:
TZ=UTC diff -urpN john-1.7.2.orig john-1.7.2 > john-1.7.2-all-12.diff gzip -9 john-1.7.2-all-12.diff
Or, to have it on one single line:
TZ=UTC diff -urpN john-1.7.2.orig john-1.7.2 | gzip -c9 > john-1.7.2-all-12.diff.gz
For a new patch, or a patch to a new version of the software, use revision 1. This will help us track any updates to the patch that we or you might make later.
If you intend to send a patch by e-mail, or especially to post it to one of our mailing lists (e.g., john-users), please leave it uncompressed (as long as the patch is smaller than, say, 50 KB) and attach it to the message, with text/plain, text/x-patch, or text/x-diff as the MIME Content-Type. This makes the patch visible in web-based archives of the mailing lists, as well as makes it easier to quote and comment on it in any follow-ups.
Before submitting a patch to the list, please review it. It's as simple as looking at your patch, eg:
diffstat john-1.7.9-jumbo-7-hmacfix-1.diff run/pass_gen.pl | 12 ++++++------ src/hmacSHA256_fmt_plug.c | 22 ++++++++++++++-------- 2 files changed, 20 insertions(+), 14 deletions(-)
Does it look relevant? No unwanted extra files listed? You should also have a final look at the full patch:
less john-1.7.9-jumbo-7-hmacfix-1.diff
Patches for John the Ripper may also be uploaded to the proper wiki page, and then you may post the wiki URL to john-users. Whatever way you choose to share your code with the community, please make sure you're licensing your code properly.
When re-generating patches to apply additional changes, the existing patches should be applied with patch -Z, for example like this:
cd NAME-VERSION patch -p1 -Z < ../NAME-VERSION-WHAT-REVISION.diff
The use of timestamps in UTC lets us better preserve them over patch file updates and reduces the amount of changes between revisions, which makes it easier to review any changes.
Please remember to format your code properly:
indent -kr -i8 -nlp -nbbo -ncs -l79 -lc79 -il0