On Tue, Jul 30, 2024 at 12:26 PM Junio C Hamano <gitster@xxxxxxxxx> wrote:
>
> Emily Shaffer <emilyshaffer@xxxxxxxxxx> 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
