On wto, 2017-07-25 at 22:28 +1000, Michael Palimaka wrote: > 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.
It's merely a recommendation. I don't want to cover every single use case because that would be insane. I'm already worried I've covered too many cases for people to read it all. > > ===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. Tags don't appear on 'git log --oneline' or cgit/gitweb shortlog. If you are groking through multiple bugs, it is more convenient if you can find the bug no straight away. > > ** <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. 'Fixes' is the original tag used by other projects. 'Bug' is shorter than 'Gentoo-bug' and avoids repeating the obvious. Much like we do not have 'Gentoo-signed-off-by', 'Gentoo-thanks-to' and so on, having 'Gentoo-bug' is equally silly. Furthermore, full URLs should be used with tags. If you are already using tags (i.e. long form), don't do it half-way and put useless digits there. Put URL that will be interpreted by practically all visual git tools written ever. > > 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'? Yes, thanks. > > > 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? I'm not stopping anyone. This is merely a suggestion. Encouraging two different tags for the same thing would be confusing to users. -- Best regards, Michał Górny
signature.asc
Description: This is a digitally signed message part
