readme: Expand how to tag commit messages

It's a common mistake that links to issues being resolved are not URLs,
and that Part-of was added manually by contributors. Make it clear what
the expectations are regarding this. Formalize on `Fixes:` for fixing
commit messages, and `Closes:` for closing issues while at it. Format
and alias for generating `Fixes:` tags come from mesa.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2847>
This commit is contained in:
Jonas Ådahl 2023-02-16 09:45:08 +01:00
parent 4551bc6b86
commit 734b72099a

View File

@ -49,6 +49,45 @@ commit subjects with a relevant topic, such as `compositor:` or
`clutter/actor:`, and it's always better to write too much in the commit `clutter/actor:`, and it's always better to write too much in the commit
message body than too little. message body than too little.
If a commit fixes an issue and that issue should be closed, add URL to it in
the bottom of the commit message and prefix with `Closes:`.
Do not add any `Part-of:` line, as that will be handled automatically when
merging.
### The Fixes tag
If a commit fixes a regression caused by a particular commit, it can be marked
with the `Fixes:` tag. To produce such a tag, use
```
git show -s --pretty='format:Fixes: %h (\"%s\")' <COMMIT>
```
or create an alias
```
git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"
```
and then use
```
git fixes <COMMIT>
```
### Example
```
compositor: Also consider dark matter when calculating paint volume
Ignoring dark matter when calculating the paint volume missed the case where
compositing happens in complete vacuum.
Fixes: 123abc123ab ("compositor: Calculate paint volume ourselves")
Closes: https://gitlab.gnome.org/GNOME/mutter/-/issues/1234
```
## Default branch ## Default branch
The default development branch is `main`. If you still have a local The default development branch is `main`. If you still have a local