forked from mumble-voip/mumble
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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.
- Loading branch information
Showing
1 changed file
with
17 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 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,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: | ||
|
||
|
@@ -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 | ||
|
@@ -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 <[email protected]> | |
``` | ||
|
||
|
||
## 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 | ||
|
@@ -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 | ||
|