diff options
| author | Ben Boeckel <ben.boeckel@kitware.com> | 2019-01-24 13:31:37 -0500 |
|---|---|---|
| committer | Ben Boeckel <ben.boeckel@kitware.com> | 2019-01-25 12:10:10 -0500 |
| commit | 939dc9a58c5667ea18809c3a5e97ef1b60eb746c (patch) | |
| tree | 3916445adce8b6282367c9fa7ae4a868dd7c6ee1 /Help/dev/review.rst | |
| parent | 378473f9f184000cb768c1b99e6242e054787f34 (diff) | |
| download | cmake-939dc9a58c5667ea18809c3a5e97ef1b60eb746c.tar.gz | |
Help: prefer commit hashes in commit references
The logic is that the describe output is readily available using `git
tag --contains` locally. In addition, for a hypothetical commit which
landed in both v3.9.4 and v3.10.1, there is no "better" tag to refer to.
since v3.10.0's relation to such a commit is unclear either way.
Also mention that a `Fixes` trailer is preferred if the mention is just
to indicate a commit which introduced an error rather than writing a
complete sentence about it.
Diffstat (limited to 'Help/dev/review.rst')
| -rw-r--r-- | Help/dev/review.rst | 19 |
1 files changed, 14 insertions, 5 deletions
diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 0c4ededd61..1d664c4b82 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -238,12 +238,10 @@ Referencing Commits in Commit Messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The preferred form for references to other commits is -``commit <commit> (<subject>, <date>)``, where: +``commit <shorthash> (<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>``. +* ``<shorthash>``: + The abbreviated hash of the commit. * ``<subject>``: The first line of the commit message. @@ -252,6 +250,17 @@ The preferred form for references to other commits is 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. +This may be generated with +``git show -s --date=short --pretty="format:%h (%s, %ad)" <commit>``. + +If the commit is a fix for the mentioned commit, consider using a ``Fixes:`` +trailer in the commit message with the specified format. This trailer should +not be word-wrapped. Note that if there is also an issue for what is being +fixed, it is preferrable to link to the issue instead. + +If relevant, add the first release tag of CMake containing the commit after +the ``<date>``, i.e., ``commit <shorthash> (<subject>, <date>, <tag>)``. + Alternatively, the full commit ``<hash>`` may be used. Revising Commit Messages |