[gentoo-dev] Revision bumps vs git commits atomicity

[Andrew Savchenko]

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).

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.

Of course a separate git branch may be used as well, but using
branches for each half-a-dozen set of commits looks like an
overkill to me.

Thoughts, comments?

[1] https://devmanual.gentoo.org/ebuild-maintenance/index.html
[2] https://devmanual.gentoo.org/general-concepts/ebuild-revisions/index.html

Best regards,
Andrew Savchenko