Message-ID: <425d56ca2a2c9eb3a0bd4019706aee6db5dd8fc6.camel@linux.intel.com>
Date:   Tue, 28 Feb 2023 22:45:42 +0800
From:   Robert Hoo <robert.hu@...ux.intel.com>
To:     Sean Christopherson <seanjc@...gle.com>,
        Paolo Bonzini <pbonzini@...hat.com>
Cc:     Thomas Gleixner <tglx@...utronix.de>,
        Ingo Molnar <mingo@...hat.com>, Borislav Petkov <bp@...en8.de>,
        Dave Hansen <dave.hansen@...ux.intel.com>,
        Sagi Shahar <sagis@...gle.com>,
        Erdem Aktas <erdemaktas@...gle.com>,
        Peter Shier <pshier@...gle.com>,
        Anish Ghulati <aghulati@...gle.com>,
        Oliver Upton <oliver.upton@...ux.dev>,
        James Houghton <jthoughton@...gle.com>,
        Anish Moorthy <amoorthy@...gle.com>,
        Ben Gardon <bgardon@...gle.com>,
        David Matlack <dmatlack@...gle.com>,
        Ricardo Koller <ricarkol@...gle.com>,
        Axel Rasmussen <axelrasmussen@...gle.com>,
        Aaron Lewis <aaronlewis@...gle.com>,
        Ashish Kalra <ashish.kalra@....com>,
        Babu Moger <babu.moger@....com>, Chao Gao <chao.gao@...el.com>,
        Chao Peng <chao.p.peng@...ux.intel.com>,
        Chenyi Qiang <chenyi.qiang@...el.com>,
        David Woodhouse <dwmw@...zon.co.uk>,
        Emanuele Giuseppe Esposito <eesposit@...hat.com>,
        Gavin Shan <gshan@...hat.com>,
        Guang Zeng <guang.zeng@...el.com>,
        Hou Wenlong <houwenlong.hwl@...group.com>,
        Jiaxi Chen <jiaxi.chen@...ux.intel.com>,
        Jim Mattson <jmattson@...gle.com>,
        Jing Liu <jing2.liu@...el.com>,
        Junaid Shahid <junaids@...gle.com>,
        Kai Huang <kai.huang@...el.com>,
        Leonardo Bras <leobras@...hat.com>,
        Like Xu <like.xu.linux@...il.com>,
        Li RongQing <lirongqing@...du.com>,
        "Maciej S . Szmigiero" <maciej.szmigiero@...cle.com>,
        Maxim Levitsky <mlevitsk@...hat.com>,
        Michael Roth <michael.roth@....com>,
        Michal Luczaj <mhal@...x.co>,
        Mingwei Zhang <mizhang@...gle.com>,
        Nikunj A Dadhania <nikunj@....com>,
        Paul Durrant <pdurrant@...zon.com>,
        Peng Hao <flyingpenghao@...il.com>,
        Peter Gonda <pgonda@...gle.com>, Peter Xu <peterx@...hat.com>,
        Suravee Suthikulpanit <suravee.suthikulpanit@....com>,
        Tom Lendacky <thomas.lendacky@....com>,
        Vipin Sharma <vipinsh@...gle.com>,
        Vitaly Kuznetsov <vkuznets@...hat.com>,
        Wanpeng Li <wanpengli@...cent.com>,
        Wei Wang <wei.w.wang@...el.com>,
        Xiaoyao Li <xiaoyao.li@...el.com>,
        Yu Zhang <yu.c.zhang@...ux.intel.com>,
        Zhenzhong Duan <zhenzhong.duan@...el.com>, kvm@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH 2/2] Documentation/process: Add a maintainer handbook
 for KVM x86

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

Powered by blists - more mailing lists