Coding Conventions

Git Conventions

Good commit messages and history are important, and required for seL4 projects.

Here is what you need to know.

This page outlines the conventions that should be used for git history in the projects under the seL4 GitHub org. Note that this applies to pull requests where the content is ready to be merged. If you are raising a pull request for feedback only, you do not need to follow the history conventions, but please note this in the description of the pull request to avoid confusion. Please also read the pull request guidelines.

We will review the history in pull requests that are ready to be merged. If you need help with git, or advice on how to structure your history, please reach out.

Note that our work-flow is a fork-rebase workflow.

Commit messages

Please follow the git commit style guide. Briefly:

  • Use a subject line to summarise the commit.
  • Limit the subject line to 50 characters.
  • Capitalise the subject line.
  • Avoid ending the subject line in a full stop.
  • Use the imperative mood in the subject line.
  • Check the repository history if it uses any obvious tagging conventions. Follow them if it does.
  • Follow this with a blank line, then a summary of why the changes are required, and if non-trivial, how they achieve their purpose.
  • Wrap the body at 72 characters.

Examples and counter-examples of the above rules can be found in the git commit style guide.

Whitespace and style

  • Please keep whitespace and style changes in their own commits, not mixed with other changes.
  • If making a trivial commit, please prefix with trivial:
  • Avoid making PRs that are only changing style and not making other significant changes. This avoids spending reviewer and CI resources on a large number of small stylistic improvements.

History

  • Merge commits are prohibited.
  • Revert commits which act on the contents of the PR are prohibited.
  • Commits should make the changes easier to follow: if you move a function and change it, please do so in separate commits.
  • Commits should be separated into functional, logical changes. If you find yourself writing a commit message which says ‘Fix X and clean up Y’, you should probably use two commits.

Further resources