| Message ID | 20240718173843.2411415-1-emilyshaffer@google.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] Documentation: add platform support policy | expand |
On Thu, Jul 18, 2024 at 10:38 AM Emily Shaffer <emilyshaffer@google.com> wrote: > > 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@google.com> > > --- > > New in v3: FYI, the asciidoctor build failed upstream. I won't have a chance to fix it til at least the afternoon (if not tomorrow), but I'll prepare a scissors fixup when I can, and include it into the reroll if/when the next one is needed. https://github.com/nasamuffin/git/actions/runs/9996112167/job/27629731071 - Emily
Emily Shaffer <nasamuffin@google.com> writes: > FYI, the asciidoctor build failed upstream. I won't have a chance to > fix it til at least the afternoon (if not tomorrow), but I'll prepare > a scissors fixup when I can, and include it into the reroll if/when > the next one is needed. diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt index 981997e635..65c0fa20de 100644 --- a/Documentation/technical/platform-support.txt +++ b/Documentation/technical/platform-support.txt @@ -54,8 +54,9 @@ 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:
Emily Shaffer <emilyshaffer@google.com> writes: > Supporting many platforms is only easy when we have the right tools to > ensure that support. "easy" -> "possible". > +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 Running $ make -C Documentation howto/maintain-git.html $ lynx Documentation/howto/maintain-git.html tells me that the title of the document is "How to maintain Git". > + overview of which branches are used in git.git, and how. "git.git" -> "the Git project" > +Compatible on `master` and releases > +----------------------------------------- Underline that signals what level the header is is drawn to the same column as the header title itself, or you'd confuse the formatter. > +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: "can" -> "want to"? But "to make sure X, you can make sure Y" feels a bit awkward. To make sure ... work for your platform, help us avoid breaking the tip of `master` by merging topics that break your platform. > +* You should run nightly tests against the `next` branch and publish breakage > + reports to the mailing list immediately when they happen. Can't it be daily instead of nightly ;-), or is it better than nothing if you can afford to run only once every other day? A topic (unless it is during the shuffle time around -rc0) usually spends no less than 7 calendar days in 'next', so while I would appreciate if somebody runs tests twice a day, in practice you should be able to catch a new breakage in 'next' if you run a full and thorough test twice a week. > +* You should either: > + > +** Provide VM access on-demand to a trusted developer working to fix the issue, > + so they can test their fix, OR "VM access on-demand" -> "on-demand access to your platform" (iow, physical iron is also fine for our purpose). > +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. It would be very nice if they did this, indeed. Explaining that something that mechanically looks vastly different is within the spirit is a very good move. > +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 OK. > +* Has dependencies which were released in the past 10 years This is hard to understand and I wonder if we can clarify. I get what you want to say: suppose we rely on library X that is getting regular feature and security updates in reasonable cadence, say every 6 months there is an upstream release of library X, but a niche platform has ported the library only once long time ago, and hasn't updated it ever since. Now the Git project may consider helping a port to such a platform if the initial port of library X was 8 years ago, but will not if it was 12 years ago. But if Git depends on an ultra stable library whose last public release was 12 years ago, disqualify everybody is not what this requirement wants to do. I attempted to formulate my version along ... Keep up with the versions of dependencies (libraries, etc.) and not to lag behind compared to typical mainstream platforms by more than X years. ... the above line, but to me it is no better than the original, so I failed miserably. But the idea I am bringing to the table here is that time of release is not absolute. If typical mainstream platforms consider a release of a library made 8 years ago from the upstream performant, functional, and secure enough and fit for use, we do not consider that they are approaching the limit. But if another platform uses the same library from 12 years ago, i.e. lagging behind others by 4 years is a problem at the same graveness using another library that was released 6 years ago, when other platforms are using a much younger vintage of the same library released at 2 years ago. Having said all that, everything I removed from my quote I found agreeable. Very well written. Thanks.
On Thursday, July 18, 2024 6:46 PM, Junio C Hamano wrote: >Emily Shaffer <emilyshaffer@google.com> writes: > >> Supporting many platforms is only easy when we have the right tools to >> ensure that support. > >"easy" -> "possible". > >> +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 > >Running > > $ make -C Documentation howto/maintain-git.html > $ lynx Documentation/howto/maintain-git.html > >tells me that the title of the document is "How to maintain Git". > >> + overview of which branches are used in git.git, and how. > >"git.git" -> "the Git project" > >> +Compatible on `master` and releases >> +----------------------------------------- > >Underline that signals what level the header is is drawn to the same column as the >header title itself, or you'd confuse the formatter. > > >> +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: > >"can" -> "want to"? > >But "to make sure X, you can make sure Y" feels a bit awkward. > > To make sure ... work for your platform, help us avoid breaking the > tip of `master` by merging topics that break your platform. > >> +* You should run nightly tests against the `next` branch and publish >> +breakage >> + reports to the mailing list immediately when they happen. > >Can't it be daily instead of nightly ;-), or is it better than nothing if you can afford to >run only once every other day? > >A topic (unless it is during the shuffle time around -rc0) usually spends no less than >7 calendar days in 'next', so while I would appreciate if somebody runs tests twice a >day, in practice you should be able to catch a new breakage in 'next' if you run a full >and thorough test twice a week. > >> +* You should either: >> + >> +** Provide VM access on-demand to a trusted developer working to fix the issue, >> + so they can test their fix, OR > >"VM access on-demand" -> "on-demand access to your platform" (iow, physical >iron is also fine for our purpose). > >> +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. > >It would be very nice if they did this, indeed. Explaining that something that >mechanically looks vastly different is within the spirit is a very good move. > >> +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 > >OK. > >> +* Has dependencies which were released in the past 10 years > >This is hard to understand and I wonder if we can clarify. I get what you want to >say: suppose we rely on library X that is getting regular feature and security updates >in reasonable cadence, say every 6 months there is an upstream release of library X, >but a niche platform has ported the library only once long time ago, and hasn't >updated it ever since. Now the Git project may consider helping a port to such a >platform if the initial port of library X was 8 years ago, but will not if it was 12 years >ago. > >But if Git depends on an ultra stable library whose last public release was 12 years >ago, disqualify everybody is not what this requirement wants to do. > >I attempted to formulate my version along ... > > Keep up with the versions of dependencies (libraries, etc.) and > not to lag behind compared to typical mainstream platforms by > more than X years. > >... the above line, but to me it is no better than the original, so I failed miserably. But >the idea I am bringing to the table here is that time of release is not absolute. If >typical mainstream platforms consider a release of a library made 8 years ago from >the upstream performant, functional, and secure enough and fit for use, we do not >consider that they are approaching the limit. But if another platform uses the same >library from 12 years ago, i.e. >lagging behind others by 4 years is a problem at the same graveness using another >library that was released 6 years ago, when other platforms are using a much >younger vintage of the same library released at 2 years ago. > >Having said all that, everything I removed from my quote I found agreeable. Very >well written. I am concerned about setting a specific limit here. The reason is that, as a platform/community maintainer: 1. I do not control the library versions that are available - in most cases 2. I do not control the available toolchain - in all cases 3. Support is required for all OS releases dating back 5 years from the close of sales - this is not actually a huge problem except for #1 and #2. However, it does not serious constraints on what toolchains are available. Most of what we do is use static linkage to avoid a lot of compatibility issues, other than OpenSSL that has to be flexible based on the rate of CVEs raised and solved. 4. Porting some new tools (e.g., GO, Rust, gcc, libc, glibc), is usually impossible no matter what my skill level based on platform prohibitions. I'm sorry to have to complain about this, but it is a reality of exotic, non-linux, platforms that are still being maintained and active (the last major NonStop OS release was 11 months ago, and another is due to drop imminently, so this is not a dead or dying platform). The last thing I want to have is having users locked out of future git versions, based on the increasing adoption of git on NonStop that has been (immodestly said) mostly my fault. Can we solve this in some acceptable way? Sincerely, Randall
On Thu, Jul 18, 2024 at 10:38:43AM -0700, Emily Shaffer wrote: > +* 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. I found the latter part of this bullet point a bit weird. We don't yet know about the specific pattern that may fail on any future supported platform, so claiming that there are ways to avoid them goes a bit too far, no? > +** 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. Do we maybe want to replace "from now" with "from when you add them"? Other than that this document looks great to me, thanks! Patrick
On 2024.07.18 10:38, Emily Shaffer wrote: > 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@google.com> > > --- > > 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@google.com/ > --- > 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 Typo: "maintstream" > + 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@googlegroups.com[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@mail.gmail.com/[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 > +-------------------- It might make more sense to move this section immediately after the introduction. I don't feel too strongly about it though. > +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@nexbridge.com> Overall, looks good to me, thanks!
On Thu, Jul 18, 2024 at 4:45 PM <rsbecker@nexbridge.com> wrote: > > On Thursday, July 18, 2024 6:46 PM, Junio C Hamano wrote: > >Emily Shaffer <emilyshaffer@google.com> writes: > > > >> Supporting many platforms is only easy when we have the right tools to > >> ensure that support. > > > >"easy" -> "possible". > > > >> +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 > > > >Running > > > > $ make -C Documentation howto/maintain-git.html > > $ lynx Documentation/howto/maintain-git.html > > > >tells me that the title of the document is "How to maintain Git". > > > >> + overview of which branches are used in git.git, and how. > > > >"git.git" -> "the Git project" > > > >> +Compatible on `master` and releases > >> +----------------------------------------- > > > >Underline that signals what level the header is is drawn to the same column as the > >header title itself, or you'd confuse the formatter. > > > > > >> +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: > > > >"can" -> "want to"? > > > >But "to make sure X, you can make sure Y" feels a bit awkward. > > > > To make sure ... work for your platform, help us avoid breaking the > > tip of `master` by merging topics that break your platform. > > > >> +* You should run nightly tests against the `next` branch and publish > >> +breakage > >> + reports to the mailing list immediately when they happen. > > > >Can't it be daily instead of nightly ;-), or is it better than nothing if you can afford to > >run only once every other day? > > > >A topic (unless it is during the shuffle time around -rc0) usually spends no less than > >7 calendar days in 'next', so while I would appreciate if somebody runs tests twice a > >day, in practice you should be able to catch a new breakage in 'next' if you run a full > >and thorough test twice a week. > > > >> +* You should either: > >> + > >> +** Provide VM access on-demand to a trusted developer working to fix the issue, > >> + so they can test their fix, OR > > > >"VM access on-demand" -> "on-demand access to your platform" (iow, physical > >iron is also fine for our purpose). > > > >> +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. > > > >It would be very nice if they did this, indeed. Explaining that something that > >mechanically looks vastly different is within the spirit is a very good move. > > > >> +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 > > > >OK. > > > >> +* Has dependencies which were released in the past 10 years > > > >This is hard to understand and I wonder if we can clarify. I get what you want to > >say: suppose we rely on library X that is getting regular feature and security updates > >in reasonable cadence, say every 6 months there is an upstream release of library X, > >but a niche platform has ported the library only once long time ago, and hasn't > >updated it ever since. Now the Git project may consider helping a port to such a > >platform if the initial port of library X was 8 years ago, but will not if it was 12 years > >ago. > > > >But if Git depends on an ultra stable library whose last public release was 12 years > >ago, disqualify everybody is not what this requirement wants to do. > > > >I attempted to formulate my version along ... > > > > Keep up with the versions of dependencies (libraries, etc.) and > > not to lag behind compared to typical mainstream platforms by > > more than X years. > > > >... the above line, but to me it is no better than the original, so I failed miserably. But > >the idea I am bringing to the table here is that time of release is not absolute. If > >typical mainstream platforms consider a release of a library made 8 years ago from > >the upstream performant, functional, and secure enough and fit for use, we do not > >consider that they are approaching the limit. But if another platform uses the same > >library from 12 years ago, i.e. > >lagging behind others by 4 years is a problem at the same graveness using another > >library that was released 6 years ago, when other platforms are using a much > >younger vintage of the same library released at 2 years ago. > > > >Having said all that, everything I removed from my quote I found agreeable. Very > >well written. > > I am concerned about setting a specific limit here. The reason is that, as a platform/community maintainer: > 1. I do not control the library versions that are available - in most cases > 2. I do not control the available toolchain - in all cases > 3. Support is required for all OS releases dating back 5 years from the close of sales - this is not actually a huge problem except for #1 and #2. However, it does not serious constraints on what toolchains are available. Most of what we do is use static linkage to avoid a lot of compatibility issues, other than OpenSSL that has to be flexible based on the rate of CVEs raised and solved. > 4. Porting some new tools (e.g., GO, Rust, gcc, libc, glibc), is usually impossible no matter what my skill level based on platform prohibitions. I actually think what level of control the platform maintainer has is beside the point. The intent of this line in the doc is to say: even if there is an active maintainer and there are active users, Git developers need to be able to use relatively modern tooling to be able to keep Git healthy and evolving. The more Git development is locked into past tooling, the less it can keep up with the needs of most of the industry, and the higher the risk comes of Git being abandoned because the cost to overhaul it to meet industry needs is too high. So, if a platform isn't compatible with those reasonably modern tools (and I do think "a C compiler that's less than 10 years out-of-date" is really stretching the meaning of "modern"), sorry, but it's not workable for us. That is, it's not about whether the maintainer is virtuous and doing everything in their power; it's about whether the platform itself is feasible to support and whether the abilities of the platform line up with the Git project's needs to make forward progress and keep up with the times. Whether or not that paraphrasal is something the rest of the Git community agrees with, though, is the whole reason I sent this doc up for review ;) So far I haven't seen any other disagreement than this mail, but we also haven't gotten a ton of reviews on this patch, less than half a dozen individuals. (By the way, "others may find Git too far gone and build something new instead" is actually already happening[1][2], including at Google.) > I'm sorry to have to complain about this, but it is a reality of exotic, non-linux, platforms that are still being maintained and active (the last major NonStop OS release was 11 months ago, and another is due to drop imminently, so this is not a dead or dying platform). The last thing I want to have is having users locked out of future git versions, based on the increasing adoption of git on NonStop that has been (immodestly said) mostly my fault. Can we solve this in some acceptable way? As it stands, we currently don't have any tooling available to make sure that changes we make work on NonStop, anyway - we basically need to take your word for it when something breaks, and that's quite difficult for the contributor base to cater to. So even if we were to relax the minimum requirement bits here, we'd have difficulty supporting NonStop in the capacity that you sound interested in. Do you have any suggestions to make NonStop easier to support in that regard? I wonder if it is better worth explaining what maintenance branch support users can expect - how long a given version will receive security patches, what kind of backporting work platform maintainers could reasonably do, and so on. Thoughts? - Emily 1: https://github.com/martinvonz/jj 2: https://sapling-scm.com/
On Thu, Jul 18, 2024 at 3:46 PM Junio C Hamano <gitster@pobox.com> wrote: [..snipped nits, I have fixed them for v4] > > +* You should run nightly tests against the `next` branch and publish breakage > > + reports to the mailing list immediately when they happen. > > Can't it be daily instead of nightly ;-), or is it better than > nothing if you can afford to run only once every other day? > > A topic (unless it is during the shuffle time around -rc0) usually > spends no less than 7 calendar days in 'next', so while I would > appreciate if somebody runs tests twice a day, in practice you > should be able to catch a new breakage in 'next' if you run a full > and thorough test twice a week. I ended up adding a sub-point to explain cadence preference and reasoning, since that's a lot to fit into a parenthetical. Thanks. > > > +* You should either: > > + > > +** Provide VM access on-demand to a trusted developer working to fix the issue, > > + so they can test their fix, OR > > "VM access on-demand" -> "on-demand access to your platform" (iow, > physical iron is also fine for our purpose). Done, thanks. > > +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 > > OK. > > > +* Has dependencies which were released in the past 10 years > > This is hard to understand and I wonder if we can clarify. I get > what you want to say: suppose we rely on library X that is getting > regular feature and security updates in reasonable cadence, say > every 6 months there is an upstream release of library X, but a > niche platform has ported the library only once long time ago, and > hasn't updated it ever since. Now the Git project may consider > helping a port to such a platform if the initial port of library X > was 8 years ago, but will not if it was 12 years ago. > > But if Git depends on an ultra stable library whose last public > release was 12 years ago, disqualify everybody is not what this > requirement wants to do. > > I attempted to formulate my version along ... > > Keep up with the versions of dependencies (libraries, etc.) and > not to lag behind compared to typical mainstream platforms by > more than X years. > > ... the above line, but to me it is no better than the original, so > I failed miserably. But the idea I am bringing to the table here is > that time of release is not absolute. If typical mainstream > platforms consider a release of a library made 8 years ago from the > upstream performant, functional, and secure enough and fit for use, > we do not consider that they are approaching the limit. But if > another platform uses the same library from 12 years ago, i.e. > lagging behind others by 4 years is a problem at the same graveness > using another library that was released 6 years ago, when other > platforms are using a much younger vintage of the same library > released at 2 years ago. Yeah, I think it makes sense to relax just a little bit more, and give ourselves flexibility to use common sense. I ended up with: """ * Uses versions of dependencies which are generally accepted as stable and supportable, e.g., in line with the version used by other long-term-support distributions """ It's not quite my favorite, still, because I guess that LTS distros could get to a point we don't want to support (do we really want to provide cutting-edge git features to a 25-year-old LTS distro, for example?). Plus, "just look at everyone else's homework and use that" feels a little weird. Will keep thinking on this, I'd welcome other suggestions for phrasing. > > Having said all that, everything I removed from my quote I found > agreeable. Very well written. Thanks. :) - Emily
Emily Shaffer <nasamuffin@google.com> writes: > It's not quite my favorite, still, because I guess that LTS distros > could get to a point we don't want to support (do we really want to > provide cutting-edge git features to a 25-year-old LTS distro, for > example?). Plus, "just look at everyone else's homework and use that" > feels a little weird. But essentially that is what we end up doing anyway, no? If a platform is used heavily by some of us, they get more attention because we would be the first to notice breakage on it. Like it or not, the population distribution of development community members on different platforms would not align with the population distribution of general public, but without access to and familiarlity with the platform, and without motivation and time we can spend on it, none of us would feel compelled to look into an issue that only surfaces on an unfamiliar platform. So it is inevitable that "you'd have better chance of being helped by us if you make it as similar to platforms that we are familiar with as you can" holds true. > Will keep thinking on this, I'd welcome other suggestions for phrasing. Likewise here.
On Thursday, July 25, 2024 2:53 PM, Emily Shaffer wrote: >On Thu, Jul 18, 2024 at 3:46 PM Junio C Hamano <gitster@pobox.com> wrote: > >[..snipped nits, I have fixed them for v4] > >> > +* You should run nightly tests against the `next` branch and >> > +publish breakage >> > + reports to the mailing list immediately when they happen. >> >> Can't it be daily instead of nightly ;-), or is it better than nothing >> if you can afford to run only once every other day? >> >> A topic (unless it is during the shuffle time around -rc0) usually >> spends no less than 7 calendar days in 'next', so while I would >> appreciate if somebody runs tests twice a day, in practice you should >> be able to catch a new breakage in 'next' if you run a full and >> thorough test twice a week. > >I ended up adding a sub-point to explain cadence preference and reasoning, since >that's a lot to fit into a parenthetical. Thanks. > >> >> > +* You should either: >> > + >> > +** Provide VM access on-demand to a trusted developer working to fix the >issue, >> > + so they can test their fix, OR >> >> "VM access on-demand" -> "on-demand access to your platform" (iow, >> physical iron is also fine for our purpose). > >Done, thanks. > >> > +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 >> >> OK. >> >> > +* Has dependencies which were released in the past 10 years >> >> This is hard to understand and I wonder if we can clarify. I get what >> you want to say: suppose we rely on library X that is getting regular >> feature and security updates in reasonable cadence, say every 6 months >> there is an upstream release of library X, but a niche platform has >> ported the library only once long time ago, and hasn't updated it ever >> since. Now the Git project may consider helping a port to such a >> platform if the initial port of library X was 8 years ago, but will >> not if it was 12 years ago. >> >> But if Git depends on an ultra stable library whose last public >> release was 12 years ago, disqualify everybody is not what this >> requirement wants to do. >> >> I attempted to formulate my version along ... >> >> Keep up with the versions of dependencies (libraries, etc.) and >> not to lag behind compared to typical mainstream platforms by >> more than X years. >> >> ... the above line, but to me it is no better than the original, so I >> failed miserably. But the idea I am bringing to the table here is >> that time of release is not absolute. If typical mainstream platforms >> consider a release of a library made 8 years ago from the upstream >> performant, functional, and secure enough and fit for use, we do not >> consider that they are approaching the limit. But if another platform >> uses the same library from 12 years ago, i.e. >> lagging behind others by 4 years is a problem at the same graveness >> using another library that was released 6 years ago, when other >> platforms are using a much younger vintage of the same library >> released at 2 years ago. > >Yeah, I think it makes sense to relax just a little bit more, and give ourselves flexibility >to use common sense. I ended up with: > >""" >* Uses versions of dependencies which are generally accepted as stable and > supportable, e.g., in line with the version used by other long-term-support > distributions >""" > >It's not quite my favorite, still, because I guess that LTS distros could get to a point >we don't want to support (do we really want to provide cutting-edge git features to >a 25-year-old LTS distro, for example?). Plus, "just look at everyone else's >homework and use that" >feels a little weird. A common practice across many commercial and Open Source projects is to fix LTS at a 5 year limit and usually for High-CVE class security fixes. That is, at least, when there is a commitment to retroactively fix problems. The Impression (from the outside of git - until about a year ago when "friends" fixes where done) is that the way to get a git fix is to upgrade. Somewhere in the middle would be more appropriate, I think. I do not think 25 year LTS is common, useful, or even likely, even for exotics (we use 5 year since a fixed announcement of a "closed selling date"). We could designate 2.46 as LTS 5 years from next week, as an example, which might not be so terrible. But LTS tends to be for qualified fixes only, like CVEs at a certain level, with functional stability (no enhancements allowed after a specific date - say "official release + 1 year"). OpenSSL is a bit more stringent, where once an LTS designated release moves past beta, there are no functional changes allowed, just bug fixes, and about a year later, just security fixes. When establishing an LTS, my core requirement is that I have a compatible supported compiler, not just a compiler available. For example, the minimum OS I support is 7 years old - 2 during active sales + 5 years after, which aligns with the vendor's OS policy. This also means that I might use c99, but only a fully supported c99+toolchain, not just one that is available that might run on the box. This means that any shipped binaries are not guaranteed to run on any OS version that is no longer supported, including the compilers on that version - probably more rigid than git would need though. May 2024 was a big month because a bunch of things were deprecated/dropped. This type of policy does take active product management, which, in gits case, would need volunteers who actively watch conditions on relevant platforms - I do that for the git builds on NonStop, so my team stops building git versions for dropped OS releases. My only issue there is cleaning up "dead" versions so people cannot download git builds that we are pretty sure will no longer run (there are complex reasons it is a difficult activity). ... but I have gone on too long, but LTS is a very heavy-weighted term with generally stringent rules. The above was really just context for decision-making around LTS, not specific comments about the content. Sorry. >Will keep thinking on this, I'd welcome other suggestions for phrasing. > >> >> Having said all that, everything I removed from my quote I found >> agreeable. Very well written.
On Tue, Jul 23, 2024 at 2:02 AM Patrick Steinhardt <ps@pks.im> wrote: > > On Thu, Jul 18, 2024 at 10:38:43AM -0700, Emily Shaffer wrote: > > +* 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. > > I found the latter part of this bullet point a bit weird. We don't yet > know about the specific pattern that may fail on any future supported > platform, so claiming that there are ways to avoid them goes a bit too > far, no? I guess I had in mind "some entry in contrib/ that happens at compile time" or "some preprocessor define hack that happens at compile time" or "???", which is where I got "a few" from. I can drop it, it is wordy and "we want to work with you to find something that doesn't suck for everyone" is the important part. Thanks. > > > +** 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. > > Do we maybe want to replace "from now" with "from when you add them"? Sure, thanks. > > Other than that this document looks great to me, thanks! Thanks for the review. - Emily > > Patrick
On Tue, Jul 23, 2024 at 2:49 PM Josh Steadmon <steadmon@google.com> wrote: > > On 2024.07.18 10:38, Emily Shaffer wrote: > > 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@google.com> > > > > --- > > > > 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@google.com/ > > --- > > 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 > > Typo: "maintstream" Oop, thanks :) > > > > + 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@googlegroups.com[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@mail.gmail.com/[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 > > +-------------------- > > It might make more sense to move this section immediately after the > introduction. I don't feel too strongly about it though. Yeah, I could see it: "here's a lot of nice things you could do, oh but just kidding at the very end we pull the rug and say actually your ancient/weird OS is not supported because it is missing XYZ" is not as nice as "hey, do you support XYZ? great start, these are the next things you need to do after." I'll move it and see about adding some clarification to make it flow (and definitely to not promise that with those minimum quals we will absolutely support your thing, full stop). > > > > +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@nexbridge.com> > > > Overall, looks good to me, thanks! Thanks for taking a look. - Emily >
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@googlegroups.com[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@mail.gmail.com/[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@nexbridge.com>
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@google.com> --- 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@google.com/ --- Documentation/Makefile | 1 + Documentation/technical/platform-support.txt | 177 +++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 Documentation/technical/platform-support.txt 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@googlegroups.com[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@mail.gmail.com/[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