New Contributor Process
Code changes must done with great caution, since ill-considered changes might unintentionally compromise the software's security.
We currently use GitHub for managing changes to the codebase. If you are unfamiliar with Git or GitHub, there are many tutorials and explanations on the GitHub website and the Internet. Feel free to also ask us; let us help you help us!
To get started on contributing code to the CipherShed project, simply follow these steps:
Fork the project on GitHub to your own account.
- Clone the repository to your local machine from your own account's fork.
- Code away! Make a branch (or several) if you so desire. Commit to your fork.
When finished, submit a pull request through GitHub. The pull request will allow comments and display a changelog for us to review.
- The team will review your changes and respond to you. You can make further commits to the same branch and they will automatically be included in the pull request.
If you have questions about the status of your pull request which have not been answered on Github, please send an email to the devs list.
Each modification of code must be well-documented. Changes to the master repository must sent as a pull request through GitHub. Pull requests won't be approved immediately (expect at least a week) to allow time for our security team to review it. This review process verifies that:
- No security issues are, intentionally or unintentionally, added to the code.
- The new code follows our coding guidelines and conventions.
- The new code has sufficient comments. Not every line must be commented, but the algorithm and information flow should be explained.
- Pull requests should be atomic. As in, work on one thing at a time and don't mix up issues/features. Create multiple branches if necessary.
- Please be descriptive, utilize in-line comments, and stay involved in discussions regarding your code.
Please use our GitHub issue tracker.
Don't worry about hiding the sausage-making. Meaning, commit often and worry about perfecting it later.
- Don't be intimated or discouraged by our code, procedures, or workflow. We're nice people, and we smack those who aren't! :-P Don't be afraid to ask questions; we'll help you help us!
Management of the Git Repository
The contributors managing the git repository on Github generally follow Nvie's model for branching and merging in git. Please read this if you want to understand our model. Only how we differ from this model is documented here.
Three Types of Contributors
The heart of our security model is careful code review. To aid this process, there are three different "types" of developers, who assume different roles in this review process.
- We have a "Security Team" of four people, in three different countries, who carefully review all changes between releases. Only ST members are allowed to edit the "master" branch, or the "review" branch. All changes in all releases are reviewed by at least 3 ST members.
"Official" ChiperShed developers are the contributors listed on our Github CipherShed/CipherShed project and who are members in our Redmine issue tracking system. In general, they are developers from the community who have made substantial contributions. They are expected to understand our development methodologies, and help create and update them over time. They may create feature and release branches, develop code, commit changes, and merge between branches. However, unless they are also ST members, they may not modify "master" or "review". They may respond to pull requests from the wider CipherShed community of unofficial developers. They are expected to review pull requests for conformance with our methodologies, and merge changes into the appropriate branch.
The third type are "new" developers, who can be anyone who would like to contribute code to CipherShed. The process for this is to fork our CipherShed repository on Github, commit your changes to that branch, and then submit a pull request to the "develop" branch (see below for details on the branches).
Becomming an "official" member is easy. Simply write code, and become a valuable contributor. We currently have over 100,000 lines of code to rewrite, and if you feel you can aid in that effort, please join the community!
Branch Naming Convention
We deviate slightly from Nvie's model in how we name branches. Our branches are:
- Master is used exactly as in Nvie's model, exactly as in Nvie's model. Only ST members are allowed to edit master. All future commits to master will be signed releases.
- Develop is used exactly as in Nvie's model.
- Release branches are exactly the same as Nvie's model, excet that we append functional names, such as "release-0.7.3-rebranding"
- The "review" branch simply aids the ST in reviewing code. Only the ST is allowed to modify "review", and all commits are to be signed by the ST member pulling the changes. Before a release, the review branch and release branch must converge to identical code.
Feature branches have to refer to an open issue on our issue tracker (Redmine) by using the following naming format: "I<IDs>-feature-name". E.g. "I10-two-factor", which would address Issue #10 on Redmine.
Future "develop-<identifier>" branches, such as "develop-audit" are branches where collaborators can work on future releases, without disturbing the "develop" branch. They are merged into "develop" just like feature branches, and effectively are "feature" branches according to Nvie's model. They simply provide a place to merge and test multiple feature branches before merging into "develop".
All merges into develop (or a future release develop-XXX branch) must be signed by the contributor doing the merge. However, individual commits in a feature branch do not have to be signed. When signing a merge, a contributor confirms that she has carefully reviewed all changes in her commit.
All future commits to the "master" and "review" branches have to be be digitally signed by an ST member.