Documentation/process: Add a maintainer handbook for KVM x86
Subsystems (4)
Sean Christopherson
maintainerv2 cover Documentation/process: Add a maintainer handbook for KVM x86
Dcumentation for contributing to KVM x86, round 2!
v2:
- Fix a KVM_GET_SUPPORTED_CPUID typo. [Yuan]
- Give Cthulhu the respect it deserves. [Like]
- Explicitly state that selftests vs. KVM patches need to maintain bisection (when possible). [Like]
- Change the recommended base from topic branches to "next" (and plan on providing stable, persistent git objects via tags). [David W]
- Add a blurb to provide guidance for series that touch non-x86 arch code. [Yu]
- Clarify when (not) to reference/quote specs (APM and SDM). [Maciej]
- Add preferences for shortlog length. [Maciej]
- Exempt things like comment fixes from testing requirements. [Maciej]
- Add a foreword to try and make the doc less scary to newcomers. [Maciej]
- Add a rule for testing Documentation/ changes.
- Clarify that fixes for the current cycle may be carried in the KVM x86 tree, but are usually taken directly by Paolo. [Robert]
- Tweak the "Changelog" section to call out that using imperative mood and avoiding pronouns is the most important rule.
v1: https://lore.kernel.org/all/[email protected]
Sean Christopherson (2):
Documentation/process: Add a label for the tip tree handbook's coding
style
Documentation/process: Add a maintainer handbook for KVM x86
.../process/maintainer-handbooks.rst | 1 + Documentation/process/maintainer-kvm-x86.rst | 391 ++++++++++++++++++ Documentation/process/maintainer-tip.rst | 2 + MAINTAINERS | 1 + 4 files changed, 395 insertions(+) create mode 100644 Documentation/process/maintainer-kvm-x86.rst
base-commit: 3ac88fa4605ec98e545fb3ad0154f575fda2de5f
Signature · 1 line
2.40.0.rc1.284.g88254d51c5-goog
Sean Christopherson
maintainerPATCH v2 1/2 Documentation/process: Add a label for the tip tree handbook's coding style
Add a label for the tip tree's "Coding style notes" so that a forthcoming KVM x86 handbook can reference/piggyback the tip tree's preferred coding style.
--- Documentation/process/maintainer-tip.rst | 2 ++ 1 file changed, 2 insertions(+)
Documentation/process/maintainer-tip.rst +2 -0
@@ -452,6 +452,8 @@ and can be added to an existing kernel config by running: Some of these options are x86-specific and can be left out when testing on other architectures. +.. _maintainer-tip-coding-style: + Coding style notes ------------------
Signature · 1 line
2.40.0.rc1.284.g88254d51c5-goog
Sean Christopherson
maintainerPATCH v2 2/2 Documentation/process: Add a maintainer handbook for KVM x86
In reply to Sean ChristophersonAdd a KVM x86 doc to the subsystem/maintainer handbook section to explain how KVM x86 (currently) operates as a sub-subsystem, and to soapbox on the rules and expectations for contributing to KVM x86.
--- .../process/maintainer-handbooks.rst | 1 + Documentation/process/maintainer-kvm-x86.rst | 391 ++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 393 insertions(+) create mode 100644 Documentation/process/maintainer-kvm-x86.rst
Documentation/process/maintainer-handbooks.rst +1 -0
@@ -17,3 +17,4 @@ Contents: maintainer-tip maintainer-netdev + maintainer-kvm-x86
Documentation/process/maintainer-kvm-x86.rst new file +391 -0
391 lines not on this page · raw message
MAINTAINERS +1 -0
@@ -11436,6 +11436,7 @@ M: Sean Christopherson <[email protected]> M: Paolo Bonzini <[email protected]> L: [email protected] S: Supported +P: Documentation/process/maintainer-kvm-x86.rst T: git git://git.kernel.org/pub/scm/virt/kvm/kvm.git F: arch/x86/include/asm/kvm* F: arch/x86/include/asm/svm.h
Signature · 1 line
2.40.0.rc1.284.g88254d51c5-goog
Documentation/process/maintainer-kvm-x86.rst line 105
Quoted 8 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.
That means patches that primarily kvm ARM changes should be based on kvm-x86/next, right?
Documentation/process/maintainer-kvm-x86.rst line 183
Quoted 3 lines
Documentation/process/maintainer-kvm-x86.rst new file +3
-0+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.
What do you mean by conceptual tree? Is it Patch subject prefix?
Documentation/process/maintainer-kvm-x86.rst line 353
Quoted 5 lines
Documentation/process/maintainer-kvm-x86.rst new file +5
-0+KVM selftests that are associated with KVM changes, e.g. regression tests for +bug fixes, should be posted along with the KVM changes as a single series. The +standard kernel rules for bisection apply, i.e. KVM changes that result in test +failures should be ordered after the selftests updates, and vice versa, new +tests that fail due to KVM bugs should be ordered after the KVM fixes.
Did you mean that in a patch series, selftest patches are placed after their corresponding KVM changes?
Thanks.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Quoted 9 lines · Bagas Sanjaya
Documentation/process/maintainer-kvm-x86.rst line 105
Quoted 8 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.
I don't think this is the best way to coordinate with other architectures. Regardless of whether you intended this to be prescriptive, I'm worried most folks will follow along and just base patches on kvm-x86/next anyway.
It'd be easier to just have multi-arch series use a stable base (i.e. a release candidate) by default. That'd avoid the undesirable case where merging a shared branch brings with it some random point in another arch's /next history.
If a different approach makes sense for a particular series then we can discuss it on the list and arrive at something agreeable for all parties involved.
Quoted 2 lines
That means patches that primarily kvm ARM changes should be based on kvm-x86/next, right?
No, don't do that.
Patches aimed at KVM/arm64 should be based on a sensible release candidate. We tend to contstruct the kvmarm/next with an early-ish release candidate (rc2-rc4). For example the 6.3 pull request was based on 6.2-rc4. We use topic branches in a slightly different manner than x86, creating ad-hoc branches for individual patch series grabbed from the list.
If one has a series that conflicts with/depends on another that is in-flight or already picked up then that should be mentioned in the cover letter. Ultimately its up to the maintainer(s) to address conflicts, and neither Marc nor I are afraid to ask for a rebase/respin if it makes our lives easier to glue it all together.
Signature · 2 lines
Thanks, Oliver
Sean Christopherson
maintainerQuoted 14 lines · Oliver Upton
Quoted 9 lines · Bagas Sanjaya
Documentation/process/maintainer-kvm-x86.rst line 105
Quoted 8 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.I don't think this is the best way to coordinate with other architectures. Regardless of whether you intended this to be prescriptive, I'm worried most folks will follow along and just base patches on kvm-x86/next anyway.
Probably, but for the target audience (KVM x86 contributors), that's likely the least awful base 99% of the time.
Quoted 4 lines
It'd be easier to just have multi-arch series use a stable base (i.e. a release candidate) by default. That'd avoid the undesirable case where merging a shared branch brings with it some random point in another arch's /next history.
You're conflating the base of the patch series with the branch it is applied to. I'm most definitely not proposing that multi-arch series from x86 contributors always be routed through kvm-x86. It's ultimately the responsibility of the maintainers, not the contributors, to avoid funky merges and histories. If a series warrants a dedicated topic branch, then we need to create said topic branch off a stable, common base, irrespective of what the contributor based their patches on.
If a series from an x86 contributor applies cleanly on kvm-x86/next but not on -rc2 (or whatever), then the reverse would also likely be true (if the contributor used -rc2 as the base). In other words, for series with non-trivial modifications to other architectures and/or common KVM code, IMO the base used for the _initial_ posting doesn't matter all that much for us maintainers since such series will likely require additional attention no matter what base is used.
On the flip side, the vast majority of "multi-arch" series in KVM tend to be focused on a single architecture, with only incidental contact to other architectures and/or common KVM code. Those types of series will likely be routed through their "target" arch tree, and so for x86, using kvm-x86/next as the base is preferrable.
My goal with suggesting/prescribing kvm-x86/next to contributors is to make the easy things easy. On my end, that means having _predictable_ submissions and minimizing the number of avoidable conflicts. For contributors, that means having a very simple rule/guideline. "Use kvm-x86/next unless you know better" satisfies all those conditions.
Quoted 8 lines
If a different approach makes sense for a particular series then we can discuss it on the list and arrive at something agreeable for all parties involved.
Quoted 2 lines
That means patches that primarily kvm ARM changes should be based on kvm-x86/next, right?
No, don't do that.
+<infinity symbol>
This doc is specifically for KVM x86.
Quoted 16 lines · Sean Christopherson
Quoted 14 lines · Oliver Upton
Quoted 9 lines · Bagas Sanjaya
Documentation/process/maintainer-kvm-x86.rst line 105
Quoted 8 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.I don't think this is the best way to coordinate with other architectures. Regardless of whether you intended this to be prescriptive, I'm worried most folks will follow along and just base patches on kvm-x86/next anyway.
Quoted 2 lines
Probably, but for the target audience (KVM x86 contributors), that's likely the least awful base 99% of the time.
Sorry, I follow this reasoning at all.
If folks are aiming to make a multi-arch contribution then the architecture they regularly contribute to has absolutely zero relevance on the series itself.
Quoted 6 lines
Quoted 4 lines
It'd be easier to just have multi-arch series use a stable base (i.e. a release candidate) by default. That'd avoid the undesirable case where merging a shared branch brings with it some random point in another arch's /next history.
You're conflating the base of the patch series with the branch it is applied to.
We cannot pretend the two are in no way related. The dependencies of a series are not obvious when based on the /next branch of any one architecture.
Quoted 3 lines
I'm most definitely not proposing that multi-arch series from x86 contributors always be routed through kvm-x86. It's ultimately the responsibility of the maintainers, not the contributors, to avoid funky merges and histories.
Right, but contributors looking to make changes across architectures share some of the burden of cross-arch coordination as well. Basing patches off of a random commit not in Linus' tree does not match at least the arm64 workflow.
Quoted 4 lines
If a
series warrants a dedicated topic branch, then we need to create said topic branch off a stable, common base, irrespective of what the contributor based their patches on.
The lowest friction way to coordinate such things is to start off with a common base and go from there. If there is a compelling argument for doing things differently in the context of one series then let's talk about it on the list.
Quoted 3 lines
If a series from an x86 contributor applies cleanly on kvm-x86/next but not on -rc2 (or whatever), then the reverse would also likely be true (if the contributor used -rc2 as the base).
This can be addressed in a merge resolution, thereby offloading the responsibility to the maintainer.
Quoted 4 lines
In other words, for series with non-trivial modifications
to other architectures and/or common KVM code, IMO the base used for the _initial_ posting doesn't matter all that much for us maintainers since such series will likely require additional attention no matter what base is used.
In all likelihood, sure the series will be respun. But, you're offloading the responsibility to ask for a sane base on other arch maintainers which I'm not cool with.
Quoted 4 lines
On the flip side, the vast majority of "multi-arch" series in KVM tend to be focused on a single architecture, with only incidental contact to other architectures and/or common KVM code. Those types of series will likely be routed through their "target" arch tree, and so for x86, using kvm-x86/next as the base is preferrable.
With long term aspirations to share more code between architectures (e.g. common MMU) I believe we'll see more changes that have meaningful interaction with all architecutures.
Quoted 5 lines
My goal with suggesting/prescribing kvm-x86/next to contributors is to make the easy things easy. On my end, that means having _predictable_ submissions and minimizing the number of avoidable conflicts. For contributors, that means having a very simple rule/guideline. "Use kvm-x86/next unless you know better" satisfies all those conditions.
I believe "Use a release candidate unless you know better" for multi-arch changes is just as simple. Better yet, it clues in contributors as to how changes are coordinated across architectures and might help them know better next time around.
Quoted 4 lines
Quoted 4 lines
If a different approach makes sense for a particular series then we can discuss it on the list and arrive at something agreeable for all parties involved.
Quoted 8 lines
Quoted 4 lines
Quoted 2 lines
That means patches that primarily kvm ARM changes should be based on kvm-x86/next, right?
No, don't do that.
+<infinity symbol>
This doc is specifically for KVM x86.
You've also made some suggestions about cross-arch development that do not fit the development model of other architectures. I have no desire to nitpick about the x86 process but want the multiarch language to actually set folks up for success working outside of the KVM/x86 tree.
Signature · 2 lines
Thanks, Oliver
Quoted 17 lines · Oliver Upton
Quoted 16 lines · Sean Christopherson
Quoted 14 lines · Oliver Upton
Quoted 9 lines · Bagas Sanjaya
Documentation/process/maintainer-kvm-x86.rst line 105
Quoted 8 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.I don't think this is the best way to coordinate with other architectures. Regardless of whether you intended this to be prescriptive, I'm worried most folks will follow along and just base patches on kvm-x86/next anyway.
Quoted 4 lines
Quoted 2 lines
Probably, but for the target audience (KVM x86 contributors), that's likely the least awful base 99% of the time.
Sorry, I follow this reasoning at all.
I *don't* follow ...
Signature · 2 lines
Thanks, Oliver
Sean Christopherson
maintainerQuoted 17 lines · Oliver Upton
Quoted 16 lines · Sean Christopherson
Quoted 14 lines · Oliver Upton
Quoted 9 lines · Bagas Sanjaya
Documentation/process/maintainer-kvm-x86.rst line 105
Quoted 8 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.I don't think this is the best way to coordinate with other architectures. Regardless of whether you intended this to be prescriptive, I'm worried most folks will follow along and just base patches on kvm-x86/next anyway.
Quoted 8 lines
Quoted 2 lines
Probably, but for the target audience (KVM x86 contributors), that's likely the least awful base 99% of the time.
Sorry, I follow this reasoning at all.
If folks are aiming to make a multi-arch contribution then the architecture they regularly contribute to has absolutely zero relevance on the series itself.
There's disconnect between what my brain is thinking and what I wrote.
The intent of the "use kvm-x86/next" guideline is aimed to address series that are almost entirely x86 specific, and only superficially touch common KVM and/or other architectures. In my experience, the vast, vast majority of "multi-arch" contributions from x86 fall into this category, i.e. aren't truly multi-arch in nature.
If I replace the above paragraph with this, does that address (or at least mitigate to an acceptable level) your concerns? Inevitably there will still be series that are wrongly based on kvm-x86, but I am more than happy to do the policing. I obviously can't guarantee that I will be the first to run afoul of a "bad" series, but I do think I can be quick enough to avoid shifting the burden to other maintainers. And if I'm wrong on either front, you get to say "told you so" and make me submit a patch of shame ;-)
The only exception to using ``kvm-x86/next`` as the base is if a patch/series is a multi-arch series, i.e. has non-trivial modifications to common KVM code and/or has more than superficial changes to other architectures's code. Multi- arch patch/series should instead be based on a common, stable point in KVM's history, e.g. the release candidate upon which ``kvm-x86 next`` is based. If you're unsure whether a patch/series is truly multi-arch, err on the side of caution and treat it as multi-arch, i.e. use a common base.
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines
Quoted 2 lines
That means patches that primarily kvm ARM changes should be based on kvm-x86/next, right?
No, don't do that.
Quoted 8 lines
Quoted 3 lines
+<infinity symbol>
This doc is specifically for KVM x86.
You've also made some suggestions about cross-arch development that do not fit the development model of other architectures. I have no desire to nitpick about the x86 process but want the multiarch language to actually set folks up for success working outside of the KVM/x86 tree.
Ah, I see where y'all are coming from. Yeah, I didn't intend for that type of blanket rule, e.g. my comment about this being specifically for KVM x86 was intended to clarify that this doc should NOT be used to determine how to handle non-x86 code.
Quoted 43 lines · Sean Christopherson
Quoted 17 lines · Oliver Upton
Quoted 16 lines · Sean Christopherson
Quoted 14 lines · Oliver Upton
Quoted 9 lines · Bagas Sanjaya
Documentation/process/maintainer-kvm-x86.rst line 105
Quoted 8 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.I don't think this is the best way to coordinate with other architectures. Regardless of whether you intended this to be prescriptive, I'm worried most folks will follow along and just base patches on kvm-x86/next anyway.
Quoted 8 lines
Quoted 2 lines
Probably, but for the target audience (KVM x86 contributors), that's likely the least awful base 99% of the time.
Sorry, I follow this reasoning at all.
If folks are aiming to make a multi-arch contribution then the architecture they regularly contribute to has absolutely zero relevance on the series itself.
There's disconnect between what my brain is thinking and what I wrote.
The intent of the "use kvm-x86/next" guideline is aimed to address series that are almost entirely x86 specific, and only superficially touch common KVM and/or other architectures. In my experience, the vast, vast majority of "multi-arch" contributions from x86 fall into this category, i.e. aren't truly multi-arch in nature.
If I replace the above paragraph with this, does that address (or at least mitigate to an acceptable level) your concerns? Inevitably there will still be series that are wrongly based on kvm-x86, but I am more than happy to do the policing. I obviously can't guarantee that I will be the first to run afoul of a "bad" series, but I do think I can be quick enough to avoid shifting the burden to other maintainers. And if I'm wrong on either front, you get to say "told you so" and make me submit a patch of shame ;-)
Quoted 3 lines
The only exception to using ``kvm-x86/next`` as the base is if a patch/series is a multi-arch series, i.e. has non-trivial modifications to common KVM code and/or has more than superficial changes to other architectures's code. Multi-
nit: Maybe 'to another architecture's code', since English is an annoying language :)
Quoted 4 lines
arch patch/series should instead be based on a common, stable point in KVM's history, e.g. the release candidate upon which ``kvm-x86 next`` is based. If you're unsure whether a patch/series is truly multi-arch, err on the side of caution and treat it as multi-arch, i.e. use a common base.
LGTM, and sorry for whining without getting across the net effect I was hoping for in the language.
Quoted 14 lines
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines
Quoted 2 lines
That means patches that primarily kvm ARM changes should be based on kvm-x86/next, right?
No, don't do that.
Quoted 8 lines
Quoted 3 lines
+<infinity symbol>
This doc is specifically for KVM x86.
You've also made some suggestions about cross-arch development that do not fit the development model of other architectures. I have no desire to nitpick about the x86 process but want the multiarch language to actually set folks up for success working outside of the KVM/x86 tree.
Quoted 4 lines
Ah, I see where y'all are coming from. Yeah, I didn't intend for that type of blanket rule, e.g. my comment about this being specifically for KVM x86 was intended to clarify that this doc should NOT be used to determine how to handle non-x86 code.
My biggest worry was that whether intentional or not, folks will probably take what you've written out of context. Not as though I could completely blame the developer in that case, as we have no documented process for arm64 at the moment.
--
Thanks,
Oliver
Sean Christopherson
maintainerQuoted 44 lines · Oliver Upton
Quoted 43 lines · Sean Christopherson
Quoted 17 lines · Oliver Upton
Quoted 16 lines · Sean Christopherson
Quoted 14 lines · Oliver Upton
Quoted 9 lines · Bagas Sanjaya
Review
Quoted 8 lines · Sean Christopherson
(quoted diff) +8
-0+As a general guideline, use ``kvm-x86/next`` even if a patch/series touches +multiple architectures, i.e. isn't strictly scoped to x86. Using any of the +branches from the main KVM tree is usually a less good option as they likely +won't have many, if any, changes for the next release, i.e. using the main KVM +tree as a base is more likely to yield conflicts. And if there are non-trivial +conflicts with multiple architectures, coordination between maintainers will be +required no matter what base is used. Note, this is far from a hard rule, i.e. +use a different base for multi-arch series if that makes the most sense.I don't think this is the best way to coordinate with other architectures. Regardless of whether you intended this to be prescriptive, I'm worried most folks will follow along and just base patches on kvm-x86/next anyway.
Quoted 8 lines
Quoted 2 lines
Probably, but for the target audience (KVM x86 contributors), that's likely the least awful base 99% of the time.
Sorry, I follow this reasoning at all.
If folks are aiming to make a multi-arch contribution then the architecture they regularly contribute to has absolutely zero relevance on the series itself.
There's disconnect between what my brain is thinking and what I wrote.
The intent of the "use kvm-x86/next" guideline is aimed to address series that are almost entirely x86 specific, and only superficially touch common KVM and/or other architectures. In my experience, the vast, vast majority of "multi-arch" contributions from x86 fall into this category, i.e. aren't truly multi-arch in nature.
If I replace the above paragraph with this, does that address (or at least mitigate to an acceptable level) your concerns? Inevitably there will still be series that are wrongly based on kvm-x86, but I am more than happy to do the policing. I obviously can't guarantee that I will be the first to run afoul of a "bad" series, but I do think I can be quick enough to avoid shifting the burden to other maintainers. And if I'm wrong on either front, you get to say "told you so" and make me submit a patch of shame ;-)
Quoted 6 lines
Quoted 3 lines
The only exception to using ``kvm-x86/next`` as the base is if a patch/series is a multi-arch series, i.e. has non-trivial modifications to common KVM code and/or has more than superficial changes to other architectures's code. Multi-
nit: Maybe 'to another architecture's code', since English is an annoying language :)
Gah, was supposed to be just "architectures'". I don't want to limit the wording to just one other architecture, because then I'll get nitpicked on what to do if a series touches _two_ architectures.
Quoted 7 lines
Quoted 4 lines
arch patch/series should instead be based on a common, stable point in KVM's history, e.g. the release candidate upon which ``kvm-x86 next`` is based. If you're unsure whether a patch/series is truly multi-arch, err on the side of caution and treat it as multi-arch, i.e. use a common base.
LGTM, and sorry for whining without getting across the net effect I was hoping for in the language.
No need to apologize, the whole point of this doc is to try to make everyone's lives easier, not just my own. But mostly my own :-D
Sean Christopherson
maintainerQuoted 6 lines · Bagas Sanjaya
Documentation/process/maintainer-kvm-x86.rst line 183
Quoted 3 lines · Sean Christopherson
Documentation/process/maintainer-kvm-x86.rst new file +3
-0+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.What do you mean by conceptual tree? Is it Patch subject prefix?
Not really? I'm struggling to describe it in words. What I mean is something like this
x86
/ | \
VMX pmu SVM
/ \
nVMX nSVMe.g. if a patch touches VMX and SVM, use "x86". But it's a bit more complex than that, e.g. a VMX-focused patch that just happens to touch Intel-specific PMU code should probably be tagged "VMX", not "x86" or "pmu".
Massaging subjects when applying is easy enough, and there will always be some amount of subjectivity, so unless this is outright confusing (or someone has a better, succinct, and easy-to-understand description), I'll probably just leave this section as-is.
Quoted 8 lines
Documentation/process/maintainer-kvm-x86.rst line 353
Quoted 5 lines
Documentation/process/maintainer-kvm-x86.rst new file +5
-0+KVM selftests that are associated with KVM changes, e.g. regression tests for +bug fixes, should be posted along with the KVM changes as a single series. The +standard kernel rules for bisection apply, i.e. KVM changes that result in test +failures should be ordered after the selftests updates, and vice versa, new +tests that fail due to KVM bugs should be ordered after the KVM fixes.Did you mean that in a patch series, selftest patches are placed after their corresponding KVM changes?
No, I meant what I wrote. If a KVM change will break a test (uncommon, but it does happen), then the selftest should be patched first so that there are no unnecessary test failures in the git history. But when adding a regression test, the KVM bug fix should come first so that again, there are no unnecessary failures if someone tests an arbitrary commit, e.g. during bisection.
On Wed, 2023-03-08 at 17:03 -0800, Sean Christopherson wrote:
(...)
Review
Quoted 4 lines
+Using reverse fir tree for variable declarations isn't strictly required,
(quoted diff) +2
-0+though it is still preferred. +
I googled, but didn't find what's "fir tree". Shed more light? I saw Maciej also asked.
https://lore.kernel.org/kvm/[email protected]/
Sean Christopherson
maintainerQuoted 7 lines · Robert Hoo
On Wed, 2023-03-08 at 17:03 -0800, Sean Christopherson wrote:
(...)Review
Quoted 4 lines
+Using reverse fir tree for variable declarations isn't strictly required,
(quoted diff) +2
-0+though it is still preferred. +I googled, but didn't find what's "fir tree". Shed more light?
Y'all need to improve your Google-fu ;-)
Since many people seem to be surprised by this one, I'll reword this section to:
Using reverse fir tree, a.k.a. reverse Christmas tree or reverse XMAS tree, for variable declarations isn't strictly required, though it is still preferred.