On 7/25/2017 4:05 AM, Michał Górny wrote: > Hi, everyone. > > There have been multiple attempts at grasping this but none so far > resulted in something official and indisputable. At the same time, we > end having to point our users at semi-official guides which change > in unpredictable ways. > > Here's the current draft: > https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git > > The basic idea is that the GLEP provides basic guidelines for using git, > and then we write a proper manual on top of it (right now, all the pages > about it end up as a mix of requirements and a partial git manual). > > What do you think about it? Is there anything else that needs being > covered? > > Copy of the markup for inline comments follows.
[cut] > ===Commit messages=== > A standard git commit message consists of three parts, in order: a > summary line, an optional body and an optional set of tags. The parts > are separated by a single empty line. > [cut] > The tag part is included in the full commit log as an extension to the > body. It consists of one or more lines consisting of key, followed by a > colon and a space, followed by value. Git does not enforce any > standardization of the keys, and the tag format is ''not'' meant for > machine processing. > > A few tags of common use are: > * user-related tags: > ** <kbd>Acked-by: Full Name <em...@example.com></kbd> — commit approved > by another person (usually without detailed review), > ** <kbd>Reported-by: Full Name <em...@example.com></kbd>, > ** <kbd>Reviewed-by: Full Name <em...@example.com></kbd> — usually > indicates full review, > ** <kbd>Signed-off-by: Full Name <em...@example.com></kbd> — DCO > approval (not used in Gentoo right now), > ** <kbd>Suggested-by: Full Name <em...@example.com></kbd>, > ** <kbd>Tested-by: Full Name <em...@example.com></kbd>. > * commit-related tags: > ** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a > previous commit, > ** <kbd>Reverts: commit-id (commit message)</kbd> — to indicate > reverting a previous commit, > * bug tracker-related tags: > ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — to > reference a bug, > ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi > ki></kbd>; — to automatically close a GitHub pull request, > ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — > to indicate a fixed bug, > * package manager tags: > ** <kbd>Package-Manager: …</kbd> — used by repoman to indicate Portage > version, > ** <kbd>RepoMan-Options: …</kbd> — used by repoman to indicate repoman > options. > > The bug tracker-related tags can be used to extend the body message. > However, they should be skipped if the bug number is already provided in > the summary and there is no explicit body. > My concern on these tags is that some evangelist will come along and demand that they always be included with every commit since they exist in a GLEP. They add very little value, IMO, and I doubt they will ever be parsed or ever read. I would object less if the committing tool, i.e. repoman, would provide easy switches for common cases for uniformity. I foresee more work on my part to remember such lines and would have to look up the "current syntax" as it goes through debate many times over as it already has. (Both in the past and in this thread again). Brian
signature.asc
Description: OpenPGP digital signature
