[gentoo-dev] Re: [RFC pre-GLEP] Gentoo Git Workflow

[Michael Palimaka]

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?