From 270d0f5219f62fde30a2eb8338e6aae27389f30e Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Fri, 24 Feb 2017 10:08:09 -0800 Subject: [PATCH] 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. --- README.adoc | 48 ++++++++++++++++-------------------------------- 1 file changed, 16 insertions(+), 32 deletions(-) diff --git a/README.adoc b/README.adoc index f39b8a57..acc272b7 100644 --- a/README.adoc +++ b/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 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.