1 files changed, 126 insertions, 0 deletions
diff --git a/doc/antora/modules/developers/pages/contributing.adoc b/doc/antora/modules/developers/pages/contributing.adoc
new file mode 100644
index 0000000..e4a4b0a
--- /dev/null
+++ b/doc/antora/modules/developers/pages/contributing.adoc
@@ -0,0 +1,126 @@
+= 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
+* 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.
+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.