Skip to contentSkip to conversation

Documentation/process: Add a maintainer handbook for KVM x86

PATCH Superseded Sean Christopherson 4 participants 14 messages Mar 9, 2023 – Mar 13, 2023

Subsystems (4)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Sean Christopherson

author maintainer
#0 lore raw

v2 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
author maintainer
#1 lore raw

PATCH 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
index 572a3289c9cb..ad0540d6882b 100644
@@ -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
author maintainer
#2 lore raw

PATCH v2 2/2 Documentation/process: Add a maintainer handbook for KVM x86

In reply to Sean Christopherson

Add 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
index d783060b4cc6..d12cbbe2b7df 100644
@@ -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
index 6a47510d1592..13e67a8b4827 100644
@@ -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
#3 lore raw

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
#4 lore raw
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
author maintainer
#5 lore raw
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.

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.

#6 lore raw
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
#7 lore raw
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
author maintainer
#8 lore raw
In reply to Oliver Upton
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 ;-)

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.

#9 lore raw
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

author maintainer
#10 lore raw
Quoted 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

author maintainer
#11 lore raw
In reply to Bagas Sanjaya
Quoted 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          nSVM

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

author maintainer
#13 lore raw
Quoted 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.