archives/freedoom
2
0
Fork 0
mirror of https://github.com/freedoom/freedoom.git synced 2025-08-30 08:16:54 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

README: Use an external resource for Git commit message formating.

Browse source 
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:
Mike Swanson 2017-02-24 10:08:09 -08:00
parent 725df65022
commit 270d0f5219
1 changed files with 16 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

48
README.adoc
View file

@ -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
simplest, but by far not the only means.
Freedoom uses the commit message format commonly seen in distributed
version control systems, and adopted by high-profile projects such as
Linux and Git. The first line of a message needs to be a short
summary, preferably at a 72-character limit. The summary usually
begins with a short component name followed by a colon, this can be a
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.
Freedoom uses the commit message style commonly seen in distributed
version control systems, adopted by projects such as Linux and Git.
For an explanation of this style, see
https://chris.beams.io/posts/git-commit/[How to Write a Git Commit
Message].
Additionally, do not use commit hashes to refer to other commits. Use
other kinds of pointers, simple ones like “my previous commit” might
suffice, or use http://esr.ibiblio.org/?p=3872[action stamps], which
can improve the meaningfulness of commit identifiers if the repository
history is 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 (July 2015), core Git does not yet have a
mechanism to output this format, but you may use a
The commit `2017-02-20T01:52:35Z!mikeonthecomputer@gmail.com` is a
good example of a properly-written commit.
Do not use commit hashes to refer to other commits. Use other kinds
of pointers, simple ones like “my previous commit” might suffice, or
use http://esr.ibiblio.org/?p=3872[action stamps], which can improve
the meaningfulness of commit identifiers if the repository history is
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
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.