Re: [PATCH v4] Documentation: add platform support policy

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 30, 2024, 19:26 UTC
Message-ID: <xmqq7cd2bs0q.fsf@gitster.g>
In-Reply-To: <20240730175448.1727373-1-emilyshaffer@google.com>

Emily Shaffer <emilyshaffer@google.com> writes:

Show 5 quoted lines

> 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.

Show 16 quoted lines

> 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.

Show 7 quoted lines

> +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?

Show 10 quoted lines

> +* 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.

Show 5 quoted lines

> +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`"?

Show 6 quoted lines

> +* 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.

Show 7 quoted lines

> +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"?