From: Alan T. DeKok Date: Mon, 5 Jan 2026 10:37:06 +0000 (-0500) Subject: point to local documentation, and move email to a separate page X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=87e20ceecd05d34bfacdfb321ab8fa9fca8bf0d9;p=thirdparty%2Ffreeradius-server.git point to local documentation, and move email to a separate page --- diff --git a/doc/antora/modules/developers/nav.adoc b/doc/antora/modules/developers/nav.adoc index 8d301a8911c..07910d3e441 100644 --- a/doc/antora/modules/developers/nav.adoc +++ b/doc/antora/modules/developers/nav.adoc @@ -5,6 +5,8 @@ ** xref:profile.adoc[Profiling] ** xref:coccinelle.adoc[Semantic Patches] ** xref:contributing.adoc[Contributing] +*** xref:github.adoc[Send PRs via GitHub] +*** xref:email.adoc[Email] ** xref:coverity.adoc[Coverity] ** xref:module_interface.adoc[Module Interface] ** xref:release-method.adoc[Release Method] diff --git a/doc/antora/modules/developers/pages/contributing.adoc b/doc/antora/modules/developers/pages/contributing.adoc index e041667e352..2e8ace1c3e8 100644 --- a/doc/antora/modules/developers/pages/contributing.adoc +++ b/doc/antora/modules/developers/pages/contributing.adoc @@ -46,84 +46,15 @@ be broken out into another, separate, commit. == Submitting patches via GitHub -See the following links for more details about submitting via github: +See the xref:github.adoc[GitHub] page for how to contibute patches via +GitHub. -* https://help.github.com/articles/fork-a-repo -* https://wiki.freeradius.org/contributing/GitHub +Some additional documentation specific to Github is at https://help.github.com/articles/fork-a-repo == 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. +See the xref:email.adoc[email] page for how to contibute patches via +email. In short: don't. // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/email.adoc b/doc/antora/modules/developers/pages/email.adoc new file mode 100644 index 00000000000..bcf2660f2bb --- /dev/null +++ b/doc/antora/modules/developers/pages/email.adoc @@ -0,0 +1,79 @@ += Submitting patches via email + +We _strongly_ prefer to see patches via xref:github.adoc[GitHub]. +Email should only be used when it is impossible to use GitHub. + +== 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:freeradius-users@freeradius.org[freeradius-users@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. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS.