** 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:github.adoc[Using GitHub]
+*** xref:gitpr.adoc[Patches via GitHub]
+*** xref:email.adoc[Diffs via Email]
** xref:coverity.adoc[Coverity]
** xref:module_interface.adoc[Module Interface]
** xref:release-method.adoc[Release Method]
= 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
+== Submit patches or diff's to the FreeRADIUS project
-=== 1. Describe your changes
+GitHub is the preferred method for submitting code changes. You can email small diffs for a single change or file. For big changes, like a large patch or modifying several files, submit a pull request to the project’s GitHub repository. This approach helps the FreeRADIUS team manage contributions more effectively. It ensures that large or complex changes are properly tracked and discussed.
-Describe the technical detail of the change(s) your patch or commit
-includes.
+=== *Describe your changes*
-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."
+Describe the technical details of the changes in your patch or commit.
-If your description starts to get long, that's a sign that you probably
-need to split up your commit. See the next point.
+Be as specific as possible. Avoid using vague descriptions like "update file X", "bug fix for file X", or "this patch updates subsystem X, please apply".
-=== 2. Separate your changes
+If your description gets too long, it may be a sign that you should split your commit, as explained in the next point.
-Separate each logical change into its own commit.
+=== *Separate your changes*
-For example, if your changes include both bug fixes and performance
-enhancements for a single module, separate those changes into two or
-more patches.
+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
If your commit includes significant whitespace changes these should also
be broken out into another, separate, commit.
-== Submitting patches via GitHub
-See the xref:github.adoc[GitHub] page for how to contribute patches via
+== Patches via GitHub
+
+See the xref:github.adoc[Using GitHub] page for how to contribute patches via
GitHub.
-Some additional documentation specific to Github is at https://help.github.com/articles/fork-a-repo
+Refer to https://help.github.com/articles/fork-a-repo[Forking GitHub repositories] for additional help on setting up your repository.
-== Submitting patches via email
+== Diffs via Email
See the xref:email.adoc[Email] page for how to contribute patches via
-email. In short: don't.
+email.
+
+[NOTE]
+====
+Only small 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].
+====
// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
-= Submitting patches via email
+= Diffs 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
+== Create the file with diff -u
Use `diff -u` or `diff -urN` to create patches.
diff -urN freeradiusd-version $MYSRC > ~/feature-version.patch
```
-== 2. Select e-mail destination
+== 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
+== 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`
to do additional work to read your patch, the odds are that it will be
ignored completely.
-== 4. E-mail size
+== 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
+== 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.
-= Submitting Patches via GitHub
-
-== Introduction
+= Using GitHub
GitHub is a social coding site allowing many developers to come together and work on projects simultaneously.
After cloning a repository you can create new branches and commit new revisions completely independently of the *upstream* repository. To distribute and receive changes you can use the `git pull` command (to get new commits from remote repositories), and `git push` command (to send your commits to remote repositories).
-== Installing Git
+== Install Git
-See https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+Before you start using Git, you need to https://git-scm.com/book/en/v2/Getting-Started-Installing-Git[install Git] on your computer. Update to the current version to get the latest features and security patches. Git can be installed as a package, or you can use another installer that simplifies the process.
-== Getting a GitHub account
+For windows-based machines, https://git-scm.com/download/win[download] the official build and install Git.
-In order to follow or fork a project you must first create a GitHub account. The current signup url is https://github.com/signup/free and the process is pretty straight forward. After you've signed up, log in and you're good to go.
+== Get a GitHub account
-Another advantage of having a GitHub account is its one of the providers this wiki supports for login, so even if you never contribute to the source code of the server, you'll still be able to help out be adding wiki content.
+In order to follow or fork a project you must first create a GitHub account. Navigate to the https://github.com/signup/free[signup page] and enter your details to complete this process. After you've signed up, log in and you're good to go.
-== Authorising your local machine to talk to GitHub
+== Authorise your local machine to talk to GitHub
In order to let your local machine talk to GitHub, you must first lodge the public portion of a RSA keypair with the GitHub servers.
=== What is a RSA keypair?
-See http://en.wikipedia.org/wiki/Public-key_cryptography and http://en.wikipedia.org/wiki/RSA
+An http://en.wikipedia.org/wiki/RSA[RSA] keypair has two linked keys: a http://en.wikipedia.org/wiki/Public-key_cryptography[public key and a private key]. The public key can be shared openly and it encrypts data and verifies digital signatures. The private key must remain secure and it decrypts data and creates digital signatures. RSA's security depends on the hard task of factoring large numbers. This makes it popular for secure communication.
=== How do I generate a keypair?
----
* Copy the key (making sure you don't accidentally get bits of command prompts).
-* On the GitHub site go to [[Account Settings->SSH Public Keys|https://github.com/account/ssh]], then click the *Add another public key* link.
+* On the GitHub site go to https://github.com/account/ssh[Account Settings->SSH Public Keys], then click the *Add another public key* link.
* Enter a Title for the key (this is arbitrary, just enter your machine's hostname or any other value you want).
-* Paste your public key into the Key field
-* Click *Add key*
+* Paste your public key into the Key field.
+* Click *Add key*.
== Linking commits with your GitHub account
git config --global user.email "<Email you used to signup with GitHub>"
----
-== Forking
+== Forking the FreeRADIUS Server
In order to contribute code you must first fork the server. Forking is the process of creating your own copy of the FreeRADIUS repository on GitHub, which you can *clone*, and then *push* your modifications to.
To fork the FreeRADIUS server
-* Login to GitHub
-* Go to the [[project site|https://github.com/FreeRADIUS/freeradius-server]]
+* Login to https://github.com[GitHub].
+* Navigate to the https://github.com/FreeRADIUS/freeradius-server[project site].
* Click the 'Fork' button.
-You'll see the current URL change to ``/<your github username>/freeradius-server`` this means you're now browsing your own copy of the FreeRADIUS source code. From this point on changes to the *upstream* repository will not be reflected in your fork, unless you explicitly pull from the *upstream* repository using the local clone of your fork, and push back to GitHub.
+You'll see the current URL change to ``/<your github username>/freeradius-server`` this means you're now browsing your own copy of the FreeRADIUS source code. From this point on changes to the *upstream* repository won't be reflected in your fork, unless you explicitly pull from the *upstream* repository using the local clone of your fork, and push back to GitHub.
== Using your shiny new fork
GitHub doesn't allow you to login to their servers with an interactive prompt. Instead you must use one of the protocols Git supports (SSH, HTTP, or Git (native protocol)) to modify the contents of your fork, and in order to do that you must first *clone* it (create a copy of it on your local machine).
-=== Cloning
+=== Cloning your fork
* To clone your fork create a directory to house your repositories and navigate to it:
----
The reason why the FreeRADIUS core developers love GitHub is because of *pull requests*. Once you've committed a set of modifications to your fork, you can generate a *pull request* to let the core developers know you have code to merge.
-If your code merges cleanly, then its a couple of clicks to get it merged into the project repository. This is **significantly** easier for core developers, compared with applying mangled patches sent on the mailing lists.
-* Go to your fork on GitHub `https://github.com/<your github username>/freeradius-server`
-* Click the 'Pull request' button
-* Follow the instructions...
+Go to your fork on GitHub `https://github.com/<your github username>/freeradius-server`. Next, * Click the 'Pull request' button. For more guidance, see xref:gitpr.adoc#Open a Pull Request[Open a Pull Request]
==== Signing commits
-The FreeRAIDUS project now requires all contributions to be signed.
-
-Refer to the links below for instructions on how to enable this:
+The FreeRAIDUS project now requires all contributions to be signed. Refer to the following pages for instructions on how to enable this:
-- https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work
-- https://help.github.com/en/github/authenticating-to-github/signing-commits
+* https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work[Git Tools Signing]
+* https://help.github.com/en/github/authenticating-to-github/signing-commits[Sign Commits]
// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
--- /dev/null
+= Patches via GitHub
+
+To create a patch, you will open a pull request for the FreeRADIUS project on GitHub.
+
+Ensure you've followed the previous xref:github.adoc[Using Git] steps by forking the official repository, clone your fork locally, create a branch to make your changes on, and then open a pull request from your branch to the main project.
+
+== Open a Pull Request (PR)
+
+If your code merges cleanly, then it's a couple of clicks to get it merged into the project repository. This is **significantly** easier for core developers, compared with applying mangled patches sent on the mailing lists.
+
+Follow these steps to complete a PR:
+
+* Navigate to your fork on GitHub `https://github.com/ <your-github-username>/freeradius-server`
+* Click the "Compare & pull request" button or navigate to the *Pull Request* tab and click the "New Pull Request" button.
+
+[WARNING]
+====
+Ensure the base branch is the FreeRADIUS project's main branch (usually master or main) and the compare branch is the name-of-your-feature-branch from your fork.
+====
+
+* Add a title and description for your pull request, explaining the changes you made.
+*Click "Create pull request" (or "Create draft pull request") to submit your contribution.
projects / thirdparty / freeradius-server.git / commitdiff
