mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-02 03:39:43 -06:00
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.
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user