Submitting a Pull Request via GitHub

Submitting a Pull Request (PR) via GitHub is the fastest and best way to contribute source code changes to the pfSense® project.

Using a PR allows developers to easily review and comment on changes, allows easy testing via patches from the System Patches Package, and allows the changes to be easily merged into the project.

Creating a PR is a relatively straightforward process but we do have a few guidelines and suggestions to follow when submitting contributions:

  • Ensure the bug or feature has an entry on https://redmine.pfsense.org – Create a new entry if one does not exist

    • The only exceptions to this are for very minor typo/wording fixes or for FreeBSD-ports package updates that have already been given an OK/green light

  • Read through and follow the Developer Style Guide when making changes to the source code

  • Read through the GitHub documentation on pull requests

  • Create a fork of the correct repository (e.g. pfSense/pfSense for the base system, or pfSense/FreeBSD-ports for packages)

  • Always work on the master branch of the pfSense/pfSense repository or the devel branch of pfSense/FreeBSD-ports

    • The exception to this is when making PRs for multiple branches due to syntax or other differences which require variations that prevent a regular cherry-pick or similar from copying the commit to other branches

  • When making commits to the fork, reference the relevant Redmine entry as mentioned in Referencing Tickets in Commit Messages

  • When ready to submit the changes, create a pull request from the fork to the appropriate branch

    • The PR title should be a short summary of the changes and include a reference to the relevant Redmine issue number(s)

    • The PR description should include a longer explanation of the proposed changes and link to the relevant Redmine issue number(s)

  • After submitting the pull request, add a link to the PR on the related Redmine issue so the entries can be cross-referenced