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 #3, next.

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

See the following links for more details about submitting via github:

- https://help.github.com/articles/fork-a-repo
- http://wiki.freeradius.org/contributing/GitHub

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/patch

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


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

4. E-mail size
~~~~~~~~~~~~~~

Large changes are not appropriate for mailing lists, and some maintainers. If
your patch, exceeds 5Kb in size, you must submit the patch via GitHub instead.

5. Name the version of the server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It is important to note, either in the subject line or in the patch
description, the server version to which this patch applies.