Skip to content

Latest commit

 

History

History
101 lines (68 loc) · 4.45 KB

CONTRIBUTING.md

File metadata and controls

101 lines (68 loc) · 4.45 KB
Raw

Coding standards

Version control

We use git repositories for all version control. We aim for a high standard of git commit hygiene on all shared branches, both in how changes are grouped into each commit, and in how the commit message is written. (This only applies to shared branches such as PR branches or upstream/master or other stable branches; obviously, every developer is free to do whatever they want with private changes in their personal repositories.)

Git commit grouping

We aim for a high standard in terms of how changes are grouped together into commits. As a brief summary, the following golden rules apply almost 100% of the time:

  • A commit should never break the tests or other CI

    • For example, it should not rely on another commit later in the same PR to fix a bug it introduces.

  • A commit should be as small as possible, but no smaller.

    • For example, when adding a new feature, the new tests for that feature should be in the same commit. Ideally the documentation should too, at least if the documentation changes are small.

  • A single commit should never mix unrelated changes.

    • For example, refactorings should never be mixed with bugfixes.

The following resources offer useful advice on this topic:

Git commit messages

We aim for high quality commit messages which always have both a title and a body, and always clearly explain the "why", i.e. the context and motivation for the change, not just the "how".

We adopt the Conventional Commits standard as a taxonomy for different types of commits, and to track compatibility according to SemVer principles.

The Perfecting the Patch YouTube video is highly recommended, as are the following resources:

Pull Request - code review

  • PRs SHOULD be submitted for each change, in order to ensure that all changes are checked by the CI pipeline.

  • For easy review, PRs SHOULD contain:

    • a clear title - in sync with the Liner ticket title

    • a description clearly explaining the "why", i.e. the context. If the issue tracker issue is linked from the PR it's not necessary to duplicate the description, but at least a high level should be given. In addition PR description should document how this has been solved, and why this approach was taken.

    • the CO2-123 identifier for any related issue in the linear.app issue tracker if applicable

    • a small number of commits (e.g. < 5)

  • Reviews should be requested from at least one other developer.

  • Feedback should generally be addressed by rewriting PR branch history to adhere to the git commit hygiene best practices documented above. For example, see:

  • Criteria for merging PRs:

    • All CI should be passing, unless there are exceptional circumstances justifying ignoring failures (e.g. an emergency hotfix to production code)

    • Reviews have been received, and feedback resolved to everyone's reasonable satisfaction.

Ignoring noisy git history

It is also recommended to configure git blame to ignore commits which were purely for fixing linting issues. You can do this by using the provided .gitblameignore file:

git config blame.ignoreRevsFile .gitblameignore