From: Sean Christopherson <seanjc@google.com>
To: "Maciej S. Szmigiero" <mail@maciej.szmigiero.name>
Cc: Paolo Bonzini <pbonzini@redhat.com>,
Thomas Gleixner <tglx@linutronix.de>,
Ingo Molnar <mingo@redhat.com>, Borislav Petkov <bp@alien8.de>,
Dave Hansen <dave.hansen@linux.intel.com>,
Sagi Shahar <sagis@google.com>,
Erdem Aktas <erdemaktas@google.com>,
Peter Shier <pshier@google.com>,
Anish Ghulati <aghulati@google.com>,
Oliver Upton <oliver.upton@linux.dev>,
James Houghton <jthoughton@google.com>,
Anish Moorthy <amoorthy@google.com>,
Ben Gardon <bgardon@google.com>,
David Matlack <dmatlack@google.com>,
Ricardo Koller <ricarkol@google.com>,
Axel Rasmussen <axelrasmussen@google.com>,
Aaron Lewis <aaronlewis@google.com>,
Ashish Kalra <ashish.kalra@amd.com>,
Babu Moger <babu.moger@amd.com>, Chao Gao <chao.gao@intel.com>,
Chao Peng <chao.p.peng@linux.intel.com>,
Chenyi Qiang <chenyi.qiang@intel.com>,
David Woodhouse <dwmw@amazon.co.uk>,
Emanuele Giuseppe Esposito <eesposit@redhat.com>,
Gavin Shan <gshan@redhat.com>, Guang Zeng <guang.zeng@intel.com>,
Hou Wenlong <houwenlong.hwl@antgroup.com>,
Jiaxi Chen <jiaxi.chen@linux.intel.com>,
Jim Mattson <jmattson@google.com>, Jing Liu <jing2.liu@intel.com>,
Junaid Shahid <junaids@google.com>,
Kai Huang <kai.huang@intel.com>,
Leonardo Bras <leobras@redhat.com>,
Like Xu <like.xu.linux@gmail.com>,
Li RongQing <lirongqing@baidu.com>,
Maxim Levitsky <mlevitsk@redhat.com>,
Michael Roth <michael.roth@amd.com>, Michal Luczaj <mhal@rbox.co>,
Mingwei Zhang <mizhang@google.com>,
Nikunj A Dadhania <nikunj@amd.com>,
Paul Durrant <pdurrant@amazon.com>,
Peng Hao <flyingpenghao@gmail.com>,
Peter Gonda <pgonda@google.com>, Peter Xu <peterx@redhat.com>,
Robert Hoo <robert.hu@linux.intel.com>,
Suravee Suthikulpanit <suravee.suthikulpanit@amd.com>,
Tom Lendacky <thomas.lendacky@amd.com>,
Vipin Sharma <vipinsh@google.com>,
Vitaly Kuznetsov <vkuznets@redhat.com>,
Wanpeng Li <wanpengli@tencent.com>,
Wei Wang <wei.w.wang@intel.com>,
Xiaoyao Li <xiaoyao.li@intel.com>,
Yu Zhang <yu.c.zhang@linux.intel.com>,
Zhenzhong Duan <zhenzhong.duan@intel.com>,
kvm@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH 2/2] Documentation/process: Add a maintainer handbook for KVM x86
Date: Wed, 22 Feb 2023 13:25:19 -0800 [thread overview]
Message-ID: <Y/aIP4aCxTVOU/ZC@google.com> (raw)
In-Reply-To: <2dfae61c-6ac7-7686-ebd1-6ad4448b2bf8@maciej.szmigiero.name>
On Wed, Feb 22, 2023, Maciej S. Szmigiero wrote:
> On 17.02.2023 23:54, Sean Christopherson wrote:
> > +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.
>
> This says do "copy-paste the relevant snippet"...
>
> > The layouts of the SDM and APM are
> > +constantly changing, and so the numbers/labels aren't stable/consistent.
> > +
> > +Generally speaking, do not copy-paste SDM or APM snippets into
> > comments.
>
> ...but this seems to say "don't do that".
Yeah, that didn't come out right.
> More specific guidance would probably help here.
Is this better?
Do not reference specific sections, tables, figures, etc. by number, especially
not in comments. Instead, if necessary (see below), copy-paste the relevant
snippet 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.
Generally speaking, do not explicitly reference or copy-paste from the SDM or
APM in comments. With few exceptions, KVM *must* honor architectural behavior,
therefore it's implied that KVM behavior is emulating SDM and/or APM behavior.
Note, referencing the SDM/APM in changelogs to justify the change and provide
context is perfectly ok and encouraged.
> > +If a patch touches multiple topics, traverse up the conceptual tree to find the
> > +first common parent (which is often simply ``x86``). When in doubt,
> > +``git log path/to/file`` should provide a reasonable hint.
> > +
> > +New topics do occasionally pop up, but please start an on-list discussion if
> > +you want to propose introducing a new topic, i.e. don't go rogue.
> > +
> > +Do not use file names or complete file paths as the subject/shortlog prefix.
>
> Do we strictly obey the "75 characters max" rule for the subject/shortlog
> or do we prefer to be more flexible here if it results in a more
> descriptive patch subject?
I prefer to be a little flexible, I'll expand this section to clarify that.
> (...)
> > +Testing
> > +-------
> > +At a bare minimum, *all* patches in a series must build cleanly for KVM_INTEL=m
> > +KVM_AMD=m, and KVM_WERROR=y. Building every possible combination of Kconfigs
> > +isn't feasible, but the more the merrier. KVM_SMM, KVM_XEN, PROVE_LOCKING, and
> > +X86_64 are particularly interesting knobs to turn.
> > +
> > +Running KVM selftests and KVM-unit-tests is also mandatory (and stating the
> > +obvious, the tests need to pass).
>
> I would add an exception here from mandatory testing for changes that
> obviously have negligible probability of affecting runtime behavior.
>
> For example: patches that modify just code comments or documentation.
Agreed, will add.
Regarding documentation, I think I'll also add a requirement of 'make htmldocs'
without warnings for non-trivial docs changes. It's all too easy to write buggy
ReST "code" that looks correct as raw text, e.g. the whole double-colon thing.
> > When possible and relevant, testing on both
> > +Intel and AMD is strongly preferred. Booting an actual VM is encouraged, but
> > +not mandatory.
> > +
> > +For changes that touch KVM's shadow paging code, running with TDP (EPT/NPT)
> > +disabled is mandatory. For changes that affect common KVM MMU code, running
> > +with TDP disabled is strongly encouraged. For all other changes, if the code
> > +being modified depends on and/or interacts with a module param, testing with
> > +the relevant settings is mandatory.
> > +
> > +Note, KVM selftests and KVM-unit-tests do have known failures. If you suspect
> > +a failure is not due to your changes, verify that the *exact same* failure
> > +occurs with and without your changes.
> > +
> > +If you can't fully test a change, e.g. due to lack of hardware, clearly state
> > +what level of testing you were able to do, e.g. in the cover letter.
> > +
> (...)
>
> Thanks for preparing such a detailed handbook Sean.
>
> However, having so many rules might seem intimidating for newcomers, and
> deter them from contributing out of fear that they'll be screamed at for
> accidentally breaking some obscure rule.
>
> That's especially true for unpaid volunteers that might become
> professional kernel developers one day if their learning curve isn't
> made too steep.
>
> Maybe have a paragraph or two that, despite all these rules, KVM x86
> strives to be a welcome community, encouraging newcomers and understanding
> their beginner mistakes (or so)?
I like that idea a lot, I'll add a section at the very top.
Thanks much!
next prev parent reply other threads:[~2023-02-22 21:25 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-02-17 22:54 [PATCH 0/2] Documentation/process: Add a maintainer handbook for KVM x86 Sean Christopherson
2023-02-17 22:54 ` [PATCH 1/2] Documentation/process: Add a label for the tip tree handbook's coding style Sean Christopherson
2023-02-17 22:54 ` [PATCH 2/2] Documentation/process: Add a maintainer handbook for KVM x86 Sean Christopherson
2023-02-18 1:52 ` Mingwei Zhang
2023-02-22 0:29 ` Sean Christopherson
2023-03-02 18:46 ` Mingwei Zhang
2023-02-20 8:10 ` Yuan Yao
2023-02-20 10:07 ` Like Xu
2023-02-22 1:55 ` Sean Christopherson
2023-02-20 23:17 ` David Woodhouse
2023-02-21 19:54 ` Sean Christopherson
2023-02-21 11:06 ` Yu Zhang
2023-02-22 0:25 ` Sean Christopherson
2023-02-24 9:44 ` Yu Zhang
2023-02-22 19:26 ` Maciej S. Szmigiero
2023-02-22 21:25 ` Sean Christopherson [this message]
2023-02-22 22:09 ` Maciej S. Szmigiero
2023-02-28 14:45 ` Robert Hoo
2023-03-07 17:53 ` Sean Christopherson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Y/aIP4aCxTVOU/ZC@google.com \
--to=seanjc@google.com \
--cc=aaronlewis@google.com \
--cc=aghulati@google.com \
--cc=amoorthy@google.com \
--cc=ashish.kalra@amd.com \
--cc=axelrasmussen@google.com \
--cc=babu.moger@amd.com \
--cc=bgardon@google.com \
--cc=bp@alien8.de \
--cc=chao.gao@intel.com \
--cc=chao.p.peng@linux.intel.com \
--cc=chenyi.qiang@intel.com \
--cc=dave.hansen@linux.intel.com \
--cc=dmatlack@google.com \
--cc=dwmw@amazon.co.uk \
--cc=eesposit@redhat.com \
--cc=erdemaktas@google.com \
--cc=flyingpenghao@gmail.com \
--cc=gshan@redhat.com \
--cc=guang.zeng@intel.com \
--cc=houwenlong.hwl@antgroup.com \
--cc=jiaxi.chen@linux.intel.com \
--cc=jing2.liu@intel.com \
--cc=jmattson@google.com \
--cc=jthoughton@google.com \
--cc=junaids@google.com \
--cc=kai.huang@intel.com \
--cc=kvm@vger.kernel.org \
--cc=leobras@redhat.com \
--cc=like.xu.linux@gmail.com \
--cc=linux-kernel@vger.kernel.org \
--cc=lirongqing@baidu.com \
--cc=mail@maciej.szmigiero.name \
--cc=mhal@rbox.co \
--cc=michael.roth@amd.com \
--cc=mingo@redhat.com \
--cc=mizhang@google.com \
--cc=mlevitsk@redhat.com \
--cc=nikunj@amd.com \
--cc=oliver.upton@linux.dev \
--cc=pbonzini@redhat.com \
--cc=pdurrant@amazon.com \
--cc=peterx@redhat.com \
--cc=pgonda@google.com \
--cc=pshier@google.com \
--cc=ricarkol@google.com \
--cc=robert.hu@linux.intel.com \
--cc=sagis@google.com \
--cc=suravee.suthikulpanit@amd.com \
--cc=tglx@linutronix.de \
--cc=thomas.lendacky@amd.com \
--cc=vipinsh@google.com \
--cc=vkuznets@redhat.com \
--cc=wanpengli@tencent.com \
--cc=wei.w.wang@intel.com \
--cc=xiaoyao.li@intel.com \
--cc=yu.c.zhang@linux.intel.com \
--cc=zhenzhong.duan@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).