Skip to content

Commit

Permalink
docs: expand the section on commit messages
Browse files Browse the repository at this point in the history
This comit expand on the commit messages section and makes it
more clear why they are important and what should be part of them.

There are many good guides on this so it's fine to keep this
brief but I think it was a little bit to concise :)

It also links to a good commit message example, I am open for
suggestions here though, while this is good (as pretty much any
from Christian) I'm sure there are even better ones.
  • Loading branch information
mvo5 committed Sep 25, 2024
1 parent afb789a commit c4f3672
Showing 1 changed file with 13 additions and 2 deletions.
15 changes: 13 additions & 2 deletions docs/developer-guide/01-general/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Commits 💎

1. Commits should be easy to read.
1. Commits should be easy to read and ideally do only a single thing.
2. The commit message should explain clearly what it's trying to do and why. Refer to the format we prefer below.
3. A Jira issue or - where applicable - a GitHub issue reference should be added to automatically link and potentially close a related issue if it exists.

Expand All @@ -11,12 +11,23 @@
```
<module>: Topic of the commit
Body of the commit, describing the changes in more detail.
Body of the commit, describing the changes in more detail including the
why/what/how.
```

- The `<module>` should point to the area of the codebase (for instance `tests` or `tools`). The topic
should summarize what the commit is doing.
- GitHub truncates the first line if it's longer than 65 characters, which is something to keep in mind as well.
- GitHub PR descriptions are disconnected from the actual `git`
history and will not show up in e.g. `git blame` or `git log` so consider
them more ephemeral.

A good commit message will help our future selfs to get back into the
context that the author had when writing the code. It should include
decisions/considerations/background that were important when the
commit was writen so that a `git show <commit>` provides a concise
way to (re)acquire this context. See [this](https://github.com/osbuild/osbuild/commit/a2e212bb2641cf28e5701ad4a2202261c2c5ee5c) as an example.


## Pull requests 🌟

Expand Down

0 comments on commit c4f3672

Please sign in to comment.