From 50b37d4a27d3295a29afca2286f1a5a086142cec Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 11:49:46 +0200 Subject: Adding upstream version 3.2.1+dfsg. Signed-off-by: Daniel Baumann --- doc/developer/contributing.rst | 127 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 doc/developer/contributing.rst (limited to 'doc/developer/contributing.rst') diff --git a/doc/developer/contributing.rst b/doc/developer/contributing.rst new file mode 100644 index 0000000..b40f98c --- /dev/null +++ b/doc/developer/contributing.rst @@ -0,0 +1,127 @@ +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. -- cgit v1.2.3