Supporting many platforms is only easy when we have the right tools to ensure that support. Teach platform maintainers how they can help us to help them, by explaining what kind of tooling support we would like to have, and what level of support becomes available as a result. Provide examples so that platform maintainers can see what we're asking for in practice. With this policy in place, we can make changes with stronger assurance that we are not breaking anybody we promised not to. Instead, we can feel confident that our existing testing and integration practices protect those who care from breakage. Signed-off-by: Emily Shaffer <nasamuffin@xxxxxxxxxx> --- Hi folks, Some months ago, I branched the Rust discussion to talk about platform support[1]. That discussion didn't go far, but with libification efforts touching the Makefile and worrying about compatibility, it seems like a worthy discussion to have. My goal with this document is that if we claim to support a given platform, that platform should be easy for contributors to test against. And the corollary, if we can't test against a given platform easily, we shouldn't be assuring users on that platform that it will always work. I'm thinking of platforms which rely on recent Git binaries but which we don't test against by default, like NonStop[2] or AIX[3]. Right now, this doc talks about "guarantees." I used that phrasing based on what I've observed to be an implicit expectation that we guarantee support; it could be this isn't actually a guarantee that the community is willing to make, so I am hoping we can discuss it and come up with the right term. I'm hoping that this policy (or one like it) can clarify a "help us help you" relationship with platform maintainers. If we can clearly define the resources we need in order to guarantee that we're supporting a platform, then we can make changes more confidently; if, instead, we make a serious effort to fix any and all reported breakages, then all patches are at risk of breaking a platform we didn't know exists but care about providing first-class support for and being rolled back. I think there is some space in between those two extremes, too, that might be suitable for some less-used platforms, or platforms which follow new releases less closely. Looking forward to discussing. - Emily 1: https://lore.kernel.org/git/CAJoAoZnHGTFhfR6e6r=GMSfVbSNgLoHF-opaWYLbHppiuzi+Rg@xxxxxxxxxxxxxx/ ; 2: https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/ ; 3: https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@xxxxxxxxxxxxxx/ --- Documentation/Makefile | 1 + Documentation/technical/platform-support.txt | 102 +++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 Documentation/technical/platform-support.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index dc65759cb1..462af0311f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -118,6 +118,7 @@ TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone +TECH_DOCS += technical/platform-support TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/scalar diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt new file mode 100644 index 0000000000..23ab708144 --- /dev/null +++ b/Documentation/technical/platform-support.txt @@ -0,0 +1,102 @@ +Platform Support Policy +======================= + +Git has a history of providing broad "support" for exotic platforms and older +platforms, without an explicit commitment. This support becomes easier to +maintain (and possible to commit to) when Git developers are providing with +adequate tooling to test for compatibility. Variouis levels of tooling will +allow us to make more solid commitments around Git's compatibility with your +platform. + +Compatible by vN+1 release +-------------------------- + +To increase probability that compatibility issues introduced in a point release +will be fixed by the next point release: + +* You should send a bug report as soon as you notice the breakage on your +platform. The sooner you notice, the better; it's better for you to watch `seen` +than to watch `master`. See linkgit:gitworkflows[7] under "Graduation" for an +overview of which branches are used in git.git, and how. +* The bug report should include information about what platform you are using. +* You should also use linkgit:git-bisect[1] and determine which commit +introduced the breakage. +* Please include any information you have about the nature of the breakage: is +it a memory alignment issue? Is an underlying library missing or broken for +your platform? Is there some quirk about your platform which means typical +practices (like malloc) behave strangely? +* Once we begin to fix the issue, please work closely with the contributor +working on it to test the proposed fix against your platform. + +Example: NonStop +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports +problems] when they're noticed. + +Compatible on `master` and point releases +----------------------------------------- + +To guarantee that `master` and all point releases work for your platform the +first time: + +* You should run nightly tests against the `next` branch and publish breakage +reports to the mailing list immediately when they happen. +* It may make sense to automate these; if you do, make sure they are not noisy +(you don't need to send a report when everything works, only when something +breaks). +* Breakage reports should be actionable - include clear error messages that can +help developers who may not have access to test directly on your platform. +* You should use git-bisect and determine which commit introduced the breakage; +if you can't do this with automation, you should do this yourself manually as +soon as you notice a breakage report was sent. +* You should either: +** Provide VM access on-demand to a trusted developer working to fix the issue, +so they can test their fix, OR +** Work closely with the developer fixing the issue - testing turnaround to +check whether the fix works for your platform should not be longer than a +business day. + +Example: +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@xxxxxxxxxxxxxx/[AIX] +provides a build farm and runs tests against release candidates. + +Compatible on `next` +-------------------- + +To guarantee that `next` will work for your platform, avoiding reactive +debugging and fixing: + +* You should add a runner for your platform to the GitHub Actions CI suite. +This suite is run when any Git developer proposes a new patch, and having a +runner for your platform/configuration means every developer will know if they +break you, immediately. +* If you rely on Git avoiding a specific pattern that doesn't work well with +your platform (like a certain malloc pattern), if possible, add a coccicheck +rule to ensure that pattern is not used. +* If you rely on some configuration or behavior, add a test for it. You may +find it easier to add a unit test ensuring the behavior you need than to add an +integration test; either one works. Untested behavior is subject to breakage at +any time. +** Clearly label these tests as necessary for platform compatibility. Add them +to an isolated compatibility-related test suite, like a new t* file or unit test +suite, so that they're easy to remove when compatibility is no longer required. +If the specific compatibility need is gated behind an issue with another +project, link to documentation of that issue (like a bug or email thread) to +make it easier to tell when that compatibility need goes away. + +Example: We run our +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI +suite] on Windows, Ubuntu, Mac, and others. + +Getting help writing platform support patches +--------------------------------------------- + +In general, when sending patches to fix platform support problems, follow +these guidelines to make sure the patch is reviewed with the appropriate level +of urgency: + +* Clearly state in the commit message that you are fixing a platform breakage, +and for which platform. +* Use the CI and test suite to ensure that the fix for your platform doesn't +break other platforms. +* If possible, add a test ensuring this regression doesn't happen again. If +it's not possible to add a test, explain why in the commit message. -- 2.45.2.803.g4e1b14247a-goog
