Commits should be signed, as explained in the GitHub documentation. This helps verify commits proposed in a pull request are from the expected author.
SecureDrop uses a branching model based on git-flow. The
branch always points to the latest stable release. Use this branch if you are
interested in installing or auditing SecureDrop. Development for the upcoming
release of SecureDrop takes place on
develop, which is the default
branch. If you want to contribute, you should branch from and submit pull
When a pull request is submitted, we have Circle CI automatically run the SecureDrop test suites, which consist of:
- Unit tests of the Python SecureDrop application code.
- Functional tests that use Selenium to drive a web browser to verify the function of the application from the user’s perspective.
- Tests of the system configuration state using testinfra.
Before a PR can be merged, these tests must all pass. If you modify the application code, you should verify the tests pass locally before submitting your PR. If you modify the server configuration, you should run the testinfra tests. Please denote in the checklist when you submit the PR that you have performed these checks locally.
We use code linters to keep a consistent code quality and style. These linters also run in CI and will produce build failures. To avoid this, we have included a git pre-commit hook. You can install it with the following command run at the root of the repository:
ln -sf ../../git/pre-commit .git/hooks/pre-commit
The code linters are installed automatically on the Development VM, but for the pre-commit hook to work, you will need to install the linting tools locally on your host machine. From the root of the repo you can run the following:
pip install -r securedrop/requirements/develop-requirements.txt
All Shell code (e.g.
sh) should be shellcheck
compliant. You can run
shellcheck locally via:
For reference, consult the shellcheck wiki for detailed explanations of any reported violations.
HTML should be in compliance with
Google’s HTML style guide.
We use html-linter to lint
our HTML templates in
securedrop/journalist_templates. Run the HTML linting options we use via:
We currently use an explicit merge strategy to merge feature branches into
develop. In order to keep our git history as clean as possible, please squash
your commits to package up your changes into a clear history. If you have
many unnecessary commits that do not add information to aid in review, they
should be removed. If you are unfamiliar with how to squash commits with rebase,
check out this
Dedicated contributors to SecureDrop will be granted extra privileges such as the right to push new branches or to merge pull requests. Any contributor with the right technical and social skills is entitled to ask. The people who have the power to grant such privileges are committed to do so in a transparent way as follows:
- The contributor posts a message in the forum asking for privileges (review or merge, etc.).
- After at least a week someone with permissions to grant such
privilege reviews the thread and either:
- grants the privilege if there are no objections from current maintainers and adds a message to the thread; or
- explains what is expected from the contributor before they can be granted the privilege.
- The thread is closed.
The privileges of a developer who has not been active for six months or more are revoked. They can apply again at any time.
- To aid in review, please write clear commit messages and include a descriptive PR summary. We have a PR template that specifies the type of information you should include.
- To maximize the chance that your PR is merged, please include the minimal changes to implement the feature or fix the bug.
- If there is not an existing issue for the PR you are interested in submitting, you should submit an issue first or comment on an existing issue outlining how you intend to approach the problem.