Re: [gentoo-dev] Revision bumps vs git commits atomicity

[Michał Górny]

On Fri, 2 Dec 2016 18:14:05 +0300
Andrew Savchenko <bircoph@g.o> wrote:

> Hi all!
>
> Right now we have two somewhat conflicting policies (at least up to
> my understanding of them):
>
> 1) git atomic commits [1]:
> each logical change should be a separate commit.
>
> 2) revision bump policy [2]:
> each change sufficiently affecting application run-time or
> installed files should have a revision bump.
>
> Let's consider the following quite common scenario: package foo-1.0
> should be updated to foo-1.1, but aside from version bump there is
> a set of accumulated issues which maintainer is willing to handle,
> e.g.:
> - bump to EAPI 6;
> - fix several runtime bugs (still present in the new version);
> - install missing documentation;
> - add previously omitted USE flags for some tools of controllable
> functionalities;
> - etc...
>
> If both policies are to be followed, users will see something like:
> foo-1.0 -> foo-1.1-r8 (assuming each sufficient change was made as
> a separate commit with a revision bump).
>
> While such versioning change is technically correct, it is
> confusing for our users and makes future maintainance harder,
> because of multiple file renames (yeah, I know about git diff
> --find-renames, but this kludge is not perfect).

To be honest, I don't really see how multiple successive renames are
really any worse than a single rename in git. Not that I oppose your
idea, just nitpicking.

> What about the following forkflow:
> - version bump first with minimal changes required, but without
> pushing commit to the tree;
> - make each logical change as a separate commit without revision
> bumps and without pushing stuff to the tree (of course repoman
> scan/full is required as usual for each commit);
> - well test package after the last commit (that it builds with
> various USE flag combinations, old and new functionality works fine
> and so on);
> - fix any problems found and only afterwards push changes to the
> tree.
>
> This way users will see only foo-1.0 -> foo-1.1 change in the tree,
> while git will still retain each logical change as a separate
> commit, which will make future maintenance and debugging much
> easier.

Well, this is pretty much what we're doing and what fits common sense,
and I'm not sure if we really need to word this into a formal policy.

The definition of 'one logical change' is pretty inconclusive. One
could claim the whole bump to be one logical change, and I don't think
that we should really force people to split every change into a single
commit because it is too cumbersome.

What really makes sense is using the common sense to determine which
changes are best made together, and which really deserve a separate
commit. And of course, once a revbump or version bump is necessary, you
have to do it on the first commit involved (to avoid altering the old
file, in case you are keeping it) and you don't have to bump further
until the thing hits users.

What we need to keep in mind is the spirit of doing split commits --
it's meant to:

a) ease reviewing, through providing better context for each change,

b) ease reverting, especially in case one of the changes is more likely
to cause mayhem than others.

-- 
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>