* CONTRIBUTE: Improve commit message instructions

This commit is contained in:
Karl Fogel 2021-12-02 20:38:25 -06:00
parent e0ee1d003a
commit f35d6a9c73

View file

@ -185,20 +185,26 @@ ChangeLog file, where they can be corrected. It saves time to get
them right the first time, so here are guidelines for formatting them: them right the first time, so here are guidelines for formatting them:
- Start with a single unindented summary line explaining the change; - Start with a single unindented summary line explaining the change;
do not end this line with a period. If that line starts with a do not end this line with a period. If possible, try to keep the
semicolon and a space "; ", the commit message will be ignored when summary line to 50 characters or fewer; this is for compatibility
generating the ChangeLog file. Use this for minor commits that do with certain Git commands that print that line in width-constrained
not need separate ChangeLog entries, such as changes in etc/NEWS. contexts.
- After the summary line, there should be an empty line, then If the summary line starts with a semicolon and a space "; ", the
unindented ChangeLog entries. commit message will be ignored when generating the ChangeLog file.
Use this for minor commits that do not need separate ChangeLog
entries, such as changes in etc/NEWS.
- After the summary line, there should be an empty line.
- Unindented ChangeLog entries normally come next. However, if the
commit couldn't be properly summarized in the brief summary line,
you can put a paragraph (after the empty line and before the
individual ChangeLog entries) that further describes the commit.
- Limit lines in commit messages to 78 characters, unless they consist - Limit lines in commit messages to 78 characters, unless they consist
of a single word of at most 140 characters; this is enforced by a of a single word of at most 140 characters; this is enforced by a
commit hook. It's nicer to limit the summary line to 50 characters; commit hook.
this isn't enforced. If the change can't be summarized so briefly,
add a paragraph after the empty line and before the individual file
descriptions.
- If only a single file is changed, the summary line can be the normal - If only a single file is changed, the summary line can be the normal
file first line (starting with the asterisk). Then there is no file first line (starting with the asterisk). Then there is no