diff options
| -rw-r--r-- | Help/dev/review.rst | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 985b1b7..be02a1a 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -195,6 +195,9 @@ Committers should aim to keep this first line short. Any subsequent lines should be separated from the first by a blank line and provide relevant, useful information. +Area Prefix on Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + The appropriateness of the initial word describing the area the commit applies to is not something the automatic robot review can judge, so it is up to the human reviewer to confirm that the area is specified and that it is @@ -209,6 +212,9 @@ message include: * ``Autogen: Extended mocInclude tests`` * ``cmLocalGenerator: Explain standard flag selection logic in comments`` +Referencing Issues in Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + If the commit fixes a particular reported issue, this information should ideally also be part of the commit message. The recommended way to do this is to place a line at the end of the message in the form ``Fixes: #xxxxx`` where @@ -228,6 +234,29 @@ other synonyms for ``Fixes`` and allows much more flexible forms than the above, but committers should aim for this format for consistency. Note that such details can alternatively be specified in the merge request description. +Referencing Commits in Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The preferred form for references to other commits is +``commit <commit> (<subject>, <date>)``, where: + +* ``<commit>``: + If available, a tag-relative name of the commit produced by + ``git describe --contains <commit-ish>``. Otherwise, the first + 8-10 characters of the commit ``<hash>``. + +* ``<subject>``: + The first line of the commit message. + +* ``<date>``: + The author date of the commit, in its original time zone, formatted as + ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. + +Alternatively, the full commit ``<hash>`` may be used. + +Revising Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^ + Reviewers are encouraged to ask the committer to amend commit messages to follow these guidelines, but prefer to focus on the changes themselves as a first priority. Maintainers will also make a check of commit messages before |