9f5a323e06
We currently only have a very brief outline of the commit message conventions in the README. Improve on that by splitting out the relevant section into a separate file that outlines all conventions we use in addition to the general guidelines in the [handbook]. [handbook]: https://handbook.gnome.org/development/commit-messages.html Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3122>
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>
|
|
```
|