mirror of
https://github.com/freedoom/freedoom.git
synced 2025-09-01 04:25:45 -04:00
README: Use an external resource for Git commit message formating.
This section was rather bulky. I have my doubts of people using it for reference, but I'd rather have it here than not at all.
This commit is contained in:
parent
725df65022
commit
270d0f5219
1 changed files with 16 additions and 32 deletions
48
README.adoc
48
README.adoc
|
@ -254,38 +254,22 @@ However, pull requests are much appreciated and you may submit them in
|
||||||
any manner you wish, with GitHub's direct pull requests being the
|
any manner you wish, with GitHub's direct pull requests being the
|
||||||
simplest, but by far not the only means.
|
simplest, but by far not the only means.
|
||||||
|
|
||||||
Freedoom uses the commit message format commonly seen in distributed
|
Freedoom uses the commit message style commonly seen in distributed
|
||||||
version control systems, and adopted by high-profile projects such as
|
version control systems, adopted by projects such as Linux and Git.
|
||||||
Linux and Git. The first line of a message needs to be a short
|
For an explanation of this style, see
|
||||||
summary, preferably at a 72-character limit. The summary usually
|
https://chris.beams.io/posts/git-commit/[How to Write a Git Commit
|
||||||
begins with a short component name followed by a colon, this can be a
|
Message].
|
||||||
directory name (eg, `musics:`), a resource name (eg, `map17:`), or a
|
|
||||||
more generic component (eg, `build system:`). The summary line must
|
|
||||||
not bleed into a second line, and should not be the start of a lengthy
|
|
||||||
explanation. If the commit needs further explanation (and they often
|
|
||||||
do), use extra paragraphs and write in plain English what the commit
|
|
||||||
is about. The commit `2014-08-24T22:42:37Z!fraggle@gmail.com` is a
|
|
||||||
good example.
|
|
||||||
|
|
||||||
Additionally, do not use commit hashes to refer to other commits. Use
|
The commit `2017-02-20T01:52:35Z!mikeonthecomputer@gmail.com` is a
|
||||||
other kinds of pointers, simple ones like “my previous commit” might
|
good example of a properly-written commit.
|
||||||
suffice, or use http://esr.ibiblio.org/?p=3872[action stamps], which
|
|
||||||
can improve the meaningfulness of commit identifiers if the repository
|
Do not use commit hashes to refer to other commits. Use other kinds
|
||||||
history is rewritten (this has happened at least twice!), or if the
|
of pointers, simple ones like “my previous commit” might suffice, or
|
||||||
repository is converted to another VCS (this happened once before).
|
use http://esr.ibiblio.org/?p=3872[action stamps], which can improve
|
||||||
At the time of writing (July 2015), core Git does not yet have a
|
the meaningfulness of commit identifiers if the repository history is
|
||||||
mechanism to output this format, but you may use a
|
rewritten (this has happened at least twice!), or if the repository is
|
||||||
|
converted to another VCS (this happened once before). At the time of
|
||||||
|
writing (February 2017), core Git does not yet have a mechanism to
|
||||||
|
output this format, but you may use a
|
||||||
https://gist.github.com/chungy/195f53bfb9253584e596[shell script] and
|
https://gist.github.com/chungy/195f53bfb9253584e596[shell script] and
|
||||||
place it in your `$PATH` to achieve some ease in generating them.
|
place it in your `$PATH` to achieve some ease in generating them.
|
||||||
|
|
||||||
You should commit at each logical step. Do not bundle up many
|
|
||||||
unrelated changes into the same commit, and definitely do not write a
|
|
||||||
commit message like “changed some stuff.” Best judgment should be
|
|
||||||
used for what constitutes a logical step. It may be just a single
|
|
||||||
file, or it may be a group of files representing a monster in the
|
|
||||||
game. If you are finding yourself needing to repair previous commits'
|
|
||||||
blunders in your private repository, try to take advantage of Git's
|
|
||||||
ability to rewrite history , don't use `git revert`, just remove (`git
|
|
||||||
reset`), amend (`git commit --amend`), or rebase (`git rebase`) as
|
|
||||||
necessary. Leave all the interesting and important history bits,
|
|
||||||
leave out stupid mistakes like spell check errors if you catch them.
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue