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

[Robert Hoo]

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)?
I see in main KVM tree, its "fixes" branch is very inactive.
Too many functional branches will add your maintenance burden.

> , 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?

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

> +
> +SDM and APM References
> +~~~~~~~~~~~~~~~~~~~~~~
> +Much of KVM's code base is directly tied to architectural behavior
> defined in
> +Intel's Software Development Manual (SDM) and AMD's Architecture
> Programmer’s
> +Manual (APM).  Use of "Intel's SDM" and "AMD's APM", or even just
> "SDM" or
> +"APM", without additional context is a-ok.
> +
> +Do not reference specific sections, tables, figures, etc. by number,
> especially
> +not in comments.  Instead, copy-paste the relevant snippet (if
> warranted), and
> +reference sections/tables/figures by name.  The layouts of the SDM
> and APM are
> +constantly changing, and so the numbers/labels aren't
> stable/consistent.

Ack