From f5ec0f2c1b406c34d53ddd7bfdbccd2f13daeb36 Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sun, 7 Apr 2024 11:44:35 +0200 Subject: [PATCH] DOCS: Fix headlines, Add general intro We had two level-one headlines. Add a document-level headline and intro text (without an intro text it would be quite empty). Indent every over headline by one level to have correct, consistent levels. The intro text provides general context even without specific technical knowledge about the document context. Although it does not introduce the connection between Git and commit. --- COMMIT_GUIDELINES.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/COMMIT_GUIDELINES.md b/COMMIT_GUIDELINES.md index eca28310a7a..e927a1a6a02 100644 --- a/COMMIT_GUIDELINES.md +++ b/COMMIT_GUIDELINES.md @@ -1,4 +1,11 @@ -# General philosophy +# Mumble Commit Message Guidelines + +A commit groups file changes with a title and description of the changes and additional metadata like change date, author, and committer. + +These Commit Message Guidelines define and describe how changes shall be structured and described in commits. +Most notably, the text form in which to title the changes. + +## General philosophy - **Each change goes into its own commit**. If you want to summarize what you did with this commit (in the commit message) and you start using the word "and", you probably want to split the commit up into 2 or more individual commits. @@ -10,7 +17,7 @@ each commit). Also if you put effort into the commit-message, you'll save work when creating a PullRequest as the description is already available. -# Commit message +## Commit message Commit messages must follow this scheme: @@ -26,7 +33,7 @@ The blank lines in between are mandatory. A commit **must** include a `TYPE` and additionally contain any of the other components listed here. -## Subject line +### Subject line The first line ("Subject line") should not exceed 50-70 characters. This is what gets displayed on GitHub at first glance, so it should contain the most important information. In order for it to be as short and precise as possible, there is the `TYPE` and @@ -34,7 +41,7 @@ optionally a `Scope`. With these it should already be clear what this commit is then include further information that is important to understand the general idea of this commit at a glance. -### TYPE +#### TYPE The `TYPE` is one of the following: @@ -60,13 +67,13 @@ If you feel like you need to use 2 or more types for a single commit but *can't combine types with `/`: `FEAT/CI: ` -### Scope +#### Scope What area is the change about. For now we don't have fixed scope keywords. A scope could be something like `ui`, `client`, `server`, `ice`, ... -### Summary +#### Summary The `Summary` is the heart of the subject line. It should contain a **very brief** summary of what you did in that commit. In order to make this as short as possible, you may use grammatically incorrect sentences @@ -79,7 +86,7 @@ If your `Summary` contains "and", you should probably split your commit up. Note: Issue references (such as #2305) **must not** be used in the `Summary`! -## Message Body +### Message Body Here you give more details about the commit. Why is it necessary and what are the details of the change. You can use multiple paragraphs for this and be as verbose as you want. @@ -91,7 +98,7 @@ The `Message Body` should contain enough information for someone to be able to l future and know exactly what it does and why it was needed. -## Footer +### Footer The `Footer` contains a list of issue references prefixed by a keyword like `Closes`, `Fixes` or `Implements`. @@ -111,7 +118,7 @@ Co-Authored-By: Other author ``` -## References +### References We have used the term "reference" a few times in these guidelines. A *reference* has the form `#` where `` is the ID GitHub assigns to the respective issue or PullRequest (it's the number that is displayed next to the title). You'll @@ -120,7 +127,7 @@ automatically by GitHub. You don't have to use a link in your commit message. In this purpose as this is just unnecessarily verbose and makes it hard to read the commit message outside of GitHub. -## Examples +### Examples ``` FEAT(client): Add possibility to change username