| Message ID | 20240730175448.1727373-1-emilyshaffer@google.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v4] Documentation: add platform support policy | expand |
Emily Shaffer <emilyshaffer@google.com> writes: > My sense is that this doc is quite close, with the only open concern > being around the "Minimum Requirements" section and what they should > contain[1]. Would it be valuable for me to trim that part out and send > it as a follow-on patch for us to discuss in isolation, and merge the > rest of the document as it is now? Hopefully just resolving a few remaining "huh?" and it would be good. > diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt > new file mode 100644 > index 0000000000..e0e7a3c2d8 > --- /dev/null > +++ b/Documentation/technical/platform-support.txt > @@ -0,0 +1,187 @@ > +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. Most of this paragraph is about "stakeholders' platform" where the stakeholders are third-person, but the last sentence suddenly makes it "your" platform, which left a jarring sensation at least to me. "your platform" -> "platforms"? That does not sound like a huge improvement. "various platforms"? That is not all that better, either. All I can say is "your platform" sounded wrong, sorry. > +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 after "... and you may well find" reads a bit muddy. I couldn't tell if it is talking about the initial port, or continued support, or both. - The rest of this document is about continued support - You are expected to come up with the initial porting - If it will make the codebase too ugly with #ifdefs scattered all over the place in order to provide compatibility with your platform, we won't accept such an initial port. - It is even true if some contributors are willing to give support to such a platform. We won't promise that we will bend over backwards to support unreasonably exotic platforms. is what I read out of the paragraph. Is that the message we want to give them? > +* 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 mainstream 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. "and make sure" -> "to see if" and add something like "In your bug report, please mention clearly that it is a compatibility issue with your platform" at the end. In other words, we are interested in hearing both kinds of issues, but we do want to see your problem report marked clearly if it happens only on a particular platform. By the way, I do not see why this bullet item should be a subitem of the "nature of the breakage" item. It probably would read better to keep them independent and on equal footing. > +Compatible on `master` and releases > +----------------------------------- > + > +To make sure all stable builds and regular releases work for your platform the > +first time, help us avoid `master` breaking for your platform: "avoid `master` breaking" -> "avoid breaking `master`"? > +* You should run regular tests against the `next` branch and > + publish breakage reports to the mailing list immediately when they happen. > + > +** Ideally, these tests should run daily. At minimum, they should run weekly, as > + topics generally spend at least 7 days in `next` before graduating to > + `master`. Weekly would give an unlucky topic only 1 day, though. A report comes, and it may probably take a few days to stop the train, in order to validate the breakage report. > +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: "ensure `next` works" -> "ensure `next` always works"?
On Tue, Jul 30, 2024 at 12:26 PM Junio C Hamano <gitster@pobox.com> wrote: > > Emily Shaffer <emilyshaffer@google.com> writes: > > > My sense is that this doc is quite close, with the only open concern > > being around the "Minimum Requirements" section and what they should > > contain[1]. Would it be valuable for me to trim that part out and send > > it as a follow-on patch for us to discuss in isolation, and merge the > > rest of the document as it is now? > > Hopefully just resolving a few remaining "huh?" and it would be good. Makes sense, but I wish that we had heard back from Randall again about that section. I'm not sure what to do if we know he is unhappy with that part but haven't heard back from him again. (And I haven't heard overwhelming support from other contribs on that section, which would make it more appealing to accept the unhappiness if the rest of the community is in favor of the text as written.) > > > diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt > > new file mode 100644 > > index 0000000000..e0e7a3c2d8 > > --- /dev/null > > +++ b/Documentation/technical/platform-support.txt > > @@ -0,0 +1,187 @@ > > +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. > > Most of this paragraph is about "stakeholders' platform" where the > stakeholders are third-person, but the last sentence suddenly makes > it "your" platform, which left a jarring sensation at least to me. > > "your platform" -> "platforms"? That does not sound like a huge > improvement. "various platforms"? That is not all that better, > either. All I can say is "your platform" sounded wrong, sorry. Yeah, it is weird. I probably take this colloquial "you" in a bunch of places, so I'll skim through the whole doc again to see if I can find somewhere it feels unnatural, now that it's been a few weeks since I wrote it at first. For this one in specific, maybe "Various levels of platform-specific tooling will allow us to make more solid commitments around Git's compatibility with that platform"? To establish that we mean tooling _for the one platform the reader cares about_, not just tooling for any platform in general? Or maybe this sentence isn't that useful. I was trying to use it to warn the reader "in this doc there are tiers, you need to meet a tier if you want the level of support it provides", but that's also quite obvious just reading the tiers, right? > > > +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 after "... and you may well find" reads a bit muddy. I > couldn't tell if it is talking about the initial port, or continued > support, or both. > > - The rest of this document is about continued support > > - You are expected to come up with the initial porting > > - If it will make the codebase too ugly with #ifdefs scattered all > over the place in order to provide compatibility with your > platform, we won't accept such an initial port. > > - It is even true if some contributors are willing to give support > to such a platform. We won't promise that we will bend over > backwards to support unreasonably exotic platforms. > > is what I read out of the paragraph. Is that the message we want to > give them? I like that message, but what I was trying to say with that sentence was "if you get lucky, some volunteer might want to help you with the initial port". It seems worth at least pointing out that that would be the exception, not the rule, but I probably already do that well enough with the previous sentence ("the platform stakeholders are expected to do the bulk of the work"). Let me reword the last sentence, then: "We will consider patches that port a new platform if they don't make life harder for other support platforms or for Git contributors. Some Git contributors may volunteer to help with the initial or continued support, but that is not a given. Support work which is too intrusive or difficult for the project to maintain may still not be accepted." I think it still gets to your point... I was trying to avoid "unreasonably exotic" because that's very subjective, and the maintainer of that platform obviously doesn't think it's unreasonable, or else why would they be working on it :) > > > +* 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 mainstream 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. > > "and make sure" -> "to see if" > > and add something like "In your bug report, please mention clearly > that it is a compatibility issue with your platform" at the end. > > In other words, we are interested in hearing both kinds of issues, > but we do want to see your problem report marked clearly if it > happens only on a particular platform. > > By the way, I do not see why this bullet item should be a subitem > of the "nature of the breakage" item. It probably would read better > to keep them independent and on equal footing. Thanks, adjusted for all these comments. > > > +Compatible on `master` and releases > > +----------------------------------- > > + > > +To make sure all stable builds and regular releases work for your platform the > > +first time, help us avoid `master` breaking for your platform: > > "avoid `master` breaking" -> "avoid breaking `master`"? Oh way better, I couldn't figure out why this sentence sounded so awkward but that helps :) > > > +* You should run regular tests against the `next` branch and > > + publish breakage reports to the mailing list immediately when they happen. > > + > > +** Ideally, these tests should run daily. At minimum, they should run weekly, as > > + topics generally spend at least 7 days in `next` before graduating to > > + `master`. > > Weekly would give an unlucky topic only 1 day, though. A report > comes, and it may probably take a few days to stop the train, in > order to validate the breakage report. Thanks. I left it less prescriptive and added more reasoning: "They must run more often than weekly, as [... 7 days in next] ..., and it takes time to put the brakes on a patch once it lands in `next`." > > > +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: > > "ensure `next` works" -> "ensure `next` always works"? Done. Also noticed that I changed one link from "maintainer's guide" to "How to maintain Git" but not this one, changed this too. Will aim for a reroll around the end of the week, one way or another, I hope. - Emily
Emily Shaffer <nasamuffin@google.com> writes: >> > +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 after "... and you may well find" reads a bit muddy. I >> couldn't tell if it is talking about the initial port, or continued >> support, or both. >> ... > I like that message, but what I was trying to say with that sentence > was "if you get lucky, some volunteer might want to help you with the > initial port". FWIW, I do not quite like that message; I agree that it would be good to tell them that they may not entirely be on their own, if they ask nicely, but no promises ;-). > It seems worth at least pointing out that that would be > the exception, not the rule, but I probably already do that well > enough with the previous sentence ("the platform stakeholders are > expected to do the bulk of the work"). Let me reword the last > sentence, then: > > "We will consider patches that port a new platform if they don't make > life harder for other support platforms or for Git contributors. Some > Git contributors may volunteer to help with the initial or continued > support, but that is not a given. Support work which is too intrusive > or difficult for the project to maintain may still not be accepted." OK, at least that clarifies the point I was puzzled about.
On Tuesday, July 30, 2024 5:25 PM, Junio C Hamano wrote: >Emily Shaffer <nasamuffin@google.com> writes: > >>> > +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 after "... and you may well find" reads a bit muddy. I >>> couldn't tell if it is talking about the initial port, or continued >>> support, or both. >>> ... >> I like that message, but what I was trying to say with that sentence >> was "if you get lucky, some volunteer might want to help you with the >> initial port". > >FWIW, I do not quite like that message; I agree that it would be good to tell them >that they may not entirely be on their own, if they ask nicely, but no promises ;-). > >> It seems worth at least pointing out that that would be the exception, >> not the rule, but I probably already do that well enough with the >> previous sentence ("the platform stakeholders are expected to do the >> bulk of the work"). Let me reword the last sentence, then: >> >> "We will consider patches that port a new platform if they don't make >> life harder for other support platforms or for Git contributors. Some >> Git contributors may volunteer to help with the initial or continued >> support, but that is not a given. Support work which is too intrusive >> or difficult for the project to maintain may still not be accepted." > >OK, at least that clarifies the point I was puzzled about. Pulling in a paragraph from earlier on: > >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. This is a tough one. If a library is actively maintained and subject to security fixes, OS providers like the NonStop team will, as a general practice, provide security fixes. It might not be as frequent as I would personally like, but a 12 year old library with security holes would not really survive to be a problem. Others, where stability is well established, let's say iconv (a bad example, I know), will not get the attention to have it fixed until there is a customer reported issue (or me stomping up and down a lot). I think that the 8 vs. 12 year difference is fairly arbitrary and might not be appropriate. In some situations, if functionality is provided by an existing library, and is augmented, the platform maintainer could provide another compatibility component to supply the capabilities. It would be a strain, and in some cases impractical, but might be possible. I think a bigger issue is where there are dependencies introduced that are either not generally portable or depend on infrastructure that is also not portable. There is a long list of projects that are all interrelated and specific to the Linux space - all of which scare me as adding any of those would exclude git from platforms where those are not possible to port. Rust and GO, which have difficult-to-port code generators are two (Rust itself is problematic as one needs consent from the Rust maintainers to even add a platform, if you read deeply enough into the "porting" documentation). Products that must use gcc or clang with unavoidable syntax features that are not supported by ANSI C compilers and libraries are also things that keep me up at night because there really is no way to work around those. In some cases, some JSON and YAML libraries ended up having to be forked and are now (not happily but) maintained by my team - not a git issue. Ultimately, my goal as a platform maintainer is to be able to sleep at night without worrying that git support will be completely turned off by a feature that uses some incompatible library as part of the git core. Git LFS has had to be put aside because of the GO dependency, but because LFS is not core git, it is survivable. I think that if such incompatibilities are introduced, there should be a mechanism to isolate them, and exclude them from the git core. Please remember that git is now a central component to a vast number of organizations that depend on it for serving features to customers. To be blunt, it is not 2007 anymore, and git exists almost everywhere of significance. That point needs to be stressed. The pervasiveness of git has dramatically increased over the past 5 years, more than I think most people realized. On NonStop, 5 years ago, there was perhaps <10% participation. If you look now, the number has gone up, probably to somewhere around 60-70%. We cannot ignore that - I sincerely hope not anyway. There are even companies that will look at your GitHub footprint exclusively as your definitive resume for hiring purposes - I actually think that is really interesting and do not want to put that at risk either (although admittedly entirely beside the point of this thread). With Respect, Randall
On Tue, Jul 30, 2024 at 3:40 PM <rsbecker@nexbridge.com> wrote: > > On Tuesday, July 30, 2024 5:25 PM, Junio C Hamano wrote: > >Emily Shaffer <nasamuffin@google.com> writes: > > > >>> > +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 after "... and you may well find" reads a bit muddy. I > >>> couldn't tell if it is talking about the initial port, or continued > >>> support, or both. > >>> ... > >> I like that message, but what I was trying to say with that sentence > >> was "if you get lucky, some volunteer might want to help you with the > >> initial port". > > > >FWIW, I do not quite like that message; I agree that it would be good to tell them > >that they may not entirely be on their own, if they ask nicely, but no promises ;-). > > > >> It seems worth at least pointing out that that would be the exception, > >> not the rule, but I probably already do that well enough with the > >> previous sentence ("the platform stakeholders are expected to do the > >> bulk of the work"). Let me reword the last sentence, then: > >> > >> "We will consider patches that port a new platform if they don't make > >> life harder for other support platforms or for Git contributors. Some > >> Git contributors may volunteer to help with the initial or continued > >> support, but that is not a given. Support work which is too intrusive > >> or difficult for the project to maintain may still not be accepted." > > > >OK, at least that clarifies the point I was puzzled about. > > Pulling in a paragraph from earlier on: > > > >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. > > This is a tough one. If a library is actively maintained and subject to security fixes, OS providers > like the NonStop team will, as a general practice, provide security fixes. It might not be as frequent > as I would personally like, but a 12 year old library with security holes would not really survive > to be a problem. Others, where stability is well established, let's say iconv (a bad example, I > know), will not get the attention to have it fixed until there is a customer reported issue (or > me stomping up and down a lot). I think that the 8 vs. 12 year difference is fairly arbitrary > and might not be appropriate. > > In some situations, if functionality is provided by an existing library, and is augmented, the > platform maintainer could provide another compatibility component to supply the capabilities. > It would be a strain, and in some cases impractical, but might be possible. > > I think a bigger issue is where there are dependencies introduced that are either not > generally portable or depend on infrastructure that is also not portable. There is a long list > of projects that are all interrelated and specific to the Linux space - all of which scare me > as adding any of those would exclude git from platforms where those are not possible to > port. Rust and GO, which have difficult-to-port code generators are two (Rust itself is > problematic as one needs consent from the Rust maintainers to even add a platform, if you > read deeply enough into the "porting" documentation). Products that must use gcc or > clang with unavoidable syntax features that are not supported by ANSI C compilers and > libraries are also things that keep me up at night because there really is no way to work > around those. In some cases, some JSON and YAML libraries ended up having to be forked > and are now (not happily but) maintained by my team - not a git issue. > > Ultimately, my goal as a platform maintainer is to be able to sleep at night without > worrying that git support will be completely turned off by a feature that uses some > incompatible library as part of the git core. Git LFS has had to be put aside because of > the GO dependency, but because LFS is not core git, it is survivable. I think that if such > incompatibilities are introduced, there should be a mechanism to isolate them, and > exclude them from the git core. > > Please remember that git is now a central component to a vast number of organizations > that depend on it for serving features to customers. To be blunt, it is not 2007 anymore, > and git exists almost everywhere of significance. That point needs to be stressed. The > pervasiveness of git has dramatically increased over the past 5 years, more than I think > most people realized. On NonStop, 5 years ago, there was perhaps <10% participation. > If you look now, the number has gone up, probably to somewhere around 60-70%. We > cannot ignore that - I sincerely hope not anyway. There are even companies that will > look at your GitHub footprint exclusively as your definitive resume for hiring purposes - I > actually think that is really interesting and do not want to put that at risk either (although > admittedly entirely beside the point of this thread). I can understand the need for something that speaks the Git protocol and enables developers to develop. However, I guess I don't understand the need for that to be the latest version of Git, or even the C Git client to begin with. The protocol changes from time to time, but we're very careful - even compared to how careful we are about scripting compatibility on the C Git CLI - to provide backwards support for clients speaking older Git protocol. Why does it matter to NonStop, then, which client is being used or if it's sparkling brand new? Git is a central component to lots of things, you're right - at Google it's incredibly important, and our serving infrastructure is based around JGit, not C Git. It's integrated into lots of development tools like IDEs and notebooks and design software, and most of those use JGit or EGit or libgit2 or something. My point isn't "just fork Git" or "just use a different library", my point is "are you sure it's correct to worry about the Git client more than you worry about the Git protocol?" Anyway, I think we've gone pretty far afield. Let me resummarize my understanding of your thoughts on this patch so far: * Given the constraints that currently apply to NonStop, based on this doc, you are planning to run daily (or at least more frequent than weekly) tests against `next`, write detailed reports to the list as soon as you discover a problem (that is, before the problem series hits `master`, in most cases), and provide fixes yourself or work closely to test fixes others write in response to those reports. * Also given the constraints that currently apply to NonStop, a hard age limit on library dependencies would disqualify NonStop from explicit support assistance. v4 of this series drops the hard age limit on library dependencies. As written currently, is it still objectionable to you? - Emily
On Wednesday, July 31, 2024 1:20 PM, Emily Shaffer wrote: >On Tue, Jul 30, 2024 at 3:40 PM <rsbecker@nexbridge.com> wrote: >> >> On Tuesday, July 30, 2024 5:25 PM, Junio C Hamano wrote: >> >Emily Shaffer <nasamuffin@google.com> writes: >> > >> >>> > +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 after "... and you may well find" reads a bit muddy. I >> >>> couldn't tell if it is talking about the initial port, or >> >>> continued support, or both. >> >>> ... >> >> I like that message, but what I was trying to say with that >> >> sentence was "if you get lucky, some volunteer might want to help >> >> you with the initial port". >> > >> >FWIW, I do not quite like that message; I agree that it would be good >> >to tell them that they may not entirely be on their own, if they ask nicely, but no >promises ;-). >> > >> >> It seems worth at least pointing out that that would be the >> >> exception, not the rule, but I probably already do that well enough >> >> with the previous sentence ("the platform stakeholders are expected >> >> to do the bulk of the work"). Let me reword the last sentence, then: >> >> >> >> "We will consider patches that port a new platform if they don't >> >> make life harder for other support platforms or for Git >> >> contributors. Some Git contributors may volunteer to help with the >> >> initial or continued support, but that is not a given. Support work >> >> which is too intrusive or difficult for the project to maintain may still not be >accepted." >> > >> >OK, at least that clarifies the point I was puzzled about. >> >> Pulling in a paragraph from earlier on: >> >> > >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. >> >> This is a tough one. If a library is actively maintained and subject >> to security fixes, OS providers like the NonStop team will, as a >> general practice, provide security fixes. It might not be as frequent >> as I would personally like, but a 12 year old library with security >> holes would not really survive to be a problem. Others, where >> stability is well established, let's say iconv (a bad example, I >> know), will not get the attention to have it fixed until there is a customer reported >issue (or me stomping up and down a lot). I think that the 8 vs. 12 year difference is >fairly arbitrary and might not be appropriate. >> >> In some situations, if functionality is provided by an existing >> library, and is augmented, the platform maintainer could provide another >compatibility component to supply the capabilities. >> It would be a strain, and in some cases impractical, but might be possible. >> >> I think a bigger issue is where there are dependencies introduced that >> are either not generally portable or depend on infrastructure that is >> also not portable. There is a long list of projects that are all >> interrelated and specific to the Linux space - all of which scare me >> as adding any of those would exclude git from platforms where those >> are not possible to port. Rust and GO, which have difficult-to-port >> code generators are two (Rust itself is problematic as one needs >> consent from the Rust maintainers to even add a platform, if you read >> deeply enough into the "porting" documentation). Products that must >> use gcc or clang with unavoidable syntax features that are not >> supported by ANSI C compilers and libraries are also things that keep me up at >night because there really is no way to work around those. In some cases, some >JSON and YAML libraries ended up having to be forked and are now (not happily >but) maintained by my team - not a git issue. >> >> Ultimately, my goal as a platform maintainer is to be able to sleep at >> night without worrying that git support will be completely turned off >> by a feature that uses some incompatible library as part of the git >> core. Git LFS has had to be put aside because of the GO dependency, >> but because LFS is not core git, it is survivable. I think that if >> such incompatibilities are introduced, there should be a mechanism to isolate >them, and exclude them from the git core. >> >> Please remember that git is now a central component to a vast number >> of organizations that depend on it for serving features to customers. >> To be blunt, it is not 2007 anymore, and git exists almost everywhere >> of significance. That point needs to be stressed. The pervasiveness of >> git has dramatically increased over the past 5 years, more than I think most people >realized. On NonStop, 5 years ago, there was perhaps <10% participation. >> If you look now, the number has gone up, probably to somewhere around >> 60-70%. We cannot ignore that - I sincerely hope not anyway. There are >> even companies that will look at your GitHub footprint exclusively as >> your definitive resume for hiring purposes - I actually think that is >> really interesting and do not want to put that at risk either (although admittedly >entirely beside the point of this thread). > >I can understand the need for something that speaks the Git protocol and enables >developers to develop. However, I guess I don't understand the need for that to be >the latest version of Git, or even the C Git client to begin with. The protocol changes >from time to time, but we're very careful - even compared to how careful we are >about scripting compatibility on the C Git CLI - to provide backwards support for >clients speaking older Git protocol. Why does it matter to NonStop, then, which >client is being used or if it's sparkling brand new? > >Git is a central component to lots of things, you're right - at Google it's incredibly >important, and our serving infrastructure is based around JGit, not C Git. It's >integrated into lots of development tools like IDEs and notebooks and design >software, and most of those use JGit or EGit or libgit2 or something. > >My point isn't "just fork Git" or "just use a different library", my point is "are you >sure it's correct to worry about the Git client more than you worry about the Git >protocol?" > >Anyway, I think we've gone pretty far afield. Let me resummarize my understanding >of your thoughts on this patch so far: > >* Given the constraints that currently apply to NonStop, based on this doc, you are >planning to run daily (or at least more frequent than >weekly) tests against `next`, write detailed reports to the list as soon as you discover >a problem (that is, before the problem series hits `master`, in most cases), and >provide fixes yourself or work closely to test fixes others write in response to those >reports. >* Also given the constraints that currently apply to NonStop, a hard age limit on >library dependencies would disqualify NonStop from explicit support assistance. > >v4 of this series drops the hard age limit on library dependencies. As written >currently, is it still objectionable to you? Staying on the latest git is not a requirement, although highly desirable. Any CVEs that impact git would have to be addressed in whatever fork is done, if that becomes necessary, which I assume we have to plan for. This is a bit of a regression, as we had a fork back in 2016 when the NonStop code was not fully integrated into C git - changing that was my primary contribution, with help from Jojo on our team. I would not be happy about reverting to the old manual process of applying patches by hand - git merge was not usually sufficient in those days - plus having to add separate tests that we had difficulty certifying. We also then have to publish the changes as part of GPL v2.0, which we did, and finally stopped having to do sharing the standard code base. As far as JGit, it is much less functional and does not build or run on NonStop due to dependencies that are also problematic (I may be wrong but I think it requires Java 17 for that, which is not yet available, nor will ever be on ia64). We used to recommend using JGit while the C git code was not fully reconciled with our variances, but JGit stopped working correctly around 2022 and I was unable to get any support to change that, at least at that time. That and the user community really likes having "git help" - no such animal is in JGit, and some of our base does not have direct Internet access where git is used (high security environments). The reason we went with C git is because it actually builds and tests correctly (with minor irrelevant exceptions in t9001 that no one on the boxes care about). It is the only CLI client that works properly, so losing it permanently (as in being stuck at an old version) would be undesirable. There is no GUI on NonStop, so no options there. To the actual question: I am actually fine (and happy) with dropping the age limit - to me this is arbitrary without an official LTS designation and does not address the fundamental compatibility issues that are unrelated to time. As above, the highest priority requirement for me is being able to continue to apply CVE-related patches to whatever code is ported and maintained. My own nightmare scenario is a git CVE (high) coming out that is only fixed in a version of git that I cannot build/deploy. That would result in the community having to drop git on a mandatory basis (serious concern). Compliance rules are typically to apply High CVE patches within a fixed timeframe, typically 30 days. --Randall
diff --git a/Documentation/Makefile b/Documentation/Makefile index 1bd23fbeef..0f55baa252 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..e0e7a3c2d8 --- /dev/null +++ b/Documentation/technical/platform-support.txt @@ -0,0 +1,187 @@ +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. + +Minimum Requirements +-------------------- + +The rest of this doc describes best practices for platforms to make themselves +easy to support. However, before considering support at all, platforms need to +meet the following minimum requirements: + +* Has C99 or C11 + +* 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 + +* Has active security support (taking security releases of dependencies, etc) + +These requirements are a starting point, and not sufficient on their own for the +Git community to be enthusiastic about supporting your platform. Maintainers of +platforms which do meet these requirements can follow the steps below to make it +more likely that Git updates will respect the platform's needs. + +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 link:../howto/maintain-git.txt["How to maintain Git"] for an + overview of which branches are used in the Git project, 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 mainstream 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, help us avoid `master` breaking for your platform: + +* You should run regular tests against the `next` branch and + publish breakage reports to the mailing list immediately when they happen. + +** Ideally, these tests should run daily. At minimum, they should run weekly, as + topics generally spend at least 7 days in `next` before graduating to + `master`. + +** 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 on-demand access to your platform 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. + We'll work case-by-case to look for 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. + +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 possible 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> --- My sense is that this doc is quite close, with the only open concern being around the "Minimum Requirements" section and what they should contain[1]. Would it be valuable for me to trim that part out and send it as a follow-on patch for us to discuss in isolation, and merge the rest of the document as it is now? New in v4: - Wording fixes in commit message and body - Clarify cadence for tests against 'next' - Attempt to clarify dependency version minimum requirement to something reasonable and flexible. Note: This section still probably needs better wording; I took a crack at it but it still feels awkward. Suggestions welcome, please. - Be more realistic about finding non-intrusive platform support approaches ("we'll look for" rather than "we'll definitely find and in fact know a few options in advance") - Move up "Minimum Requirements" section to the top, so we don't bait-and-switch maintainers of platforms who don't even meet the baseline but start making effort to set up testing infrastructure and so on. Thanks, - Emily v1 description at https://lore.kernel.org/git/20240709225042.2005233-1-emilyshaffer@google.com/ Passing docs build at https://github.com/nasamuffin/git/actions/runs/10167171645/job/28118949973 1: Thread starting around https://lore.kernel.org/git/00fa01dad96c$8fda8890$af8f99b0$@nexbridge.com/ --- Documentation/Makefile | 1 + Documentation/technical/platform-support.txt | 187 +++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 Documentation/technical/platform-support.txt Range-diff against v3: 1: 575c5a5a5f ! 1: 02fda7106e Documentation: add platform support policy @@ Metadata ## Commit message ## Documentation: add platform support policy - Supporting many platforms is only easy when we have the right tools to + Supporting many platforms is only possible when we have the right tools to ensure that support. Teach platform maintainers how they can help us to help them, by @@ Documentation/technical/platform-support.txt (new) +contributor interested in working on that support, but the Git community as a +whole doesn't feel an obligation to perform such work. + ++Minimum Requirements ++-------------------- ++ ++The rest of this doc describes best practices for platforms to make themselves ++easy to support. However, before considering support at all, platforms need to ++meet the following minimum requirements: ++ ++* Has C99 or C11 ++ ++* 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 ++ ++* Has active security support (taking security releases of dependencies, etc) ++ ++These requirements are a starting point, and not sufficient on their own for the ++Git community to be enthusiastic about supporting your platform. Maintainers of ++platforms which do meet these requirements can follow the steps below to make it ++more likely that Git updates will respect the platform's needs. ++ +Compatible by next release +-------------------------- + @@ Documentation/technical/platform-support.txt (new) + 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. ++ Policy" in link:../howto/maintain-git.txt["How to maintain Git"] for an ++ overview of which branches are used in the Git project, and how. + +* The bug report should include information about what platform you are using. + @@ Documentation/technical/platform-support.txt (new) + 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 ++ for a mainstream 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. @@ Documentation/technical/platform-support.txt (new) +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: ++first time, help us avoid `master` breaking for your platform: ++ ++* You should run regular tests against the `next` branch and ++ publish breakage reports to the mailing list immediately when they happen. + -+* You should run nightly tests against the `next` branch and publish breakage -+ reports to the mailing list immediately when they happen. ++** Ideally, these tests should run daily. At minimum, they should run weekly, as ++ topics generally spend at least 7 days in `next` before graduating to ++ `master`. + +** 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. @@ 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 ++** Provide on-demand access to your platform 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 @@ Documentation/technical/platform-support.txt (new) + +* 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. ++ We'll work case-by-case to look for 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. @@ Documentation/technical/platform-support.txt (new) +* 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 +-------------------- +