| Message ID | 20240711232413.693444-1-emilyshaffer@google.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v2] Documentation: add platform support policy | expand |
Emily Shaffer <emilyshaffer@google.com> writes: > +Platform Support Policy > +======================= Paraphrasing a bit for my understanding (read: not suggestions to rewrite), with some comments (read: might suggest rewrites). > +Git has a history of providing broad "support" for exotic platforms and older > +platforms, without an explicit commitment. There currently is no level of guarantees given. > +This support becomes easier to > +maintain (and possible to commit to) We want to give better support and certain levels of guarantees? (this is left unsaid, though). If we don't want that, then we would not care what would make the support easier to maintain, so that's implied. Do we want to make it more explicit? Perhaps Stakeholders of such platforms, however, may want to have a more predictable support commitments. It would require ... > when Git developers are provided with > +adequate tooling to test for compatibility. ... platform stakeholders to supply Git developers adequate tooling to test for compatibility and to develop workarounds for platform specific quirks, which may be hard to find for such exotic and/or older platforms without platform stakeholders' involvement. > Various levels of tooling will > +allow us to make more solid commitments around Git's compatibility with your > +platform. Good. All of this document assumes that a working port of Git once existed in the near past for a platform, and we outline the levels of investment platform stakeholders can make in order to keep it working, and expected outcome depending on the level of their investment. The document does not cover "I now have this exotic box---could you port Git to it?" Is it something we want to clarify in this part of the document? > +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? > +* Once we begin to fix the issue, please work closely with the contributor > +working on it to test the proposed fix against your platform. This is a source to be reformatted by AsciiDoc so it _should not_ matter [*], but I find it utterly unreadable if a bulletted list of paragraphs are formatted like the above. Side note: ... but it does matter because what we look at while editing is this .txt source file. I locally reformatted the above like so: 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. to have the second and subsequent lines indented to begin at the same column as the first line, and have a blank line between bulletted list entries, which made it easier to scan the source text. Such a reformatting did not appear to make any changes when the resulting HTML file was rendered (via "lynx -dump"). This might be my personal preference, and if other people prefer the more dense form used inthe patch, then I wouldn't complain. Regarding this point. > +* 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? How deep do we expect platform stakeholders to dig in their initial contact to us? In order to make a firm "It is a memory alignment issue" would be helped by having otherwise identical version of Git built from the same source on a more mainstream platform (say, Debian GNU/Linux running on x86_64) and the exotic platform in question, to be able to say "Ahh, x86 is lenient to unaligned access and that is why this problem wasn't noticed by developers, but on my platform this matters". Is such a comparison something we may want to hint here? Perhaps at the end of "use git-bisect to find the exact commit", add something like Build Git from exactly the same source files on your platform and one of the mainstream platforms and see if the problem you noticed appears on both, or only on your platform. If the former, the suggestions in this document does not apply, but of course we do greatly appreciate such a bug report that will help users of every platform. Note that the above would apply equally for any compatibility levels, not limited to those who expect "by next release". > +Example: NonStop > +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports > +problems] when they're noticed. > + > +Compatible on `master` and point releases > +----------------------------------------- > + > +To guarantee that `master` and all point releases work for your platform the > +first time: > + > +* You should run nightly tests against the `next` branch and publish breakage > +reports to the mailing list immediately when they happen. > +** 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). Also, the same problem that was reported yesterday for yesterday's 'next' does not have to be reported for today's 'next', even if they are different, as long as the breakage is the same. > +Compatible on `next` > +-------------------- > + > +To guarantee that `next` will work for your platform, avoiding reactive > +debugging and fixing: Applies to the phrasing at the beginning of the previous section as well, but I found it easier to read if you flipped the order from "do Y and you get X" from "you want X, so do Y", e.g. We can avoid reactive debugging and fixing, if you make sure 'next' keeps working for your platform. Do we assume that readers are familiar with the way how `master` and `next` are used? Otherwise We can avoid reactive debugging and fixing, if you make sure the 'next' branch keeps working for your platform. The changes in this branch are what the developers finished reviewing and are expected to appear in the next tagged release. Unless you stop them, that is. > +* 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. I am a bit surprised that nobody from GitLab complained so far, but the contents of the ci/ hierarchy has been reorganized and it is my understanding that we now consider both GitLab CI and GitHub Actions first-class citizens. > +** 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. Again, "do not be too noisy" principle should be stressed, no? If it breaks only on the exotic platform in question, please do notify, but if the breakage is shared with all the other platforms, then...?
On Fri, Jul 12, 2024 at 11:15 AM Junio C Hamano <gitster@pobox.com> wrote: > > Emily Shaffer <emilyshaffer@google.com> writes: > > > +Platform Support Policy > > +======================= > > Paraphrasing a bit for my understanding (read: not suggestions to > rewrite), with some comments (read: might suggest rewrites). > > > +Git has a history of providing broad "support" for exotic platforms and older > > +platforms, without an explicit commitment. > > There currently is no level of guarantees given. > > > +This support becomes easier to > > +maintain (and possible to commit to) > > We want to give better support and certain levels of guarantees? > (this is left unsaid, though). I guess? Really the way I think of it is: we don't care if we aren't guaranteeing your platform, but if you want us to care, you need to make it easy for us. We will not do frustrating support work (post a patch, wait 2 weeks for someone to notice it broke, try to fix it with no repro and limited info, wait another 2 weeks to find out the "fix" still didn't work, etc). I think that's a distinction without much difference, though :) > If we don't want that, then we would not care what would make > the support easier to maintain, so that's implied. Do we want > to make it more explicit? Perhaps > > Stakeholders of such platforms, however, may want to have a more > predictable support commitments. It would require ... > > > when Git developers are provided with > > +adequate tooling to test for compatibility. > > ... platform stakeholders to supply Git developers adequate > tooling to test for compatibility and to develop workarounds for > platform specific quirks, which may be hard to find for such > exotic and/or older platforms without platform stakeholders' > involvement. If I fudge with the rewrite a little, I get: """ 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. """ Trying to capture: * our current "support" is implicit and could break whenever, doesn't that scare you? * if you want something better, we need tooling from you * generally, the tooling needs to let us self-test things against your platform * you don't have to do it all, but you get less if you do less I left out the part about platform-specific things being hard to find without having access to the platform; that seemed to go without saying. But maybe I'm wrong there. > > > Various levels of tooling will > > +allow us to make more solid commitments around Git's compatibility with your > > +platform. > > Good. > > All of this document assumes that a working port of Git once existed > in the near past for a platform, and we outline the levels of > investment platform stakeholders can make in order to keep it > working, and expected outcome depending on the level of their > investment. The document does not cover "I now have this exotic > box---could you port Git to it?" > > Is it something we want to clarify in this part of the document? Clarified like so in my local copy, we can nitpick it a little before I send v3 though: """ 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. """ Trying to capture: * This is only for maintenance * If you want to bring up a new platform, that's on you * of course, individuals do what they want, so you MIGHT find someone to help, but no promises > > > +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? > > +* Once we begin to fix the issue, please work closely with the contributor > > +working on it to test the proposed fix against your platform. > > This is a source to be reformatted by AsciiDoc so it _should not_ > matter [*], but I find it utterly unreadable if a bulletted list of > paragraphs are formatted like the above > > Side note: ... but it does matter because what we look at while > editing is this .txt source file. > > I locally reformatted the above like so: > > 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. > > to have the second and subsequent lines indented to begin at the > same column as the first line, and have a blank line between > bulletted list entries, which made it easier to scan the source text. > Such a reformatting did not appear to make any changes when the > resulting HTML file was rendered (via "lynx -dump"). > > This might be my personal preference, and if other people prefer the > more dense form used inthe patch, then I wouldn't complain. Nah, I prefer it too, this is just what `<ESC>gq` gave me at first. Will fix. The way the nested bullets work in asciidoc they are still justified all the way to the left, which means when I align to the space after the last * I only get a one-space indent. Is this readable, or should I indent more? """ * 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. """ > > Regarding this point. > > > +* 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? > > How deep do we expect platform stakeholders to dig in their initial > contact to us? In order to make a firm "It is a memory alignment > issue" would be helped by having otherwise identical version of Git > built from the same source on a more mainstream platform (say, > Debian GNU/Linux running on x86_64) and the exotic platform in > question, to be able to say "Ahh, x86 is lenient to unaligned access > and that is why this problem wasn't noticed by developers, but on my > platform this matters". Is such a comparison something we may want > to hint here? Perhaps at the end of "use git-bisect to find the > exact commit", add something like > > Build Git from exactly the same source files on your platform > and one of the mainstream platforms and see if the problem you > noticed appears on both, or only on your platform. If the > former, the suggestions in this document does not apply, but of > course we do greatly appreciate such a bug report that will help > users of every platform. > > Note that the above would apply equally for any compatibility > levels, not limited to those who expect "by next release". Captured a paraphrasing of that. I like that your suggestion doesn't get into "how to diagnose that it's *actually* a memory alignment problem", but instead is a general reminder to make sure it really is a platform-specific issue; it seems to me that that should be common sense, but I don't mind calling it out anyway here :) > > > +Example: NonStop > > +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports > > +problems] when they're noticed. > > + > > +Compatible on `master` and point releases > > +----------------------------------------- > > + > > +To guarantee that `master` and all point releases work for your platform the > > +first time: > > + > > +* You should run nightly tests against the `next` branch and publish breakage > > +reports to the mailing list immediately when they happen. > > +** 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). > > Also, the same problem that was reported yesterday for yesterday's > 'next' does not have to be reported for today's 'next', even if they > are different, as long as the breakage is the same. Called out, thanks. > > > +Compatible on `next` > > +-------------------- > > + > > +To guarantee that `next` will work for your platform, avoiding reactive > > +debugging and fixing: > > Applies to the phrasing at the beginning of the previous section as > well, but I found it easier to read if you flipped the order from > "do Y and you get X" from "you want X, so do Y", e.g. Clarified, and tried to clarify in previous couple sections too, although I think they were not so bad as this one. > > We can avoid reactive debugging and fixing, if you make sure > 'next' keeps working for your platform. > > Do we assume that readers are familiar with the way how `master` and > `next` are used? Otherwise > > We can avoid reactive debugging and fixing, if you make sure the > 'next' branch keeps working for your platform. The changes in > this branch are what the developers finished reviewing and are > expected to appear in the next tagged release. Unless you stop > them, that is. We linked to how-to-maintain-git earlier in the doc, I linked it again here for people who are skimming. Thanks. > > > +* 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. > > I am a bit surprised that nobody from GitLab complained so far, but > the contents of the ci/ hierarchy has been reorganized and it is my > understanding that we now consider both GitLab CI and GitHub Actions > first-class citizens. Added GitLab too and generalized the text referring to GitHub specifically further down in the doc. We already have a point about "if the existing CI doesn't work, you can roll your own" so I didn't try to expand on it more than I already did below, though. > > > +** 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. > > Again, "do not be too noisy" principle should be stressed, no? If > it breaks only on the exotic platform in question, please do notify, > but if the breakage is shared with all the other platforms, then...? I am not sure if I mind, if it's going to individual and not to the entire list. I get redundant breakages in GitHub Actions runner review if I left off a semicolon, too, right? Maybe I should stress more that these don't belong on the list, though?
Emily Shaffer <nasamuffin@google.com> writes: > If I fudge with the rewrite a little, I get: > > """ > 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. > """ This reads well. > """ > 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. > """ The part before "We will consider" reads very well. The part after that, I haven't formed a firm opinion on (yet). > """ > * 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. > """ Looking good, I guess. THanks.
On Mon, Jul 15, 2024 at 4:46 PM Junio C Hamano <gitster@pobox.com> wrote: > > Emily Shaffer <nasamuffin@google.com> writes: > > > If I fudge with the rewrite a little, I get: > > > > """ > > 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. > > """ > > This reads well. > > > """ > > 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. > > """ > > The part before "We will consider" reads very well. The part after > that, I haven't formed a firm opinion on (yet). > > > """ > > * 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. > > """ > > Looking good, I guess. It seems like there's not much more in contention from the current responses to this thread and v2. I've got a reroll ready with mostly wording/formatting changes based on your reply. I asked Johannes if he wanted to take a look on Discord[1], it seemed like he wasn't interested in doing a full review and doesn't want his name on the maintainer list: me: @dscho did you see https://lore.kernel.org/git/20240711232413.693444-1-emilyshaffer@google.com/ ? do you want to be written down as windows maintainer? or does this policy differ enough from the way GfW works that it doesn't make sense for you? [...] dscho: That document makes sense for Git, including on the NonStop platform. dscho: For Git for Windows, the processes are substantially different, for example: not using a Git mailing list but instead GitHub discussions, issues and pull requests. Also, there is no seen, next, master nor maint. There's main. me: yeah, I guess I'm really asking - does this do enough for what you need to make your GfW fork work dscho: So: Thank you for notifying me and asking; I think it'll be fine without my name in it. What's next to move this patch forward? Should I be asking around for more people to review it? Or do you think it's close enough to ready that I should send v3 without waiting longer so you can take it? I took a look at DecisionMaking.txt but don't see that there's a clear answer; of the people participating in this thread my impression is that we have consensus, but there's also not that many people participating. - Emily 1: https://discord.com/channels/1042895022950994071/1156706741875130499/1262827182162575471 (requires Discord login and Git server membership :/)
On Tuesday, July 16, 2024 1:59 PM, Emily Shaffer wrote: >On Mon, Jul 15, 2024 at 4:46 PM Junio C Hamano <gitster@pobox.com> wrote: >> >> Emily Shaffer <nasamuffin@google.com> writes: >> >> > If I fudge with the rewrite a little, I get: >> > >> > """ >> > 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. >> > """ >> >> This reads well. >> >> > """ >> > 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. >> > """ >> >> The part before "We will consider" reads very well. The part after >> that, I haven't formed a firm opinion on (yet). >> >> > """ >> > * 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. >> > """ >> >> Looking good, I guess. > >It seems like there's not much more in contention from the current responses to >this thread and v2. I've got a reroll ready with mostly wording/formatting changes >based on your reply. > >I asked Johannes if he wanted to take a look on Discord[1], it seemed like he wasn't >interested in doing a full review and doesn't want his name on the maintainer list: > >me: @dscho did you see >https://lore.kernel.org/git/20240711232413.693444-1- >emilyshaffer@google.com/ >? do you want to be written down as windows maintainer? or does this policy differ >enough from the way GfW works that it doesn't make sense for you? >[...] >dscho: That document makes sense for Git, including on the NonStop platform. Putting it the way below, we could use my team's GitHub Issues list for our fork (we haven't used the fork since 3.0 happened and we finally got to the same code base). The repo is still there, if this team wants it, but I think the general mailing list for NonStop issues is probably better. Most (by a long way) of our issues have ultimately been of general interest. My community is rather shy (not used to mailing lists) and also mostly blocking access to GitHub.com, so... mailing list for discussions. >dscho: For Git for Windows, the processes are substantially different, for example: >not using a Git mailing list but instead GitHub discussions, issues and pull requests. >Also, there is no seen, next, master nor maint. There's main. >me: yeah, I guess I'm really asking - does this do enough for what you need to make >your GfW fork work >dscho: So: Thank you for notifying me and asking; I think it'll be fine without my >name in it. > >What's next to move this patch forward? Should I be asking around for more people >to review it? Or do you think it's close enough to ready that I should send v3 >without waiting longer so you can take it? I took a look at DecisionMaking.txt but >don't see that there's a clear answer; of the people participating in this thread my >impression is that we have consensus, but there's also not that many people >participating. > > - Emily > >1: >https://discord.com/channels/1042895022950994071/1156706741875130499 >/1262827182162575471 >(requires Discord login and Git server membership :/)
Emily Shaffer <nasamuffin@google.com> writes: > What's next to move this patch forward? Should I be asking around for > more people to review it? This round has been out there long enough and without an updated round, the patch is unlikely to see more reviews, I would think. Let's see an updated version soon and see what happens.
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..b818e6a402 --- /dev/null +++ b/Documentation/technical/platform-support.txt @@ -0,0 +1,138 @@ +Platform Support Policy +======================= + +Git has a history of providing broad "support" for exotic platforms and older +platforms, without an explicit commitment. This support becomes easier to +maintain (and possible to commit to) when Git developers are 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. + +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? +* Once we begin to fix the issue, please work closely with the contributor +working on it to test the proposed fix against your platform. + +Example: NonStop +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports +problems] when they're noticed. + +Compatible on `master` and point releases +----------------------------------------- + +To guarantee that `master` and all point releases work for your platform the +first time: + +* You should run nightly tests against the `next` branch and publish breakage +reports to the mailing list immediately when they happen. +** 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). +* 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 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. +* 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 v2: - Added a "minimum requirements" list in response to brian and Kyle's suggestions. This doesn't mean "if you meet these requirements, we'll work hard to make sure Git works for you"; it means "if you don't meet these requirements, then your tests/runners/patches are not welcome." Would appreciate someone double-checking the language to make sure that's conveyed (nicely). Also, the list of requirements right now is very short, because I didn't want to make any assumptions :) so if there are more that I should add, please suggest them (or, maybe it makes more sense to suggest them as a follow-on patch). - Added a section for a list of platform maintainers so we know who to contact. I guess this could probably use dates (although we have the `git blame`) to ensure that it's not too stale. I didn't add Dscho, because I figured we had better double-check with him before signing him up to anything; will add him to CC for this round. I didn't add avarab for AIX because the last I heard about it was years ago; will CC him too. Are there others that people know of? - Fixed some typos Junio pointed out. I'm all thumbs. - Reworded the "if we break release, we'll fix by next release" language to be less specific and hopefully more honest. - Gave more detail about which branches are worth watching, and linked to the maintainer guide rather than the workflows guide. Also suggested watching `cabal`/security list. - Made testing turnaround time requirement less specific (and more intimidating). Happy to hear suggestions for rephrasing, I'm worried it may be a little rude as is. - Stopped mentioning coccicheck specifically; instead, invite people to discuss possible compatibility restrictions with the mailing list, as no one size fits all. I'd be happy to know if this is clear as written or not. - Recommended tests restricting use of platform features come with an expiration date, and why. If I didn't get the reasoning right, please let me know and suggest a rephrase. - Suggested that GitHub Actions aren't the only way to do on-demand CI, and if you come up with another way to do it that is as low-effort for developers, that's OK too. Thanks, - Emily v1 description at https://lore.kernel.org/git/20240709225042.2005233-1-emilyshaffer@google.com/ --- Documentation/Makefile | 1 + Documentation/technical/platform-support.txt | 138 +++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 Documentation/technical/platform-support.txt Range-diff against v1: 1: 71e537e11d ! 1: 653661002c Documentation: add platform support policy ## Documentation/Makefile ## @@ Documentation/Makefile: TECH_DOCS += technical/multi-pack-index @@ 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 providing with -+adequate tooling to test for compatibility. Variouis levels of tooling will ++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. + -+Compatible by vN+1 release ++Compatible by next release +-------------------------- + -+To increase probability that compatibility issues introduced in a point release -+will be fixed by the next point 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; it's better for you to watch `seen` -+than to watch `master`. See linkgit:gitworkflows[7] under "Graduation" for an -+overview of which branches are used in git.git, and how. ++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. @@ Documentation/technical/platform-support.txt (new) + +* 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). @@ Documentation/technical/platform-support.txt (new) +* You should either: +** Provide VM access on-demand to a trusted developer working to fix the issue, +so they can test their fix, OR -+** Work closely with the developer fixing the issue - testing turnaround to -+check whether the fix works for your platform should not be longer than a -+business day. ++** 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] @@ Documentation/technical/platform-support.txt (new) +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. +* If you rely on Git avoiding a specific pattern that doesn't work well with -+your platform (like a certain malloc pattern), if possible, add a coccicheck -+rule to ensure that pattern is not used. -+* If you rely on some configuration or behavior, add a test for it. You may -+find it easier to add a unit test ensuring the behavior you need than to add an -+integration test; either one works. Untested behavior is subject to breakage at -+any time. ++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 @@ Documentation/technical/platform-support.txt (new) +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>