This page is a more detailed version of the parent page. It describes some items in more detail and provides rationale. You are supposed to read it once when you join Serokell, after that you can mostly use the parent page for reference.

Note: this page assumes that the repository in question is hosted on GitHub. However, even if it's not the case (for example, the repository is hosted on GitLab), virtually everything from this page should apply as well.

Branches

• The code in the master branch SHOULD always compile and pass all tests. Documentation SHOULD be up-to-date and have no broken links.
• Issue branches. Naming scheme: <username>/<issue_id>-<brief_description>.
  • Username SHOULD be GitHub user name. If you are well-known under a different nickname, using that nickname is acceptable.
  • For GitHub issues issue_id is # followed by a number. For YouTrack issues use lowercase letters and no dashes in issue_id.
  • If there is more than one related issue or more than one person working on an issue, concatenate them using dashes.
  • Use lowercase letters and dashes in brief_description.
  • 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-button
    • volhovm/srk322-eat-salad
    • gromak-pva228/lsd666-dscp42-refactor-ssc

Commit messages

• Follow this guide.
• Prefix the subject line with IDs of all relevant issues.
• If a commit is anything but a hot-fix, its body MUST contain a paragraph stating the problem ("Problem: …") being solved, and then the description of the proposed solution ("Solution: …").
• Example is provided below:

[#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.

Commit history

Ideal commit history should satisfy the following criteria:

• Each commit SHOULD be a minimal and accurate answer to exactly one identified and agreed problem.
• Each commit SHOULD NOT fix a problem introduced by an earlier commit in your pull request or revert an earlier commit in your PR.
• 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 can fix it in your PR.

Note, however, that during PR review your history doesn't have to satisfy these criteria. When you make a PR, commit history should be proper™. After that your history may be spoiled because PR reviewers will be interested to see how your PR evolved over time and see commits implementing their requested changes. However, future code readers will not be interested in everything that happened inside your PR during the review-fixup phase, so commits to be merged to the target branch should satisfy the above criteria.

See the Git hints section in the end of this doc if you have troubles making your history pretty.

PR ↔ issue relation

Each PR SHOULD resolve exactly one issue and each issue SHOULD be resolved by exactly one PR. So don't start working on more than one issue at once. There are legitimate cases when it doesn't hold though, for example: