From 51a7341b43460ca1a036411103a10a66e79e9e73 Mon Sep 17 00:00:00 2001 From: Jim Porter Date: Wed, 7 Feb 2024 22:08:08 -0800 Subject: [PATCH] * CONTRIBUTE (Commit messages): Improve wording about file entries. --- CONTRIBUTE | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTE b/CONTRIBUTE index 70b9760bb99..c942bfb3b8b 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -200,15 +200,21 @@ them right the first time, so here are guidelines for formatting them: - 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. - -- Lines in ChangeLog entries should preferably be not longer than 63 - characters, and must not exceed 78 characters, unless they consist - of a single word of at most 140 characters; this 78/140 limit is - enforced by a commit hook. +- If necessary, a paragraph describing the commit in more detail comes + next. Explaining the rationale for a design choice is best done in + comments in the source code. However, sometimes it is useful to + describe just the rationale for a change; that can be done in this + paragraph. If you include this paragraph, there should be another + empty line after it. + +- File entries come next. These begin with a "* " followed by the + file's name, the function or section that was changed in parentheses, + a ": ", and then a short description of the change. + +- Lines in the detailed paragraph and file entries should preferably be + not longer than 63 characters, and must not exceed 78 characters, + unless they consist of a single word of at most 140 characters; this + 78/140 limit is enforced by a commit hook. - 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 @@ -240,11 +246,6 @@ them right the first time, so here are guidelines for formatting them: - Any lines of the commit message that start with "; " are omitted from the generated ChangeLog. -- Explaining the rationale for a design choice is best done in comments - in the source code. However, sometimes it is useful to describe just - the rationale for a change; that can be done in the commit message - between the summary line and the file entries. - - Emacs generally follows the GNU coding standards for ChangeLogs: see https://www.gnu.org/prep/standards/html_node/Change-Logs.html or run 'info "(standards)Change Logs"'. One exception is that -- 2.25.1