Skip to content

Commit

Permalink
Clarify commit standard
Browse files Browse the repository at this point in the history
  • Loading branch information
lindenmckenzie committed Feb 4, 2025
1 parent de7adfc commit 9dee812
Showing 1 changed file with 9 additions and 2 deletions.
11 changes: 9 additions & 2 deletions COMMIT_STANDARDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,15 @@ Writing good commit messages is important. Not just for yourself, but for other
- people in the public (remember, we code in the open) who want to see our work, or learn from our practices
- any future developers (including yourself) who want to see why a change was made

A good commit message briefly summarises the "what" for scanning purposes, but also includes the "why". If the "what" in the message is not enough, the diff is there as a fallback. This is not true for the "why" of a change - this can be much harder or impossible to reconstruct, but is often of great significance.
A good commit message should:

- summarise the "what", providing a concise, scan-friendly headline that captures the essence of the change.
- explain the "why" by including details in the message body that clarify the motivation behind the change. While the code diff shows what changed, the reasoning often isn't apparent.
- follow a consistent format by using the imperative mood (e.g. "Add", "Fix", "Update") to give a clear, action-oriented description.

## Merging and squashing

When working on a feature branch, your branch may become out of date with it's parent. To update your branch we prefer a rebase here to a merge commit as we prefer a clean and straight history on the parent branch. However, this can be difficult for reviewers to track changes if done in between reviews. Please check with your reviewer before doing so. This is also true for tidying up commit histories and messages.
When working on a feature branch, it's common for your branch to become outdated relative to its parent. We prefer to update your branch by rebasing rather than merging. Rebasing offers a cleaner, linear history on the parent branch, which is easier to follow. However:

- Coordinate with Reviewers/Team: Rebasing during an active code review can complicate the review process. Always check with your reviewer/team style guide before rebasing or tidying up commit histories.
- Use Squashing Judiciously: Squash commits when it makes sense to consolidate minor, related changes into one atomic commit. Just ensure that you retain enough detail in the commit message to explain the consolidated changes.

0 comments on commit 9dee812

Please sign in to comment.