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
+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.
+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
--------------
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."
+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.
+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.
+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.
+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 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.
+If your commit includes significant whitespace changes these should also be
+broken out into another, separate, commit.
Submitting patches via GitHub
-----------------------------
~~~~~~~~~~~~
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.
+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::
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::
+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/
2. Select e-mail destination
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you are on the developers mailing list, send the patch there. freeradius-devel@lists.freeradius.org
+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.
+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.
+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.
+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.
+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.
+It is important to note, either in the subject line or in the patch
+description, the server version to which this patch applies.
projects / freeradius.git / commitdiff