On 07/25/2017 06:05 PM, 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
This looks really nice, thanks for working on it. > * When doing a minor change to a large number of packages, it is > reasonable to do so in a single commit. However, when doing a major > change (e.g. a version bump), it is better to split commits on package > boundaries. In some cases we do prefer to make major changes on a set of related package all in one commit. For example, we always bump the 240+ KDE Applications collection together because that's how it's released. > ===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. > > The summary line is included in the short logs (<kbd>git log -- > oneline</kbd>, gitweb, GitHub, mail subject) and therefore should > provide a short yet accurate description of the change. The summary line > starts with a logical unit name, followed by a colon, a space and a > short description of the most important changes. If a bug is associated > with a change, then it should be included in the summary line as > <kbd>#nnnnnn</kbd> or likewise. The summary line must not exceed 69 > characters, and must not be wrapped. Does a bug # really need to always be in the summary line? It can eat valuable characters and tags which are pretty popular are equally valid IMO. > ** <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, grepping the git log shows that 'Gentoo-bug' is much more common than plain 'Bug'. 'Fixes' is hardly used at all, and I think it's a bit confusing to use this for bugs as well as commits. > a few branches on the repository, and did not maintain them. The Infra > had to query the developers about the state of the branches and clean > them up. Should 'The Infra' be 'The Infra team' or just 'Infra'? > Gentoo developers are still frequently using <kbd>Gentoo-Bug</kbd> tag, > sometimes followed by <kbd>Gentoo-Bug-URL</kbd>. Using both > simultaneously is meaningless (they are redundant), and using the former > has no advantages over using the classic <kbd>#nnnnnn</kbd> form in the > summary or the body. I agree that using both is redundant, but I don't agree with discouraging or banning the use of 'Gentoo-bug'. If someone prefers to use it so it sits nicely with the other tags why stop them?
