This document is supposed to be used as a reference. You can find an extended version with rationale, more detailed workflow, and some hints on the following page:
Where and how to commit your work
1.1. The master branch:
1.1.1. The code in the master branch SHOULD always compile and pass all tests.
1.1.2. The documentation in the master branch SHOULD always be up-to-date.
1.2. Issue branches:
1.2.1. Naming scheme: <username>/<issue_id>-<brief_description>.
1.2.2. Make sure the description is really brief but clear enough so that it is easy to understand what the issue is about without looking it up in the issue tracker (assuming that you are familiar with existing issues).
Examples:
gromakovsky/#228-add-yellow-buttonvolhovm/srk322-eat-saladgromak-pva228/lsd666-dscp42-refactor-ssc1.3. Pull requests:
1.3.1. Each pull request SHOULD resolve exactly one issue and each issue SHOULD be resolved by exactly one PR.
1.3.2. Try to avoid too big PRs. If your PR has more than 500 additions + deletions, please think twice whether it can be split into smaller PRs.
1.3.3. PR title SHOULD adhere to the following scheme: [ISSUE-ID] Brief description.
1.3.4. PR description MUST NOT be empty. If there is a PR template, PR description MUST adhere to this template. If there is no template, please describe the changes you've made and why you've made them. Also, provide links to related issues.
1.3.5. You SHOULD request a review from two persons you think would be most suitable as reviewers. You MAY request a review from only one person if it is acceptable by the repository policy and if the changes are very simple. You MAY request a review from more people if the changes are substantial – use your discretion.
1.3.6. Keep in mind that review might be automatically requested from codeowners when you actually create a PR. Make sure to review list of reviewers after pressing the Create pull request button.
2.1. An ideal commit history should satisfy the following criteria:
2.1.1. Each commit MUST adhere to the commit guidelines (#3).
2.1.2. Each commit SHOULD be a minimal and accurate answer to exactly one identified and agreed problem.
2.1.3. Each commit SHOULD NOT fix a problem introduced by an earlier commit in your pull request or revert an earlier commit in your PR.
2.1.4. Each commit SHOULD be signed.
2.1.5. Your pull request generally shouldn't contain changes unrelated to the issue it solves. However, if you modify some file and see an obvious small mistake there (e. g. a typo or wrong formatting), you MAY fix it in your PR.
2.2. Upon submitting a pull request, ensure the commit history satisfies the criteria listed in 2.1.
2.3. During the PR review:
2.3.1. Make changes in separate commits, even if such commits do not comply with 2.1 or 3.
2.3.2. You MUST NOT amend the previous commits.
2.3.3. You SHOULD NOT use force-push unless you're pushing the same commits rebased on the newer version of the target branch.
2.3.4. You SHOULD periodically synchronize your issue branch with the target branch.
2.3.5. You SHOULD use rebase to synchronize the branches.
2.3.6. You SHOULD NOT use "Update branch" or merge to synchronize the branches unless rebasing is prohibitively hard.
2.4. After passing the review but before merging:
2.4.1. Rebase your changes on the target branch.
2.4.2. Use the interactive rebase to prettify the commit history so that it adheres to 2.1.
2.5. Merging the changes:
2.5.1. If you want to merge someone else's PR, you SHOULD make sure the author is fine with merging and does not want to do anything with the commit history. If the repository is hosted on GitLab, the author's self-approval implies they are fine with merging.
2.5.2. You MUST create a merge commit, i.e. you MUST NOT use neither fast-forward merge nor "squash and merge". Exception: you MAY use "squash and merge" if the PR has exactly 1 commit.
3.1. The rules in this section apply to:
3.1.1. Commits that a PR contains upon submission.
3.1.2. Commits that are going to be merged into the target branch.
3.2. Each commit message MUST have a subject line (header) and a body, separated with a blank line.
3.3. Subject line:
3.3.1. Prefix the subject line with IDs of all relevant issues: [GHC-8], [#4] if they are accessible by all people with access to the repository.
3.3.2. Start with an uppercase letter.
3.3.3. Try to limit the subject line to 50 characters; the hard limit is 72 characters.
3.3.4. Do not end the subject line with a period.
3.3.5. Use the imperative mood in the subject line.
3.4. Message body:
3.4.1. Start with Problem: and describe a problem that the commit solves.
3.4.1. Continue with Solution: and describe how the commit addresses the problem.
3.4.3. Add additional context if you wish.
Examples:
GOOD:
[#453] Switch from avada-kedavra to expelliarmus
Problem: `avada-kedavra` library that we use to kill unwanted
process instances has a negative side-effect: it tears
programmers' souls apart. There's currently no mitigation
of this issue according to: (link to the developer issue
tracker).
Solution: Use a simpler `expelliarmus` library that blocks
process instances from performing any effects. Garbage-collect
blocked processes using the `kill` syscall.
BAD:
[#453] Switch from avada-kedavra to expelliarmus[#453] Change the killer lib[#453] Get rid of avada-kedavra in favor of expelliarmus because the former has some negative side-effects that are too long to explain in the commit header[#453] Update killer Problem: we need a new lib Solution: switch to the new lib