68 lines
1.8 KiB
Markdown
68 lines
1.8 KiB
Markdown
|
# Commit Messages
|
||
|
|
||
|
Commit messages should follow the guidelines in the [GNOME handbook][handbook].
|
||
|
Please make sure that you have read those recommendations carefully.
|
||
|
|
||
|
The following outlines the additional conventions that are used
|
||
|
in gnome-shell (and mutter).
|
||
|
|
||
|
[handbook]: https://handbook.gnome.org/development/commit-messages.html
|
||
|
|
||
|
## Example
|
||
|
|
||
|
```
|
||
|
status/volume: Automatically mute in vacuum
|
||
|
|
||
|
In space, no one can hear you scream. There is no point
|
||
|
in emitting sound that cannot be perceived, so automatically
|
||
|
mute all output streams.
|
||
|
|
||
|
Closes: https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/1234
|
||
|
```
|
||
|
|
||
|
## Description
|
||
|
|
||
|
Try to always prefix commit subjects with a relevant topic, such
|
||
|
as `overview:` or `st/actor:`. Less specific changes can use more
|
||
|
general topics such as `st` or `js`.
|
||
|
|
||
|
As a general rule, it is always better to write too much in the
|
||
|
commit message body than too little.
|
||
|
|
||
|
## References
|
||
|
|
||
|
References should always be expressed as full URL instead of the
|
||
|
`#1234` shorthand, so they still work outside the GitLab UI.
|
||
|
|
||
|
To close an issue automatically, we prefer the `Closes:` keyword
|
||
|
over the alternatives (see next section).
|
||
|
|
||
|
If a merge requests consists of multiple commits and none of them
|
||
|
fixes the issue completely, use the plain issue URL without prefix
|
||
|
as reference, and use the automatic issue closing syntax in the
|
||
|
description of the merge request.
|
||
|
|
||
|
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>
|
||
|
```
|