Skip to content

Commit

Permalink
Refocus our commit message guidance
Browse files Browse the repository at this point in the history
Our previous commit message guidance copy and pasted 7 formatting rules from a
blog post. These make for good general advice but I don't think we'd hold up a
merge if a user ended their subject line with "." or wrote in the past tense.

This commit strips the message standard back to the questions that good commit
messages answer, a preference for one commit per PR, and the most important
of the 7 formatting rules. I've kept the link to the blog post as guidance for
folks who have not written many commit messages before or simply aren't familiar.

I've also added a commit message example that hopefully can act as a template
developers can copy / paste if they're having trouble constructing the message.
  • Loading branch information
Scott authored and tekton-robot committed Oct 7, 2021
1 parent 776c1a1 commit 0a73bb9
Showing 1 changed file with 34 additions and 16 deletions.
50 changes: 34 additions & 16 deletions standards.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Each Pull Request is expected to meet the following expectations around:

* [Pull Request Description](#pull-request-description)
* [Commits](#commits)
* [Example Commit Message](#example-commit-message)
* [Docs](#docs)
* [Functionality](#functionality)
* [Content](#content)
Expand All @@ -36,22 +37,39 @@ _See also [the Tekton review process](https://github.com/tektoncd/community/blob

## Commits

* Follow [commit messages best practices](https://chris.beams.io/posts/git-commit/):
1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how. Don't just link to an issue and
[aim for 2 paragraphs](https://www.youtube.com/watch?v=PJjmw9TRB7s), e.g.:
* What is the problem being solved?
* Why is this the best approach?
* What other approaches did you consider?
* What side effects will this approach have?
* What future work remains to be done?
* Prefer one commit per PR; if there are multiple commits, ensure each is
self-contained and makes sense without the context of the others in the PR
* Use the body to explain [what and why vs. how](https://chris.beams.io/posts/git-commit/#why-not-how).
Link to an issue whenever possible and [aim for 2 paragraphs](https://www.youtube.com/watch?v=PJjmw9TRB7s),
e.g.:
* What is the problem being solved?
* Why is this the best approach?
* What other approaches did you consider?
* What side effects will this approach have?
* What future work remains to be done?
* Prefer one commit per PR. For multiple commits ensure each makes sense without the context of the others.
* As much as possible try to stick to these general formatting guidelines:
* Separate subject line from message body.
* Write the subject line using the "imperative mood" ([see examples](https://chris.beams.io/posts/git-commit/#imperative)).
* Keep the subject to 50 characters or less.
* Try to keep the message wrapped at 72 characters.
* Check [these seven best practices](https://chris.beams.io/posts/git-commit/#seven-rules) for more detail.

### Example Commit Message

Here's a commit message example to work from that sticks to the spirit
of the guidance outlined above:

```
Add example commit message to demo our guidance
Prior to this message being included in our standards there was no
canonical example of an "ideal" commit message for devs to quickly copy.
Providing a decent example helps clarify the intended outcome of our
commit message rules and offers a template for people to work from. We
could alternatively link to good commit messages in our repos but that
requires developers to follow more links rather than just showing
what we want.
```

## Docs

Expand Down

0 comments on commit 0a73bb9

Please sign in to comment.