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 <emilyshaffer@xxxxxxxxxx> --- New in v3: - Made language to platform maintainers a little clearer (hopefully) about this allowing us to provide more predictable support levels. - Clarified that this covers maintaining previous functionality, not adding support for something new. - Made the bullet point formatting a little less eye-bleedy. - Asked reporters to make sure that bugs are really a platform compatibility bug, and not a regular bug. - Rephrased section intros to emphasize what the platform maintainer gets, rather than emphasize the Git project patch lifecycle. - Clarified alternatives to GitHub Actions CI: GitLab or list scraping. Made some notes about avoiding noise. - Small fixes to formatting, spacing, etc Thanks, - Emily v1 description at https://lore.kernel.org/git/20240709225042.2005233-1-emilyshaffer@xxxxxxxxxx/ --- Documentation/Makefile | 1 + Documentation/technical/platform-support.txt | 177 +++++++++++++++++++ 2 files changed, 178 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..981997e635 --- /dev/null +++ b/Documentation/technical/platform-support.txt @@ -0,0 +1,177 @@ +Platform Support Policy +======================= + +Git has a history of providing broad "support" for exotic platforms and older +platforms, without an explicit commitment. Stakeholders of these platforms may +want a more predictable support commitment. This is only possible when platform +stakeholders supply Git developers with adequate tooling, so we can test for +compatibility or develop workarounds for platform-specific quirks on our own. +Various levels of tooling will allow us to make more solid commitments around +Git's compatibility with your platform. + +Note that this document is about maintaining existing support for a platform +that has generally worked in the past; for adding support to a platform which +doesn't generally work with Git, the stakeholders for that platform are expected +to do the bulk of that work themselves. We will consider such patches if they +don't make life harder for other supported platforms, and you may well find a +contributor interested in working on that support, but the Git community as a +whole doesn't feel an obligation to perform such work. + +Compatible by next release +-------------------------- + +To increase probability that compatibility issues introduced in a release +will be fixed in a later release: + +* You should send a bug report as soon as you notice the breakage on your + platform. The sooner you notice, the better; watching `seen` means you can + notice problems before they are considered "done with review"; whereas + watching `master` means the stable branch could break for your platform, but + you have a decent chance of avoiding a tagged release breaking you. See "The + Policy" in the link:../howto/maintain-git.txt[maintainer's guide] 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? + +** If possible, build Git from the exact same source both for your platform and + for a maintstream platform, and make sure the problem you noticed appears + only on your platform. If the problem appears in both, then it's not a + compatibility issue, but we of course appreciate hearing about it in a bug + report anyway, to benefit users of every platform. + +* 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 releases +----------------------------------------- + +To make sure all stable builds and regular releases work for your platform the +first time, you can make sure `master` doesn't break for your platform: + +* You should run nightly tests against the `next` branch and publish breakage + reports to the mailing list immediately when they happen. + +** You may want to ask to join the mailto:git-security@xxxxxxxxxxxxxxxx[security + mailing list] in order to run tests against the fixes proposed there, too. + +* 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; you don't need to send repeated reports for the same breakage night + after night). + +* 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; the turnaround to check + that their proposed fix works for your platform should be fast enough that it + doesn't hinder the developer working on that fix. Slow testing turnarounds + may cause the fix to miss the next release, or the developer may lose + interest in working on the fix at all. + +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 avoid reactive debugging and fixing when changes hit a release or stable, you +can aim to ensure `next` works for your platform. (See "The Policy" in the +link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next` +is used in the Git project.) To do that: + +* You should add a runner for your platform to the GitHub Actions or GitLab 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 adding it to an existing CI suite is infeasible (due to architecture + constraints or for performance reasons), any other method which runs as + automatically and quickly as possible works, too. For example, a service + which snoops on the mailing list and automatically runs tests on new [PATCH] + emails, replying to the author with the results, would also be within the + spirit of this requirement. + +* If you rely on Git avoiding a specific pattern that doesn't work well with + your platform (like a certain malloc pattern), raise it on the mailing list. + There are a few ways to avoid these breakages, so we'll work case-by-case to + find a solution that doesn't unnecessarily constrain other platforms to keep + compatibility with yours. + +* If you rely on some configuration or behavior, add a test for it. 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. + +** Include a comment with an expiration date for these tests no more than 1 year + from now. You can update the expiration date if your platform still needs + that assurance down the road, but we need to know you still care about that + compatibility case and are working to make it unnecessary. + +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. + +Minimum Requirements +-------------------- + +Even if platform maintainers are willing to add tests or CI runners, we will +not consider helping to support platforms that do not meet these minimum +requirements: + +* Has C99 or C11 + +* Has dependencies which were released in the past 10 years + +* Has active security support (taking security releases of dependencies, etc) + +Platform Maintainers +-------------------- + +If you maintain a platform, or Git for that platform, and intend to work with +the Git project to ensure compatibility, please send a patch to add yourself to +this list. + +NonStop: Randall S. Becker <rsbecker@xxxxxxxxxxxxx> Range-diff against v2: 1: 653661002c ! 1: 575c5a5a5f Documentation: add platform support policy @@ Documentation/technical/platform-support.txt (new) +======================= + +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 provided with -+adequate tooling to test for compatibility. Various levels of tooling will -+allow us to make more solid commitments around Git's compatibility with your -+platform. ++platforms, without an explicit commitment. Stakeholders of these platforms may ++want a more predictable support commitment. This is only possible when platform ++stakeholders supply Git developers with adequate tooling, so we can test for ++compatibility or develop workarounds for platform-specific quirks on our own. ++Various levels of tooling will allow us to make more solid commitments around ++Git's compatibility with your platform. ++ ++Note that this document is about maintaining existing support for a platform ++that has generally worked in the past; for adding support to a platform which ++doesn't generally work with Git, the stakeholders for that platform are expected ++to do the bulk of that work themselves. We will consider such patches if they ++don't make life harder for other supported platforms, and you may well find a ++contributor interested in working on that support, but the Git community as a ++whole doesn't feel an obligation to perform such work. + +Compatible by next release +-------------------------- @@ Documentation/technical/platform-support.txt (new) +will be fixed in a later release: + +* You should send a bug report as soon as you notice the breakage on your -+platform. The sooner you notice, the better; watching `seen` means you can -+notice problems before they are considered "done with review"; whereas watching -+`master` means the stable branch could break for your platform, but you have a -+decent chance of avoiding a tagged release breaking you. See "The Policy" in the -+link:../howto/maintain-git.txt[maintainer's guide] for an overview of which -+branches are used in git.git, and how. ++ platform. The sooner you notice, the better; watching `seen` means you can ++ notice problems before they are considered "done with review"; whereas ++ watching `master` means the stable branch could break for your platform, but ++ you have a decent chance of avoiding a tagged release breaking you. See "The ++ Policy" in the link:../howto/maintain-git.txt[maintainer's guide] 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. ++ 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? ++ 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? ++ ++** If possible, build Git from the exact same source both for your platform and ++ for a maintstream platform, and make sure the problem you noticed appears ++ only on your platform. If the problem appears in both, then it's not a ++ compatibility issue, but we of course appreciate hearing about it in a bug ++ report anyway, to benefit users of every platform. ++ +* Once we begin to fix the issue, please work closely with the contributor -+working on it to test the proposed fix against your platform. ++ 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 ++Compatible on `master` and releases +----------------------------------------- + -+To guarantee that `master` and all point releases work for your platform the -+first time: ++To make sure all stable builds and regular releases work for your platform the ++first time, you can make sure `master` doesn't break for your platform: + +* You should run nightly tests against the `next` branch and publish breakage -+reports to the mailing list immediately when they happen. ++ reports to the mailing list immediately when they happen. ++ +** You may want to ask to join the mailto:git-security@xxxxxxxxxxxxxxxx[security -+mailing list] in order to run tests against the fixes proposed there, too. ++ mailing list] in order to run tests against the fixes proposed there, too. ++ +* 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). ++ (you don't need to send a report when everything works, only when something ++ breaks; you don't need to send repeated reports for the same breakage night ++ after night). ++ +* Breakage reports should be actionable - include clear error messages that can -+help developers who may not have access to test directly on your platform. ++ 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. ++ 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 ++ so they can test their fix, OR ++ +** Work closely with the developer fixing the issue; the turnaround to check -+that their proposed fix works for your platform should be fast enough that it -+doesn't hinder the developer working on that fix. Slow testing turnarounds may -+cause the fix to miss the next release, or the developer may lose interest in -+working on the fix at all. ++ that their proposed fix works for your platform should be fast enough that it ++ doesn't hinder the developer working on that fix. Slow testing turnarounds ++ may cause the fix to miss the next release, or the developer may lose ++ interest in working on the fix at all. + +Example: +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@xxxxxxxxxxxxxx/[AIX] @@ Documentation/technical/platform-support.txt (new) +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 adding it to GitHub Actions is infeasible (due to architecture constraints -+or for performance reasons), any other method which runs as automatically and -+quickly as possible works, too. For example, a service which snoops on the -+mailing list and automatically runs tests on new [PATCH] emails, replying to the -+author with the results, would also be within the spirit of this requirement. ++To avoid reactive debugging and fixing when changes hit a release or stable, you ++can aim to ensure `next` works for your platform. (See "The Policy" in the ++link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next` ++is used in the Git project.) To do that: ++ ++* You should add a runner for your platform to the GitHub Actions or GitLab 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 adding it to an existing CI suite is infeasible (due to architecture ++ constraints or for performance reasons), any other method which runs as ++ automatically and quickly as possible works, too. For example, a service ++ which snoops on the mailing list and automatically runs tests on new [PATCH] ++ emails, replying to the author with the results, would also be within the ++ spirit of this requirement. ++ +* If you rely on Git avoiding a specific pattern that doesn't work well with -+your platform (like a certain malloc pattern), raise it on the mailing list. -+There are a few ways to avoid these breakages, so we'll work case-by-case to -+find a solution that doesn't unnecessarily constrain other platforms to keep -+compatibility with yours. -+* If you rely on some configuration or behavior, add a test for it. Untested -+behavior is subject to breakage at any time. ++ your platform (like a certain malloc pattern), raise it on the mailing list. ++ There are a few ways to avoid these breakages, so we'll work case-by-case to ++ find a solution that doesn't unnecessarily constrain other platforms to keep ++ compatibility with yours. ++ ++* If you rely on some configuration or behavior, add a test for it. 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. ++ 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. ++ +** Include a comment with an expiration date for these tests no more than 1 year -+from now. You can update the expiration date if your platform still needs that -+assurance down the road, but we need to know you still care about that -+compatibility case and are working to make it unnecessary. ++ from now. You can update the expiration date if your platform still needs ++ that assurance down the road, but we need to know you still care about that ++ compatibility case and are working to make it unnecessary. + +Example: We run our +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI @@ Documentation/technical/platform-support.txt (new) +of urgency: + +* Clearly state in the commit message that you are fixing a platform breakage, -+and for which platform. ++ and for which platform. ++ +* Use the CI and test suite to ensure that the fix for your platform doesn't -+break other platforms. ++ 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. ++ it's not possible to add a test, explain why in the commit message. + +Minimum Requirements +-------------------- @@ Documentation/technical/platform-support.txt (new) +requirements: + +* Has C99 or C11 ++ +* Has dependencies which were released in the past 10 years ++ +* Has active security support (taking security releases of dependencies, etc) + +Platform Maintainers -- 2.45.2.1089.g2a221341d9-goog
