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

[Duncan]

Michał Górny posted on Tue, 25 Jul 2017 10:05:06 +0200 as excerpted:

> ===Splitting commits===
> Git commits are lightweight, and the developers are encouraged to split
> their commits to improve readability and the ability of reverting
> specific sub-changes. When choosing how to split the commits, the
> developers should consider the following three rules:
> # Use atomic commits — one commit per logical change.
> # Split commits at logical unit (package, eclass, profile…) boundaries.
> # Avoid creating commits that are 'broken' — e.g. are incomplete, have
> uninstallable packages.

(Without commenting on the technical specifics, particularly in the
examples, only nitpicking grammar here...)

Two instances of "the developers":  Should be "the developer" (singular),
or "developers" (plural, no "the"), your choice.  Note that in the first
usage, if the singular "the developer" is chosen, the following "are" and
"their" will need changed to singular as well.

(Of course then there's the question of his/her or a controversial usage
of singular "their" to remain gender neutral, so plural "developers" may
be best there, nicely avoiding the secondary controversy.  FWIW, the
appropriateness of singular they/their to avoid gender specificity is a
current topic of debate in linguistic circles, but is "languagelog approved"
at least, citing usage by respected authors going back over a century, and
seems to be on the way toward wider acceptance.  YMMV, but it's easy enough
to avoid the entire question here, with consistent plural usage.)

> It is technically impossible to always respect all of the three rules,

s/all of the three rules,/all three rules/
(Note omission of the comma too.)

> so developers have to balance between them at their own discretion. Side
> changes that are implied by other change (e.g. revbump due to some
> change) should be included in the first commit requiring them. Commits
> should be ordered to avoid breakage, and follow logical ordering
> whenever possible.
>
> Examples:
> * When doing a version bump, it is usually not reasonable to split every
> necessary logical change into separate commit since the interim commits

s/into separate commit/into separate commits/

... but that's still slightly uncomfortable due to ambiguous plurality
agreement.  Maybe...

"into its own commit"

> would correspond to a broken package. However, if the package has a live
> ebuild, it ''might'' be reasonable to perform split logical changes on
> the live ebuild, then create a release as another logical step.
> * When doing one or more changes that require a revision bump, bump the
> revision in the commit including the first change. Split the changes
> into multiple logical commits without further revision bumps — since
> they are going to be pushed in a single push, the user will not be
> exposed to interim state.
> * When adding a new version of a package that should be masked, you can
> include the {{Path|package.mask}} edit in the commit adding it.
> Alternatively, you can add the mask in a split commit ''preceding'' the
> bump.
> * 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.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman