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

[Michał Górny]

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