We are moving the source for the contents of the old pfSense® Wiki to GitHub. This is not a light decision, and has been in the works for some time.

First and foremost, thank you to any and everyone who has contributed to the pfSense Wiki. We appreciate your support and look forward to more in the future.

Why the Move

Ultimately, we made the switch because it was the right thing to do. Specifically, there were several reasons for this move, including:

  • GDPR Compliance - We don’t have to worry about storing any personal information about contributors and contributors don’t have to worry about creating an account with a limited use case (assuming they use their github account for other projects).
  • Technical Debt - We have already standardized our documentation around sphinx so this allows us to deprecate a mediaWiki server, reducing the cost of maintaining a unique codebase.
  • Quality Assurance - Much like the pfSense project itself, this documentation workflow allows us to approve and comment on contributions before they are submitted, versus after – as is the case with a typical wiki.

What Changed

  • Development Model - We have moved from a contribution model that allows changes to be made first and then repaired after the fact. The new model is submission-based (in the form of a Pull Request) and when approved, the changes are in place. This workflow functions much like that for open-source software, gaining its many benefits.
  • Content - As far as the content goes, it is largely the same, but is now better organized and categorized.
  • Content Management - Instead of using mediaWiki, we now use sphinx to generate a static HTML version of the documentation, based on the reStructuredText source files contained on GitHub.
  • Contributing - Given that the content management has changed, the workflow for contributing has also changed. You can find updated instructions on how to contribute to the documentation in CONTRIBUTING.md.
  • The URL - It will now be located at https://docs.netgate.com/ as that locations dovetails nicely with the rest of our other documentation and doesn’t require spinning up another server.

How it Works

We use continuous integration and deployment methodologies to make the process of verifying and deploying changes as frictionless as possible.

Continuous Integration using Travis-CI

Continuous Integration is basically integrating your newest addition of code, or markup language, into the rest of the project and running a series of tests to make sure it behaves as expected. In the case of a sphinx project, the most important test is to lint the submitted reStructuredText to make sure it has correct syntax.

Not only can you configure Travis-CI to run on the master branch, but it also supports running integration tests on all pull requests before they are to be merged.

Travis-CI integrates with GitHub so you can see the build status on each commit or PR and wether or not the build it triggered passed or failed, which helps tighten the feedback loop for each contribution.

Continuous Deployment using Netlify

To create the continuous deployment portion of the pipeline, GitHub commits and pull requests can trigger Netlify builds, and more importantly a deployments, so that the changes can be reviewed in a staging environment that mimics production. This allows the contributors to confirm the changes they made show up as they expected, as well as the maintainers.

We look forward to further improving the pfSense Documentation, if you have any general questions about the process feel free to start a thread on the forum.