Skip to content

Commit

Permalink
DOCS: Fix headlines, Add general intro
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
Kissaki committed Apr 7, 2024
1 parent 2382408 commit a67ea7e
Showing 1 changed file with 17 additions and 10 deletions.
27 changes: 17 additions & 10 deletions COMMIT_GUIDELINES.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,11 @@
# General philosophy
# Mumble Commit Message Guidelines

A commit groups file changes with a title and description of changes and additional meta-data 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.
Expand All @@ -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:

Expand All @@ -26,15 +33,15 @@ 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
optionally a `Scope`. With these it should already be clear what this commit is about in general. The short `Summary` should
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:

Expand All @@ -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: <Summary>`


### 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
Expand All @@ -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.
Expand All @@ -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`.

Expand All @@ -111,7 +118,7 @@ Co-Authored-By: Other author <other@example.com>
```


## References
### References

We have used the term "reference" a few times in these guidelines. A *reference* has the form `#<ID>` where `<ID>` is the
ID GitHub assigns to the respective issue or PullRequest (it's the number that is displayed next to the title). You'll
Expand All @@ -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
Expand Down

0 comments on commit a67ea7e

Please sign in to comment.