Contributing

1. We use PRs for every change, except truly trivial ones.

2. The commit message of direct commits to master must end in (resolves # followed by the issue number followed by ).**

3. We strive to never break the build on master.

4. PRs are built automatically by Jenkins.

5. Ideally, a PR should contain a single commit that addresses a single, specific issue. Rebasing and squashing can be used to achieve that goal, but read the section on multi-author PRs below.

6. The branch name for a PR starts with issue- followed by the issue number, followed by a short, snake-case description of the change. There can be many open PRs with their associated branches at any given point in time and this convention ensures that we can easily identify branches.

7. The commit message of the first commit in a PR needs to end in (resolves # followed by the issue number followed by ).

8. The title of the PR needs to have the same (resolves #...) suffix as the commit message. This enables Waffle to stack the PR and the associated issue. Fortunately, GitHub automatically pre-populates the title of the PR with the message of the first commit in the PR, so this isn't additional work.

For example: Say there was an issue number 123 titled Foo does not work. The branch name should be issue-123-fix-foo and the title of the commit should be Fix foo in case of bar (resolves #123).

9. Until the PR is merged it should be continually rebased by the author on top of master.

10. We distinguish between author (the person filing the PR) and reviewer (the person to which the PR is assigned). Only the reviewer of a PR can merge it.

11. Multi-author PRs can have more than one commit. They must not be rebased because that would create havoc for the other contributors. To keep a multi-author PR up-to-date with master, merge from master instead of rebasing on top of master. A PR starts off as single-author and can be changed to multi-author upon request via comment (typically by the reviewer) in the PR. The author of a single-author has to explicitly grant the request. Before the PR is merged, it may transition back to single-author mode, again via comment request in the PR. Every contributor has to acknowledge the request after making sure they don't have any unpushed changes they care about. This is necessary because a single-author PR can be rebased and rebasing would make it hard to integrate these unpushed commits.