Re: [PATCH 2/2] Documentation/process: Add a maintainer handbook for KVM x86

[Sean Christopherson]

On Tue, Feb 28, 2023, Robert Hoo wrote:
> On Fri, 2023-02-17 at 14:54 -0800, Sean Christopherson wrote:
> > +Branches
> > +~~~~~~~~
> > +The KVM x86 tree is organized into multiple topic branches.  The
> > purpose of
> > +using finer-grained topic branches is to make it easier to keep tabs
> > on an area
> > +of development, and to limit the collateral damage of human errors
> > and/or buggy
> > +commits, e.g. dropping the HEAD commit of a topic branch has no
> > impact on other
> > +in-flight commits' SHA1 hashes, and having to reject a pull request
> > due to bugs
> > +delays only that topic branch.
> > +
> > +All topic branches, except for ``next`` and ``fixes``
> 
> What's this "fixes" branch for?
> If fixes for current cycle, will apply to main KVM tree; if fixes for
> next cycle, why not directly to its topic branch or next branch (kvm-
> x86 tree)?

kvm-x86/fixes is a placeholder for carrying fixes for the current cycle.  I
deliberately hedged in the previous section by saying "Generally speaking".  I.e.
the vast majority of fixes will be applied to the main tree, but there may be
situations where I gather fixes in kvm-x86 and send a pull request to Paolo, e.g.
that may be easier if Paolo is on holiday for an extended period.

 : Generally speaking, fixes for the current cycle are applied directly to the
 : main KVM tree, while all development for the next cycle is routed through the
 : KVM x86 tree.

I'll add a blurb to the above paragraph to clarify that fixes _may_ be carried in
kvm-x86/fixes.

> I see in main KVM tree, its "fixes" branch is very inactive.

AFAIK, Paolo doesn't use it at all.

> Too many functional branches will add your maintenance burden.

There's definitely a point where more branches would be a bad thing, but I don't
think having a "fixes" branch moves the needle on that front.

> > , are rolled into ``next``
> > +via a cthulu merge on an as-needed basis, i.e. when a topic branch
> > is updated.
> > +As a result, force pushes to ``next`` are common.
> > +
> > +Lifecycle
> > +~~~~~~~~~
> > +Pull requests for the next release cycle are sent to the main KVM
> > tree, one
> > +for each KVM x86 topic branch. 
> 
> Will each KVM x86 topic branch has a mapping topic branch in main KVM
> tree? I mean where is their pull target(s), next branch in main KVM
> tree? or their counterpart branches in main KVM tree?

Barring some esoteric edge case, the target will be kvm/next or kvm/queue.  Merging
to a topic branch and then merging again would add no value.  I'd prefer not to add
anything to clarify the target because (a) it's technically outside the scope of KVM
x86 and (b) it simply doesn't matter as far as KVM x86 is concerned.  E.g. if Paolo
wants/needs to merge a topic branch somewhere else for whatever reason, that doesn't
impact the KVM x86 lifecycle in any way.

> >  If all goes well, the topic branches are rolled
> > +into the main KVM pull request sent during Linus' merge
> > window.  Pull requests
> > +for KVM x86 branches are typically made the week before Linus'
> > opening of the
> > +merge window, e.g. the week following rc7 for "normal" releases.
> > +
> > +The KVM x86 tree doesn't have its own official merge window, but
> > there's a soft
> > +close around rc5 for new features, and a soft close around rc6 for
> > fixes.
> > +
> > 
> > +Comments
> > +~~~~~~~~
> > +Write comments using imperative mood and avoid pronouns.  Use
> > comments to
> > +provide a high level overview of the code, and/or to explain why the
> > code does
> > +what it does.  Do not reiterate what the code literally does; let
> > the code
> > +speak for itself.  If the code itself is inscrutable, comments will
> > not help.
> 
> Welcome comments that state preconditions for calling this function?
> e.g. some lock held.

Hard "no".  Any non-obvious preconditions should be conveyed through lockdep
assertions, WARNs, etc...