= 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
https://github.com/FreeRADIUS/freeradius-server/pulls[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 GitHub

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

* https://help.github.com/articles/fork-a-repo
* https://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.
mailto:freeradius-devel@lists.freeradius.org[freeradius-devel@lists.freeradius.org]

Otherwise, send the patch to
mailto:patches@freeradius.org[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.
