Contributing
Submitting patches or diff’s to the FreeRADIUS project
For a person or company wishing to submit a change to the FreeRADIUS project the process can sometimes be daunting if you’re not familiar with "the system." This text is a collection of suggestions which can greatly increase the chances of your change being accepted.
Note: Only trivial patches will be accepted via email. Large patches, or patches that modify a number of files MUST be submitted as a pull-request via GitHub.
Hints and tips
1. Describe your changes
Describe the technical detail of the change(s) your patch or commit includes.
Be as specific as possible. The WORST descriptions possible include things like "update file X", "bug fix for file X", or "this patch includes updates for subsystem X. Please apply."
If your description starts to get long, that’s a sign that you probably need to split up your commit. See the next point.
2. Separate your changes
Separate each logical change into its own commit.
For example, if your changes include both bug fixes and performance enhancements for a single module, separate those changes into two or more patches.
On the other hand, if you make a single change to numerous files, group those changes into a single commit. Thus a single LOGICAL change is contained within a single commit.
If one commit depends on another commit in order for a change to be complete, that is OK. Simply note "this commit depends on commit X" in the extended commit description.
If your commit includes significant whitespace changes these should also be broken out into another, separate, commit.
Submitting patches via email
1. diff -u
Use diff -u or diff -urN to create patches.
All changes to the source occur in the form of patches, as generated by
diff(1). When creating your patch, make sure to create it in unified
diff format, as supplied by the -u argument to diff(1). Patches
should be based in the root source directory, not in any lower
subdirectory.
- To create a patch for a single file, it is often sufficient to do
SRCTREE=/home/user/src/freeradiusd/
MYFILE=src/modules/rlm_foo/foo.c
cd $SRCTREE
cp $MYFILE $MYFILE.orig
vi $MYFILE # make your change
diff -u $MYFILE.orig $MYFILE > /tmp/patchTo create a patch for multiple files, you should unpack a vanilla,
or unmodified source tree, and generate a diff against your own source
tree. For example:
MYSRC=/home/user/src/freeradiusd-feature/
gunzip freeradiusd-version.tar.gz
tar xvf freeradiusd-version.tar
diff -urN freeradiusd-version $MYSRC > ~/feature-version.patch2. Select e-mail destination
If you are on the developers mailing list, send the patch there. freeradius-devel@lists.freeradius.org
Otherwise, send the patch to patches@freeradius.org
3. No MIME, no links, no compression, no attachments. Just plain text
The developers need to be able to read and comment on the changes you
are submitting. It is important for a developer to be able to quote
your changes, using standard e-mail tools, so that they may comment on
specific portions of your code.
For this reason, all patches should be submitting e-mail inline.
Do not attach the patch as a MIME attachment, compressed or not. Many popular e-mail applications will not always transmit a MIME attachment as plain text, making it impossible to comment on your code. A MIME attachment also takes a bit more time to process, decreasing the likelihood of your MIME-attached change being accepted.
Compressed patches are generally rejected outright. If the developer has to do additional work to read your patch, the odds are that it will be ignored completely.