[PATCH] Documentation: add platform support policy

[PATCH] Documentation: add platform support policy

[Emily Shaffer]

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 <nasamuffin@google.com>

---

Hi folks,

Some months ago, I branched the Rust discussion to talk about platform
support[1]. That discussion didn't go far, but with libification efforts
touching the Makefile and worrying about compatibility, it seems like a worthy
discussion to have. 

My goal with this document is that if we claim to support a given platform,
that platform should be easy for contributors to test against. And the
corollary, if we can't test against a given platform easily, we shouldn't be
assuring users on that platform that it will always work. I'm thinking of
platforms which rely on recent Git binaries but which we don't test against by
default, like NonStop[2] or AIX[3].

Right now, this doc talks about "guarantees." I used that phrasing based on
what I've observed to be an implicit expectation that we guarantee support; it
could be this isn't actually a guarantee that the community is willing to make,
so I am hoping we can discuss it and come up with the right term.

I'm hoping that this policy (or one like it) can clarify a "help us help you"
relationship with platform maintainers. If we can clearly define the resources
we need in order to guarantee that we're supporting a platform, then we can
make changes more confidently; if, instead, we make a serious effort to fix any
and all reported breakages, then all patches are at risk of breaking a platform
we didn't know exists but care about providing first-class support for and
being rolled back. I think there is some space in between those two extremes,
too, that might be suitable for some less-used platforms, or platforms which
follow new releases less closely.

Looking forward to discussing.

 - Emily

1: https://lore.kernel.org/git/CAJoAoZnHGTFhfR6e6r=GMSfVbSNgLoHF-opaWYLbHppiuzi+Rg@mail.gmail.com/ 
2: https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/ 
3: https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/
---
 Documentation/Makefile                       |   1 +
 Documentation/technical/platform-support.txt | 102 +++++++++++++++++++
 2 files changed, 103 insertions(+)
 create mode 100644 Documentation/technical/platform-support.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index dc65759cb1..462af0311f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -118,6 +118,7 @@ TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
+TECH_DOCS += technical/platform-support
 TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/scalar
diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt
new file mode 100644
index 0000000000..23ab708144
--- /dev/null
+++ b/Documentation/technical/platform-support.txt
@@ -0,0 +1,102 @@
+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 providing with
+adequate tooling to test for compatibility. Variouis levels of tooling will
+allow us to make more solid commitments around Git's compatibility with your
+platform.
+
+Compatible by vN+1 release
+--------------------------
+
+To increase probability that compatibility issues introduced in a point release
+will be fixed by the next point 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.
+* 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.
+* 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 - testing turnaround to
+check whether the fix works for your platform should not be longer than a
+business day.
+
+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 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.
+** 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.
+
+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.
-- 
2.45.2.803.g4e1b14247a-goog

Re: [PATCH] Documentation: add platform support policy

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 3323 bytes --]

On 2024-07-09 at 22:50:42, Emily Shaffer wrote:
> Right now, this doc talks about "guarantees." I used that phrasing based on
> what I've observed to be an implicit expectation that we guarantee support; it
> could be this isn't actually a guarantee that the community is willing to make,
> so I am hoping we can discuss it and come up with the right term.

I think it might be helpful to look at what some other projects do. Rust
has a concept of tiered support, and it requires platforms to have
maintainers who will commit to support an OS.  I don't think we
necessarily need to be so formal, but if nobody's stepping up to monitor
an OS or architecture, it may break at any time and we won't be able to
consider it when deciding on features we require from the platform (such
as Rust, C versions, or POSIX versions).

I think it's also worth discussing what we require from a platform we're
willing to support.  For example, we might require that the platform
pass the entire testsuite (ignoring irrelevant tests or tests for things
that platform doesn't use, such as Perl) or be actively pursuing an
attempt to do so.  We may also want to require that an OS be actively
receiving security support so that we don't have people asking us to
carry patches for actively obsolete OSes, such as CentOS 6.  Finally,
some sort of time limit may be helpful, since some Linux vendors are now
offering 15 years of support, and we really may not want to target
really ancient versions of things like libcurl.

At the same time, we do have people actively building Git on a variety
of platforms and a huge number of architectures, including most Linux
distros and the BSDs, and we will want to be cognizant that we should
avoid breaking those environments when possible, even though, say, the
porters for some of those OSes or architectures may not actively follow
the list (due to limited porters and lots of porting work).  I imagine
we might say that released architectures on certain distros (Debian
comes to mind as a very portable option) might be implicitly supported.

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

I think this is a particularly helpful approach.  I understand the Linux
runners support nested virtualization, so it's possible to run tests in
a VM on a Linux runner on OSes that Actions doesn't natively support.  I
do this for several of my Rust projects[0] on FreeBSD and NetBSD, for
example, and it should work on platforms that support Vagrant and run on
x86-64.

That won't catch things like alignment problems which don't affect
x86-64, but it does catch a lot of general portability problems that are
OS-related.

I'm in agreement with all of your suggestions, by the way, and I
appreciate you opening this discussion.

[0] An example for the curious is muter: https://github.com/bk2204/muter.
-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

Re: [PATCH] Documentation: add platform support policy

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

> +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 providing with

"providing"?  "provided"?

> +adequate tooling to test for compatibility. Variouis levels of tooling will

"Variouis"?

> +allow us to make more solid commitments around Git's compatibility with your
> +platform.
> +
> +Compatible by vN+1 release
> +--------------------------

I couldn't quite tell what you meant by vN+1 on the title.  If Git
v2.45.X were working fine on an un(der)maintained platform, and some
changes went into Git v2.46.0 were incompatible with it, then vN
would obviously be v2.46.0 but what is vN+1?  v2.47.0 or v2.46.1?

howto/maintain-git.txt calls v2.47.0 "the next feature release"
after v2.46.0, while v2.46.1 is "the first maintenance release".

> +To increase probability that compatibility issues introduced in a point release
> +will be fixed by the next point release:

So you meant "by v2.46.1 (or if you fail to notice breakage then it
might slip until v2.46.2)".  Is the procedure for the platform folks
any different if they target the next feature release?

I think what they need to do would not change all that much between
these two cases, so I'd suggest dropping a mention of "point
release".  I.e, "introduced in an earlier release will be fixed by a
future release".

A point release cannot introduce compatibility issues or any
breakages, but mistakes happen ;-) But for a receiver of a new bug,
it does not matter an iota if a point release or a major release
introduced an issue.

To recap, my suggestions for the above part are:

 - retitle to "Compatible by the next release"

 - "introduced in an earlier release will be fixed by a future
   release" without mentioning the nature of releases like point,
   feature, and maintenance.

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

Let's clarify what goal they want to achieve by "watching".

    ... for you to watch `seen` to prevent changes that break your
    platform from getting merged into `next`, than to watch `master`.

> See linkgit:gitworkflows[7] under "Graduation" for an
> +overview of which branches are used in git.git, and how.

Or "The Policy" section of howto/maintain-git.txt where the use of
each branch makes it a bit more clear what 'next' is for, and why
'seen' may be worth looking at by these people.


> +Compatible on `master` and point releases
> +-----------------------------------------
> +
> +To guarantee that `master` and all point releases work for your platform the
> +first time:

OK, as most of the changes go to `master` before getting merged down
to `maint` to become part of the next maintenance release, actively
protecting `master` from bugs is worthwhile.  What about changes
that do not come via the `master` branch?  Should they also join the
security list and have an early access to the cabal material?

> +* You should run nightly tests against the `next` branch and publish breakage
> +reports to the mailing list immediately when they happen.
> +* 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.

All of the above are actually applicable to any active contributors
on any platforms.  If your group feeds custom builds of Git out of
"master" to your $CORP customers, you want to ensure you catch
badness while it is still in "next" (or better yet, before it hits
"next").  If your internal builds are based on "next", you'd want to
ensure that "next" stays clean, which means you'd need to watch
"seen" (or better yet, patches floating on the list before they hit
"seen").  Your group may build with unusual toolchain internal to
your $CORP and may link with specialized libraries, etc., in which
case maintaining such a build is almost like maintaining an exotic
platform.

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

These are very specific, especially for minority platform folks.  I
agree with the direction, but "not be longer than" might be too
strong.  Longer turnaround time will certainly make the issue
resolution slower, but if the platform maintainer can stand it, that
is their choice.  Finding some volunteers among our developers who
are familiar with the code to help their problem with more patience
and can wait for more than a business day is also up to them.

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

This would be nice even if the platform maintainer do not care about
`next` occasionally breaking (i.e. keep `master` working, in the
previous section, or even find breakages on `master` before the next
feature release, in the section before that).

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

Sorry, but I do not quite follow you here.

In general, it is a bad idea to promise that we are willing to tie
our hands with coccicheck to satisfy needs by exotic platforms,
without first having a chance to see and evaluate such needs.

"if possible, add" -> "sometimes it may turn out to be a good idea
to add", perhaps?

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

A unit test may be easier to add than an end-to-end test, but given
that end-users and platform maintainers want to see Git work as a
whole (e.g., if you prepare two repositories and do "git push there
:refs/heads/foo" then it removes the 'foo' branch), an end-to-end
test would probably be more useful and robust way to ensure that a
feature you care about will keep working.

In any case, I am not sure the sentence that ends with "either one
works" is worth existing here in this document.  Two important points
to stress here are (1) add test to protect what you care about and (2)
otherwise you can keep both halves.

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Tue, Jul 9, 2024 at 5:57 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Emily Shaffer <emilyshaffer@google.com> writes:
>
> > +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 providing with
>
> "providing"?  "provided"?
>
> > +adequate tooling to test for compatibility. Variouis levels of tooling will
>
> "Variouis"?

Thanks, fixed both for next time there's a reroll ready.

>
> > +allow us to make more solid commitments around Git's compatibility with your
> > +platform.
> > +
> > +Compatible by vN+1 release
> > +--------------------------
>
> I couldn't quite tell what you meant by vN+1 on the title.  If Git
> v2.45.X were working fine on an un(der)maintained platform, and some
> changes went into Git v2.46.0 were incompatible with it, then vN
> would obviously be v2.46.0 but what is vN+1?  v2.47.0 or v2.46.1?
>
> howto/maintain-git.txt calls v2.47.0 "the next feature release"
> after v2.46.0, while v2.46.1 is "the first maintenance release".
>
> > +To increase probability that compatibility issues introduced in a point release
> > +will be fixed by the next point release:
>
> So you meant "by v2.46.1 (or if you fail to notice breakage then it
> might slip until v2.46.2)".  Is the procedure for the platform folks
> any different if they target the next feature release?
>
> I think what they need to do would not change all that much between
> these two cases, so I'd suggest dropping a mention of "point
> release".  I.e, "introduced in an earlier release will be fixed by a
> future release".
>
> A point release cannot introduce compatibility issues or any
> breakages, but mistakes happen ;-) But for a receiver of a new bug,
> it does not matter an iota if a point release or a major release
> introduced an issue.
>
> To recap, my suggestions for the above part are:
>
>  - retitle to "Compatible by the next release"
>
>  - "introduced in an earlier release will be fixed by a future
>    release" without mentioning the nature of releases like point,
>    feature, and maintenance.

Thanks for the thorough clarification, I hadn't thought in as much
detail as this :) Will make those edits.

>
> > +* 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`.
>
> Let's clarify what goal they want to achieve by "watching".

Fixed for next reroll.

>
>     ... for you to watch `seen` to prevent changes that break your
>     platform from getting merged into `next`, than to watch `master`.
>
> > See linkgit:gitworkflows[7] under "Graduation" for an
> > +overview of which branches are used in git.git, and how.
>
> Or "The Policy" section of howto/maintain-git.txt where the use of
> each branch makes it a bit more clear what 'next' is for, and why
> 'seen' may be worth looking at by these people.

Thanks, yeah, changed the link to point there instead.

>
>
> > +Compatible on `master` and point releases
> > +-----------------------------------------
> > +
> > +To guarantee that `master` and all point releases work for your platform the
> > +first time:
>
> OK, as most of the changes go to `master` before getting merged down
> to `maint` to become part of the next maintenance release, actively
> protecting `master` from bugs is worthwhile.  What about changes
> that do not come via the `master` branch?  Should they also join the
> security list and have an early access to the cabal material?

Good question, I actually am not sure of the answer. Does that make it
too easy for anybody to claim they maintain some random platform and
therefore they'd like to see all the RCE howtos weeks before they are
fixed? I guess that we already have distro packagers in security
list/cabal, so it may not be worse exposure than that.

>
> > +* You should run nightly tests against the `next` branch and publish breakage
> > +reports to the mailing list immediately when they happen.
> > +* 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.
>
> All of the above are actually applicable to any active contributors
> on any platforms.  If your group feeds custom builds of Git out of
> "master" to your $CORP customers, you want to ensure you catch
> badness while it is still in "next" (or better yet, before it hits
> "next").  If your internal builds are based on "next", you'd want to
> ensure that "next" stays clean, which means you'd need to watch
> "seen" (or better yet, patches floating on the list before they hit
> "seen").  Your group may build with unusual toolchain internal to
> your $CORP and may link with specialized libraries, etc., in which
> case maintaining such a build is almost like maintaining an exotic
> platform.

Hits close to home ;)

Does this mean that this part of the document should go somewhere else
and we should just use a pointer here? Is there a guide handy for "how
to soft-fork Git"?

>
> > +* 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.
>
> These are very specific, especially for minority platform folks.  I
> agree with the direction, but "not be longer than" might be too
> strong.  Longer turnaround time will certainly make the issue
> resolution slower, but if the platform maintainer can stand it, that
> is their choice.  Finding some volunteers among our developers who
> are familiar with the code to help their problem with more patience
> and can wait for more than a business day is also up to them.

Maybe something like this is better?

"Work closely with the developer fixing the issue; the turnaround to
check that a proposed fix works for your platform should be fast
enough that it doesn't hinder the developer working on that fix. If
the turnaround is too slow, fixing the issue may miss the next release
or the developer may lose interest in working on the fix at all."

This last bit seems harsh but might be a good reminder - in this
situation, the developer is a volunteer, and if that volunteer work is
artificially annoying, they can decide to stop doing it. Open to
rephrasing.

>
> > +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.
>
> This would be nice even if the platform maintainer do not care about
> `next` occasionally breaking (i.e. keep `master` working, in the
> previous section, or even find breakages on `master` before the next
> feature release, in the section before that).

I agree that it would be nice for any scenario :)

I was trying to link lower quality of service with lower investment;
it would be nice to have things from the "higher investment" tier, but
it's not really necessary for Git to be providing that worse quality
of service.

Would it be worth mentioning at the very beginning of the doc that
"it's OK if you pick and choose between different tiers, and we
appreciate anything that takes a higher investment, but these lists
should give you an impression of what you'll get from the level of
effort you want to provide yourself"? Probably not with that exact
phrasing, but to try and get that concept across, at least.

>
> > +* 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.
>
> Sorry, but I do not quite follow you here.
>
> In general, it is a bad idea to promise that we are willing to tie
> our hands with coccicheck to satisfy needs by exotic platforms,
> without first having a chance to see and evaluate such needs.
>
> "if possible, add" -> "sometimes it may turn out to be a good idea
> to add", perhaps?

Maybe it is better to ask them to discuss it with us on-list, and that
the result of that discussion may be that they should add some such
test? Or, do we want to firmly say, no coccicheck restrictions based
on platform, give us a CI runner or bust? I don't feel super strongly
either way - writing this section I was trying to come up with any way
to get on-demand ~instant (<1hr) feedback to any contributor, and this
seemed like one someone could do. That doesn't mean we have to let
them, if we don't like this way.

>
> > +* 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.
>
> A unit test may be easier to add than an end-to-end test, but given
> that end-users and platform maintainers want to see Git work as a
> whole (e.g., if you prepare two repositories and do "git push there
> :refs/heads/foo" then it removes the 'foo' branch), an end-to-end
> test would probably be more useful and robust way to ensure that a
> feature you care about will keep working.
>
> In any case, I am not sure the sentence that ends with "either one
> works" is worth existing here in this document.  Two important points
> to stress here are (1) add test to protect what you care about and (2)
> otherwise you can keep both halves.
>

Thanks, will do.


I've got a couple of changes locally but I'll hold off on the reroll
til the open phrasing questions get resolved, and I get through
brian's review as well, and maybe another day to see if Randall makes
a response, since I cc'd him too. Will aim to send out v2 Friday
latest (barring any combustion events at $dayjob). Thanks much for the
quick and thorough reply.

 - Emily

Re: [PATCH] Documentation: add platform support policy

[Kyle Lippincott]

On Tue, Jul 9, 2024 at 3:50 PM Emily Shaffer <emilyshaffer@google.com> wrote:
> +* 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.

Should we state that we reserve the right to reject these tests if
they would put what we feel is an excessive burden on the git
developers? i.e. a requirement to use C89 would be rejected
(obviously). a requirement to support 16-bit platforms would also be
rejected. I don't know that we need to list examples for what we'd
reject, they could be implied that we're likely to accept anything
else.

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

I think that we likely won't have the ability to investigate whether
it's _truly_ gone away ourselves, and there's no guarantee that the
person that added these tests will be able to vet it either (maybe
they've switched jobs, for example).

I think we should take a stance that may be considered hostile, but I
can't really think of a better one:
- there needs to be a regular (6 month? 12 month? no longer than 12
month surely...) reaffirmation by the interested party that this is
still a requirement for them. This comes in the form of updating a
date in the codebase, not just a message on the list. If this
reaffirmation does not happen, we are allowed to assume that this is
not needed anymore and remove the test that's binding us to supporting
that. We should probably go a step further and intentionally violate
the test condition, so that any builds done by the interested parties
break immediately (which should be caught by the other processes
documented here; if they don't break, then it was correct to remove
the restriction).
- _most_ of these restrictions should probably have a limited number
of reaffirmations? I feel like this needs to be handled on a
case-by-case basis, but I want us to be clear that just because we
accepted these restrictions in the past doesn't mean we will accept
them indefinitely.
- Just because there's a reaffirmation doesn't mean we're guaranteeing
we won't delete the test before the affirmation "expires". If there's
an urgent security need to do something, and it can't be done without
breaking this, we'll choose to break this test. If there's general
consensus to do something (adopt a new language standard version, for
example), there's no guarantee we'll wait until all the existing
affirmations expire.

The thinking here is that this test is imposing a restriction on the
git developers that we've agreed to take on as a favor: we are going
to restrict ourselves from doing X _for the time being_ not
necessarily because it'll break you, but because it's a bad experience
for the git developers to create a patch series that lands and then
gets backed out when the breakage on $non_standard_platform is
detected on seen/next/master.

Re: [PATCH] Documentation: add platform support policy

[Junio C Hamano]

Emily Shaffer <nasamuffin@google.com> writes:

>> > +Compatible on `master` and point releases
>> > +-----------------------------------------
>> > +
>> > +To guarantee that `master` and all point releases work for your platform the
>> > +first time:
>>
>> OK, as most of the changes go to `master` before getting merged down
>> to `maint` to become part of the next maintenance release, actively
>> protecting `master` from bugs is worthwhile.  What about changes
>> that do not come via the `master` branch?  Should they also join the
>> security list and have an early access to the cabal material?
>
> Good question, I actually am not sure of the answer. Does that make it
> too easy for anybody to claim they maintain some random platform and
> therefore they'd like to see all the RCE howtos weeks before they are
> fixed? I guess that we already have distro packagers in security
> list/cabal, so it may not be worse exposure than that.

Stopping at saying "You may want to ask to join the security list"
and then leave the vetting process out of the guidelines for the
contributor (i.e. out of this document) may strike a good balance.

We will obviously be careful about whom to add to the security list,
but that does not change where people hear about the list and apply
to join.

>> All of the above are actually applicable to any active contributors
>> on any platforms.
>> ...
>
> Hits close to home ;)
>
> Does this mean that this part of the document should go somewhere else
> and we should just use a pointer here? Is there a guide handy for "how
> to soft-fork Git"?

Once we have a contributor guidelines this is a good material to
migrate there, but that would probably wait after the dust from this
document settles.

> Maybe something like this is better?
>
> "Work closely with the developer fixing the issue; the turnaround to
> check that a proposed fix works for your platform should be fast
> enough that it doesn't hinder the developer working on that fix. If
> the turnaround is too slow, fixing the issue may miss the next release
> or the developer may lose interest in working on the fix at all."

I think that is a good approach to take.  "We will not promise to
wait for you if you are slow, and that is not limited to those who
are working on minority/niche platforms" is a good point to make.

>> > +* 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.
>>
>> Sorry, but I do not quite follow you here.
>>
>> In general, it is a bad idea to promise that we are willing to tie
>> our hands with coccicheck to satisfy needs by exotic platforms,
>> without first having a chance to see and evaluate such needs.
>>
>> "if possible, add" -> "sometimes it may turn out to be a good idea
>> to add", perhaps?
>
> Maybe it is better to ask them to discuss it with us on-list, and that
> the result of that discussion may be that they should add some such
> test? Or, do we want to firmly say, no coccicheck restrictions based
> on platform, give us a CI runner or bust? I don't feel super strongly
> either way - writing this section I was trying to come up with any way
> to get on-demand ~instant (<1hr) feedback to any contributor, and this
> seemed like one someone could do. That doesn't mean we have to let
> them, if we don't like this way.

Yes.  If you want to add additional constraints on how the codebase
does things, discuss it on list first and work with us to come up
with a way to without forcing too many unnecessary constraints on
other platforms.  It may result in keeping the generic codebase
pristine and free from #ifdef and having platform specific code
somewhere in compat/ but such details do not have to be spelled
out---they will be different case-by-case and we will hopefully
devise new and improved ways to deal with them.

RE: [PATCH] Documentation: add platform support policy

[rsbecker]

On Wednesday, July 10, 2024 2:56 PM, Emily Shaffer wrote:
>On Tue, Jul 9, 2024 at 5:57 PM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> Emily Shaffer <emilyshaffer@google.com> writes:
>>
>> > +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 providing with
>>
>> "providing"?  "provided"?
>>
>> > +adequate tooling to test for compatibility. Variouis levels of
>> > +tooling will
>>
>> "Variouis"?
>
>Thanks, fixed both for next time there's a reroll ready.
>
>>
>> > +allow us to make more solid commitments around Git's compatibility
>> > +with your platform.
>> > +
>> > +Compatible by vN+1 release
>> > +--------------------------
>>
>> I couldn't quite tell what you meant by vN+1 on the title.  If Git
>> v2.45.X were working fine on an un(der)maintained platform, and some
>> changes went into Git v2.46.0 were incompatible with it, then vN would
>> obviously be v2.46.0 but what is vN+1?  v2.47.0 or v2.46.1?
>>
>> howto/maintain-git.txt calls v2.47.0 "the next feature release"
>> after v2.46.0, while v2.46.1 is "the first maintenance release".
>>
>> > +To increase probability that compatibility issues introduced in a
>> > +point release will be fixed by the next point release:
>>
>> So you meant "by v2.46.1 (or if you fail to notice breakage then it
>> might slip until v2.46.2)".  Is the procedure for the platform folks
>> any different if they target the next feature release?
>>
>> I think what they need to do would not change all that much between
>> these two cases, so I'd suggest dropping a mention of "point release".
>> I.e, "introduced in an earlier release will be fixed by a future
>> release".
>>
>> A point release cannot introduce compatibility issues or any
>> breakages, but mistakes happen ;-) But for a receiver of a new bug, it
>> does not matter an iota if a point release or a major release
>> introduced an issue.
>>
>> To recap, my suggestions for the above part are:
>>
>>  - retitle to "Compatible by the next release"
>>
>>  - "introduced in an earlier release will be fixed by a future
>>    release" without mentioning the nature of releases like point,
>>    feature, and maintenance.
>
>Thanks for the thorough clarification, I hadn't thought in as much detail as this :)
>Will make those edits.
>
>>
>> > +* 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`.
>>
>> Let's clarify what goal they want to achieve by "watching".
>
>Fixed for next reroll.
>
>>
>>     ... for you to watch `seen` to prevent changes that break your
>>     platform from getting merged into `next`, than to watch `master`.
>>
>> > See linkgit:gitworkflows[7] under "Graduation" for an
>> > +overview of which branches are used in git.git, and how.
>>
>> Or "The Policy" section of howto/maintain-git.txt where the use of
>> each branch makes it a bit more clear what 'next' is for, and why
>> 'seen' may be worth looking at by these people.
>
>Thanks, yeah, changed the link to point there instead.
>
>>
>>
>> > +Compatible on `master` and point releases
>> > +-----------------------------------------
>> > +
>> > +To guarantee that `master` and all point releases work for your
>> > +platform the first time:
>>
>> OK, as most of the changes go to `master` before getting merged down
>> to `maint` to become part of the next maintenance release, actively
>> protecting `master` from bugs is worthwhile.  What about changes that
>> do not come via the `master` branch?  Should they also join the
>> security list and have an early access to the cabal material?
>
>Good question, I actually am not sure of the answer. Does that make it too easy for
>anybody to claim they maintain some random platform and therefore they'd like to
>see all the RCE howtos weeks before they are fixed? I guess that we already have
>distro packagers in security list/cabal, so it may not be worse exposure than that.
>
>>
>> > +* You should run nightly tests against the `next` branch and
>> > +publish breakage reports to the mailing list immediately when they happen.
>> > +* 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.
>>
>> All of the above are actually applicable to any active contributors on
>> any platforms.  If your group feeds custom builds of Git out of
>> "master" to your $CORP customers, you want to ensure you catch badness
>> while it is still in "next" (or better yet, before it hits "next").
>> If your internal builds are based on "next", you'd want to ensure that
>> "next" stays clean, which means you'd need to watch "seen" (or better
>> yet, patches floating on the list before they hit "seen").  Your group
>> may build with unusual toolchain internal to your $CORP and may link
>> with specialized libraries, etc., in which case maintaining such a
>> build is almost like maintaining an exotic platform.
>
>Hits close to home ;)

I hear that. Sometimes having an exotic platform and specialized libraries are overlapping. I am still stuck with 32-bit git because some of the available DLLs on NonStop are still only 32-bit - I'm working hard on changing that but it's not under my budget control.

On that subject, I think it is important to have known or designated platform maintainers for the exotics. The downside is that some people expect miracles from us - I just had one request to permanently preserve timestamps of files as they were at commit time. We're into weeks of explanations on why this is a bad idea. Nonetheless, there is a certain amount of responsibility that comes with maintaining a platform, and knowing whom to ask when there are issues. The platform maintainers also can provide needed (preemptive) feedback on dependency changes. I'm not sure how to encode that in a compatible policy, however.


>Does this mean that this part of the document should go somewhere else and we
>should just use a pointer here? Is there a guide handy for "how to soft-fork Git"?
>
>>
>> > +* 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.
>>
>> These are very specific, especially for minority platform folks.  I
>> agree with the direction, but "not be longer than" might be too
>> strong.  Longer turnaround time will certainly make the issue
>> resolution slower, but if the platform maintainer can stand it, that
>> is their choice.  Finding some volunteers among our developers who are
>> familiar with the code to help their problem with more patience and
>> can wait for more than a business day is also up to them.
>
>Maybe something like this is better?
>
>"Work closely with the developer fixing the issue; the turnaround to check that a
>proposed fix works for your platform should be fast enough that it doesn't hinder
>the developer working on that fix. If the turnaround is too slow, fixing the issue may
>miss the next release or the developer may lose interest in working on the fix at all."
>
>This last bit seems harsh but might be a good reminder - in this situation, the
>developer is a volunteer, and if that volunteer work is artificially annoying, they can
>decide to stop doing it. Open to rephrasing.
>
>>
>> > +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.
>>
>> This would be nice even if the platform maintainer do not care about
>> `next` occasionally breaking (i.e. keep `master` working, in the
>> previous section, or even find breakages on `master` before the next
>> feature release, in the section before that).
>
>I agree that it would be nice for any scenario :)
>
>I was trying to link lower quality of service with lower investment; it would be nice
>to have things from the "higher investment" tier, but it's not really necessary for Git
>to be providing that worse quality of service.
>
>Would it be worth mentioning at the very beginning of the doc that "it's OK if you
>pick and choose between different tiers, and we appreciate anything that takes a
>higher investment, but these lists should give you an impression of what you'll get
>from the level of effort you want to provide yourself"? Probably not with that exact
>phrasing, but to try and get that concept across, at least.
>
>>
>> > +* 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.
>>
>> Sorry, but I do not quite follow you here.
>>
>> In general, it is a bad idea to promise that we are willing to tie our
>> hands with coccicheck to satisfy needs by exotic platforms, without
>> first having a chance to see and evaluate such needs.
>>
>> "if possible, add" -> "sometimes it may turn out to be a good idea to
>> add", perhaps?
>
>Maybe it is better to ask them to discuss it with us on-list, and that the result of that
>discussion may be that they should add some such test? Or, do we want to firmly
>say, no coccicheck restrictions based on platform, give us a CI runner or bust? I
>don't feel super strongly either way - writing this section I was trying to come up
>with any way to get on-demand ~instant (<1hr) feedback to any contributor, and
>this seemed like one someone could do. That doesn't mean we have to let them, if
>we don't like this way.
>
>>
>> > +* 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.
>>
>> A unit test may be easier to add than an end-to-end test, but given
>> that end-users and platform maintainers want to see Git work as a
>> whole (e.g., if you prepare two repositories and do "git push there
>> :refs/heads/foo" then it removes the 'foo' branch), an end-to-end test
>> would probably be more useful and robust way to ensure that a feature
>> you care about will keep working.
>>
>> In any case, I am not sure the sentence that ends with "either one
>> works" is worth existing here in this document.  Two important points
>> to stress here are (1) add test to protect what you care about and (2)
>> otherwise you can keep both halves.
>>
>
>Thanks, will do.
>
>
>I've got a couple of changes locally but I'll hold off on the reroll til the open phrasing
>questions get resolved, and I get through brian's review as well, and maybe another
>day to see if Randall makes a response, since I cc'd him too. Will aim to send out v2
>Friday latest (barring any combustion events at $dayjob). Thanks much for the
>quick and thorough reply.

--Randall

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Tue, Jul 9, 2024 at 4:16 PM brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> On 2024-07-09 at 22:50:42, Emily Shaffer wrote:
> > Right now, this doc talks about "guarantees." I used that phrasing based on
> > what I've observed to be an implicit expectation that we guarantee support; it
> > could be this isn't actually a guarantee that the community is willing to make,
> > so I am hoping we can discuss it and come up with the right term.
>
> I think it might be helpful to look at what some other projects do. Rust
> has a concept of tiered support, and it requires platforms to have
> maintainers who will commit to support an OS.  I don't think we
> necessarily need to be so formal, but if nobody's stepping up to monitor
> an OS or architecture, it may break at any time and we won't be able to
> consider it when deciding on features we require from the platform (such
> as Rust, C versions, or POSIX versions).

It took me a little time to find it, so here's the link for others:
https://doc.rust-lang.org/nightly/rustc/platform-support.html

I do think it's interesting that while Rust splits their tiers based
on how much of it will definitely work (definitely builds+tests,
definitely builds, probably builds maybe), which is different from how
I sliced it by time (works on release, works on stable, works on
unstable). This kind of lines up with what you mentioned next about
the tests (or some subset) working, which I hadn't considered, either.

>
> I think it's also worth discussing what we require from a platform we're
> willing to support.  For example, we might require that the platform
> pass the entire testsuite (ignoring irrelevant tests or tests for things
> that platform doesn't use, such as Perl) or be actively pursuing an
> attempt to do so.  We may also want to require that an OS be actively
> receiving security support so that we don't have people asking us to
> carry patches for actively obsolete OSes, such as CentOS 6.  Finally,
> some sort of time limit may be helpful, since some Linux vendors are now
> offering 15 years of support, and we really may not want to target
> really ancient versions of things like libcurl.

I sort of wonder how much of this is taken care of by expressing
"fully supported" as "can run in GitHub Actions". Even if an LTS
distro is 12 years old and using ancient curl, will GitHub still be
able to run it in a VM/container? Maybe there's no such guarantee,
since you can hook up self-hosted runners (which sounds more appealing
if someone's got something weird enough it doesn't run well in a
container).

I'm not sure which of these requirements we'd want to enumerate - but
does it make sense to tack it onto the end of this doc? Something
like:

"""
Minimum Requirements
------

Even if tests or CI runners are added to guarantee support, supported
platforms must:

* Be compatible with C99
* Use curl vX.Y.Z or later
* Use zlib vA.B.C or later
...
"""

>
> At the same time, we do have people actively building Git on a variety
> of platforms and a huge number of architectures, including most Linux
> distros and the BSDs, and we will want to be cognizant that we should
> avoid breaking those environments when possible, even though, say, the
> porters for some of those OSes or architectures may not actively follow
> the list (due to limited porters and lots of porting work).  I imagine
> we might say that released architectures on certain distros (Debian
> comes to mind as a very portable option) might be implicitly supported.

Are they implicitly supported, or are they explicitly supported via
the GH runners? Or indirectly supported? For example, the Actions
suite tests on Ubuntu; at least once upon a time Ubuntu was derived
from Debian (is it still? I don't play with distros much anymore); so
would that mean that running tests in Ubuntu also implies they will
pass in Debian?

(By the way, I think we should probably just add a BSD test runner to
Actions config; we test on MacOS but that's not that closely related.
It seems like it might be a pretty easy lift to do that.)

>
> > +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.
>
> I think this is a particularly helpful approach.  I understand the Linux
> runners support nested virtualization, so it's possible to run tests in
> a VM on a Linux runner on OSes that Actions doesn't natively support.  I
> do this for several of my Rust projects[0] on FreeBSD and NetBSD, for
> example, and it should work on platforms that support Vagrant and run on
> x86-64.
>
> That won't catch things like alignment problems which don't affect
> x86-64, but it does catch a lot of general portability problems that are
> OS-related.
>
> I'm in agreement with all of your suggestions, by the way, and I
> appreciate you opening this discussion.
>
> [0] An example for the curious is muter: https://github.com/bk2204/muter.

Neat :)

> --
> brian m. carlson (they/them or he/him)
> Toronto, Ontario, CA

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

> >> > +* You should run nightly tests against the `next` branch and
> >> > +publish breakage reports to the mailing list immediately when they happen.
> >> > +* 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.
> >>
> >> All of the above are actually applicable to any active contributors on
> >> any platforms.  If your group feeds custom builds of Git out of
> >> "master" to your $CORP customers, you want to ensure you catch badness
> >> while it is still in "next" (or better yet, before it hits "next").
> >> If your internal builds are based on "next", you'd want to ensure that
> >> "next" stays clean, which means you'd need to watch "seen" (or better
> >> yet, patches floating on the list before they hit "seen").  Your group
> >> may build with unusual toolchain internal to your $CORP and may link
> >> with specialized libraries, etc., in which case maintaining such a
> >> build is almost like maintaining an exotic platform.
> >
> >Hits close to home ;)
>
> I hear that. Sometimes having an exotic platform and specialized libraries are overlapping. I am still stuck with 32-bit git because some of the available DLLs on NonStop are still only 32-bit - I'm working hard on changing that but it's not under my budget control.
>
> On that subject, I think it is important to have known or designated platform maintainers for the exotics. The downside is that some people expect miracles from us - I just had one request to permanently preserve timestamps of files as they were at commit time. We're into weeks of explanations on why this is a bad idea. Nonetheless, there is a certain amount of responsibility that comes with maintaining a platform, and knowing whom to ask when there are issues. The platform maintainers also can provide needed (preemptive) feedback on dependency changes. I'm not sure how to encode that in a compatible policy, however.

I think it's a pretty good idea to have a contact list written down
somewhere, yeah. Maybe something similarly-formatted to a MAINTAINERS
file. I don't feel bad if it's just appended to the bottom of this doc
til we find a better place to put it... or maybe we can put such a
contact list in compat/, since someone lost trying to figure out a
compatibility thing might be looking there anyway?

Who else would we put on there? I can think of you for NonStop from
the top of my head; that AIX breakage I dug up was reported by AEvar,
but it's also a few years old; and I could imagine putting Johannes
down for Windows. Maybe that's enough to start with.

By the way, Randall, should I be waiting for a more complete review of
this patch from you before I reroll?

 - Emily

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Wed, Jul 10, 2024 at 1:13 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Emily Shaffer <nasamuffin@google.com> writes:
>
> >> > +Compatible on `master` and point releases
> >> > +-----------------------------------------
> >> > +
> >> > +To guarantee that `master` and all point releases work for your platform the
> >> > +first time:
> >>
> >> OK, as most of the changes go to `master` before getting merged down
> >> to `maint` to become part of the next maintenance release, actively
> >> protecting `master` from bugs is worthwhile.  What about changes
> >> that do not come via the `master` branch?  Should they also join the
> >> security list and have an early access to the cabal material?
> >
> > Good question, I actually am not sure of the answer. Does that make it
> > too easy for anybody to claim they maintain some random platform and
> > therefore they'd like to see all the RCE howtos weeks before they are
> > fixed? I guess that we already have distro packagers in security
> > list/cabal, so it may not be worse exposure than that.
>
> Stopping at saying "You may want to ask to join the security list"
> and then leave the vetting process out of the guidelines for the
> contributor (i.e. out of this document) may strike a good balance.
>
> We will obviously be careful about whom to add to the security list,
> but that does not change where people hear about the list and apply
> to join.

Thanks, done.

> >> All of the above are actually applicable to any active contributors
> >> on any platforms.
> >> ...
> >
> > Hits close to home ;)
> >
> > Does this mean that this part of the document should go somewhere else
> > and we should just use a pointer here? Is there a guide handy for "how
> > to soft-fork Git"?
>
> Once we have a contributor guidelines this is a good material to
> migrate there, but that would probably wait after the dust from this
> document settles.

Ok. For now I'll leave it as-is.

>
> > Maybe something like this is better?
> >
> > "Work closely with the developer fixing the issue; the turnaround to
> > check that a proposed fix works for your platform should be fast
> > enough that it doesn't hinder the developer working on that fix. If
> > the turnaround is too slow, fixing the issue may miss the next release
> > or the developer may lose interest in working on the fix at all."
>
> I think that is a good approach to take.  "We will not promise to
> wait for you if you are slow, and that is not limited to those who
> are working on minority/niche platforms" is a good point to make.
>
> >> > +* 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.
> >>
> >> Sorry, but I do not quite follow you here.
> >>
> >> In general, it is a bad idea to promise that we are willing to tie
> >> our hands with coccicheck to satisfy needs by exotic platforms,
> >> without first having a chance to see and evaluate such needs.
> >>
> >> "if possible, add" -> "sometimes it may turn out to be a good idea
> >> to add", perhaps?
> >
> > Maybe it is better to ask them to discuss it with us on-list, and that
> > the result of that discussion may be that they should add some such
> > test? Or, do we want to firmly say, no coccicheck restrictions based
> > on platform, give us a CI runner or bust? I don't feel super strongly
> > either way - writing this section I was trying to come up with any way
> > to get on-demand ~instant (<1hr) feedback to any contributor, and this
> > seemed like one someone could do. That doesn't mean we have to let
> > them, if we don't like this way.
>
> Yes.  If you want to add additional constraints on how the codebase
> does things, discuss it on list first and work with us to come up
> with a way to without forcing too many unnecessary constraints on
> other platforms.  It may result in keeping the generic codebase
> pristine and free from #ifdef and having platform specific code
> somewhere in compat/ but such details do not have to be spelled
> out---they will be different case-by-case and we will hopefully
> devise new and improved ways to deal with them.

Ok. I've got a rephrasing for the next reroll; still thinking I can
get that sent by tomorrow latest. Thanks!

 - Emily

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Wed, Jul 10, 2024 at 12:11 PM Kyle Lippincott <spectral@google.com> wrote:
>
> On Tue, Jul 9, 2024 at 3:50 PM Emily Shaffer <emilyshaffer@google.com> wrote:
> > +* 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.
>
> Should we state that we reserve the right to reject these tests if
> they would put what we feel is an excessive burden on the git
> developers? i.e. a requirement to use C89 would be rejected
> (obviously). a requirement to support 16-bit platforms would also be
> rejected. I don't know that we need to list examples for what we'd
> reject, they could be implied that we're likely to accept anything
> else.

brian mentioned something similar in their review, to which I proposed
a minimum requirements field[1]; I think this would work for that too?
Thoughts?

> > +** 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.
>
> I think that we likely won't have the ability to investigate whether
> it's _truly_ gone away ourselves, and there's no guarantee that the
> person that added these tests will be able to vet it either (maybe
> they've switched jobs, for example).
>
> I think we should take a stance that may be considered hostile, but I
> can't really think of a better one:
> - there needs to be a regular (6 month? 12 month? no longer than 12
> month surely...) reaffirmation by the interested party that this is
> still a requirement for them. This comes in the form of updating a
> date in the codebase, not just a message on the list. If this
> reaffirmation does not happen, we are allowed to assume that this is
> not needed anymore and remove the test that's binding us to supporting
> that.

I like the idea of the date in code, because that's "polled" rather
than "pushed" - when I break the test, I can go look at it, and see a
condition like "Until July 1st, 2024" and say "well it's July 11th, so
I don't care, deleted!" - or, more likely, I can see that date expired
a year and a half ago :)

> We should probably go a step further and intentionally violate
> the test condition, so that any builds done by the interested parties
> break immediately (which should be caught by the other processes
> documented here; if they don't break, then it was correct to remove
> the restriction).

...but this seems harder to keep track of. Where are we remembering
these "due dates" and remembering to break them on purpose? I'm not
sure that there's a good way to enforce this.

> - _most_ of these restrictions should probably have a limited number
> of reaffirmations? I feel like this needs to be handled on a
> case-by-case basis, but I want us to be clear that just because we
> accepted these restrictions in the past doesn't mean we will accept
> them indefinitely.
> - Just because there's a reaffirmation doesn't mean we're guaranteeing
> we won't delete the test before the affirmation "expires". If there's
> an urgent security need to do something, and it can't be done without
> breaking this, we'll choose to break this test. If there's general
> consensus to do something (adopt a new language standard version, for
> example), there's no guarantee we'll wait until all the existing
> affirmations expire.

I honestly like this point more than the previous one. Limiting by a
number, even one that changes, feels less flexible than allowing
ourselves to say "enough of this nonsense, it's the Century of the
Fruitbat, we really want to use <C11 feature> so you can get
maintenance updates instead now".

>
> The thinking here is that this test is imposing a restriction on the
> git developers that we've agreed to take on as a favor: we are going
> to restrict ourselves from doing X _for the time being_ not
> necessarily because it'll break you, but because it's a bad experience
> for the git developers to create a patch series that lands and then
> gets backed out when the breakage on $non_standard_platform is
> detected on seen/next/master.

1: https://lore.kernel.org/git/CAO_smVjZ7DSPdL+KYCm2mQ=q55XbEH7Vu_jLxkAa5WTcD9rq8A@mail.gmail.com/T/#m9d7656905be500a97ee6f86b030e94c91a79507a

RE: [PATCH] Documentation: add platform support policy

[rsbecker]

On Thursday, July 11, 2024 2:20 PM, Emily Shaffer wrote:
>> >> > +* You should run nightly tests against the `next` branch and
>> >> > +publish breakage reports to the mailing list immediately when they happen.
>> >> > +* 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.
>> >>
>> >> All of the above are actually applicable to any active contributors
>> >> on any platforms.  If your group feeds custom builds of Git out of
>> >> "master" to your $CORP customers, you want to ensure you catch
>> >> badness while it is still in "next" (or better yet, before it hits "next").
>> >> If your internal builds are based on "next", you'd want to ensure
>> >> that "next" stays clean, which means you'd need to watch "seen" (or
>> >> better yet, patches floating on the list before they hit "seen").
>> >> Your group may build with unusual toolchain internal to your $CORP
>> >> and may link with specialized libraries, etc., in which case
>> >> maintaining such a build is almost like maintaining an exotic platform.
>> >
>> >Hits close to home ;)
>>
>> I hear that. Sometimes having an exotic platform and specialized libraries are
>overlapping. I am still stuck with 32-bit git because some of the available DLLs on
>NonStop are still only 32-bit - I'm working hard on changing that but it's not under
>my budget control.
>>
>> On that subject, I think it is important to have known or designated platform
>maintainers for the exotics. The downside is that some people expect miracles from
>us - I just had one request to permanently preserve timestamps of files as they
>were at commit time. We're into weeks of explanations on why this is a bad idea.
>Nonetheless, there is a certain amount of responsibility that comes with
>maintaining a platform, and knowing whom to ask when there are issues. The
>platform maintainers also can provide needed (preemptive) feedback on
>dependency changes. I'm not sure how to encode that in a compatible policy,
>however.
>
>I think it's a pretty good idea to have a contact list written down somewhere, yeah.
>Maybe something similarly-formatted to a MAINTAINERS file. I don't feel bad if it's
>just appended to the bottom of this doc til we find a better place to put it... or
>maybe we can put such a contact list in compat/, since someone lost trying to figure
>out a compatibility thing might be looking there anyway?
>
>Who else would we put on there? I can think of you for NonStop from the top of
>my head; that AIX breakage I dug up was reported by AEvar, but it's also a few years
>old; and I could imagine putting Johannes down for Windows. Maybe that's enough
>to start with.
>
>By the way, Randall, should I be waiting for a more complete review of this patch
>from you before I reroll?

Please reroll.
--Randall

Re: [PATCH] Documentation: add platform support policy

[Junio C Hamano]

Emily Shaffer <nasamuffin@google.com> writes:

> ...but this seems harder to keep track of. Where are we remembering
> these "due dates" and remembering to break them on purpose? I'm not
> sure that there's a good way to enforce this.

If you come up with a good way, let me know.  We have a few "test
balloons" in the code base and a due date that allows us to say "now
it is 18 months since this test balloon was raised, and nobody
complained, so we can safely assume that all compilers that matter
to users of this project support this language construct just fine"
would be a wonderful thing to have.

Re: [PATCH] Documentation: add platform support policy

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Emily Shaffer <nasamuffin@google.com> writes:
>
>> ...but this seems harder to keep track of. Where are we remembering
>> these "due dates" and remembering to break them on purpose? I'm not
>> sure that there's a good way to enforce this.
>
> If you come up with a good way, let me know.  We have a few "test
> balloons" in the code base and a due date that allows us to say "now
> it is 18 months since this test balloon was raised, and nobody
> complained, so we can safely assume that all compilers that matter
> to users of this project support this language construct just fine"
> would be a wonderful thing to have.

Or, just set up a calendar reminder or an entry in an issue tracker
that are accessible publicly, only to ease the "keeping track of"
part?

As an open source public project, we would not want to depend too
heavily on a single vendor's offering for anything that is essential
to run the project, but as long as we make sure that:

 - the authoritative due date is in the commit log message that
   introduces something, e.g., "we add this limitation, which we
   will revisit and reconsider in 6 months", but

 - if any hosting, cloud, or any other service providers, be they
   commercial or run by volunteers, offer a way for us to make it
   easier to keep track of that authoritative due date established
   above, without additional strings attached, we may freely take
   it (in other words, we are not free-software-socialists against
   commercial services).

then the "reminder" part would not be something essential to run the
project, so ...

Re: [PATCH] Documentation: add platform support policy

[Kyle Lippincott]

On Thu, Jul 11, 2024 at 11:15 AM Emily Shaffer <nasamuffin@google.com> wrote:
>
> On Tue, Jul 9, 2024 at 4:16 PM brian m. carlson
> <sandals@crustytoothpaste.net> wrote:
> >
> > On 2024-07-09 at 22:50:42, Emily Shaffer wrote:
> > > Right now, this doc talks about "guarantees." I used that phrasing based on
> > > what I've observed to be an implicit expectation that we guarantee support; it
> > > could be this isn't actually a guarantee that the community is willing to make,
> > > so I am hoping we can discuss it and come up with the right term.
> >
> > I think it might be helpful to look at what some other projects do. Rust
> > has a concept of tiered support, and it requires platforms to have
> > maintainers who will commit to support an OS.  I don't think we
> > necessarily need to be so formal, but if nobody's stepping up to monitor
> > an OS or architecture, it may break at any time and we won't be able to
> > consider it when deciding on features we require from the platform (such
> > as Rust, C versions, or POSIX versions).
>
> It took me a little time to find it, so here's the link for others:
> https://doc.rust-lang.org/nightly/rustc/platform-support.html
>
> I do think it's interesting that while Rust splits their tiers based
> on how much of it will definitely work (definitely builds+tests,
> definitely builds, probably builds maybe), which is different from how
> I sliced it by time (works on release, works on stable, works on
> unstable). This kind of lines up with what you mentioned next about
> the tests (or some subset) working, which I hadn't considered, either.
>
> >
> > I think it's also worth discussing what we require from a platform we're
> > willing to support.  For example, we might require that the platform
> > pass the entire testsuite (ignoring irrelevant tests or tests for things
> > that platform doesn't use, such as Perl) or be actively pursuing an
> > attempt to do so.  We may also want to require that an OS be actively
> > receiving security support so that we don't have people asking us to
> > carry patches for actively obsolete OSes, such as CentOS 6.  Finally,
> > some sort of time limit may be helpful, since some Linux vendors are now
> > offering 15 years of support, and we really may not want to target
> > really ancient versions of things like libcurl.
>
> I sort of wonder how much of this is taken care of by expressing
> "fully supported" as "can run in GitHub Actions". Even if an LTS
> distro is 12 years old and using ancient curl, will GitHub still be
> able to run it in a VM/container? Maybe there's no such guarantee,
> since you can hook up self-hosted runners (which sounds more appealing
> if someone's got something weird enough it doesn't run well in a
> container).
>
> I'm not sure which of these requirements we'd want to enumerate - but
> does it make sense to tack it onto the end of this doc? Something
> like:
>
> """
> Minimum Requirements
> ------
>
> Even if tests or CI runners are added to guarantee support, supported
> platforms must:
>
> * Be compatible with C99
> * Use curl vX.Y.Z or later
> * Use zlib vA.B.C or later
> ...
> """

My concern with actually listing what the minimum requirements are is
that we then need a process for raising the minimum requirements. For
C specification, I can see that rightfully being an involved
conversation and achieving consensus that this is the right time to do
it. For things like library versions, I'm less comfortable with it
because if we have to raise the minimum bar for some urgent reason,
there's the potential for additional friction with these platforms
claiming that we stated we'd support them (ex: we say you need to be
able to use libfoo v3.x.x (v4.x.x had some breaking changes, but
coexists with v3, so we just stuck with v3), and some security fix
that we need to receive only exists on the v4 version, so now we need
to port to using v4 so that we get the security fix).

I think it's probably fine to list minimum requirements, as long as we
have something conveying "and possibly other criteria". I don't want
this interpreted as a "do this, and we will try hard to not break
you", it should be interpreted as "if you can't do at least this, we
won't even look at patches/tests/CI to unbreak you/keep you unbroken"

>
> >
> > At the same time, we do have people actively building Git on a variety
> > of platforms and a huge number of architectures, including most Linux
> > distros and the BSDs, and we will want to be cognizant that we should
> > avoid breaking those environments when possible, even though, say, the
> > porters for some of those OSes or architectures may not actively follow
> > the list (due to limited porters and lots of porting work).  I imagine
> > we might say that released architectures on certain distros (Debian
> > comes to mind as a very portable option) might be implicitly supported.
>
> Are they implicitly supported, or are they explicitly supported via
> the GH runners? Or indirectly supported? For example, the Actions
> suite tests on Ubuntu; at least once upon a time Ubuntu was derived
> from Debian (is it still? I don't play with distros much anymore); so
> would that mean that running tests in Ubuntu also implies they will
> pass in Debian?
>
> (By the way, I think we should probably just add a BSD test runner to
> Actions config; we test on MacOS but that's not that closely related.
> It seems like it might be a pretty easy lift to do that.)
>
> >
> > > +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.
> >
> > I think this is a particularly helpful approach.  I understand the Linux
> > runners support nested virtualization, so it's possible to run tests in
> > a VM on a Linux runner on OSes that Actions doesn't natively support.  I
> > do this for several of my Rust projects[0] on FreeBSD and NetBSD, for
> > example, and it should work on platforms that support Vagrant and run on
> > x86-64.
> >
> > That won't catch things like alignment problems which don't affect
> > x86-64, but it does catch a lot of general portability problems that are
> > OS-related.
> >
> > I'm in agreement with all of your suggestions, by the way, and I
> > appreciate you opening this discussion.
> >
> > [0] An example for the curious is muter: https://github.com/bk2204/muter.
>
> Neat :)
>
> > --
> > brian m. carlson (they/them or he/him)
> > Toronto, Ontario, CA
>

RE: [PATCH] Documentation: add platform support policy

[rsbecker]

On Thursday, July 11, 2024 4:13 PM, Kyle Lippincott wrote:
>On Thu, Jul 11, 2024 at 11:15 AM Emily Shaffer <nasamuffin@google.com> wrote:
>>
>> On Tue, Jul 9, 2024 at 4:16 PM brian m. carlson
>> <sandals@crustytoothpaste.net> wrote:
>> >
>> > On 2024-07-09 at 22:50:42, Emily Shaffer wrote:
>> > > Right now, this doc talks about "guarantees." I used that phrasing
>> > > based on what I've observed to be an implicit expectation that we
>> > > guarantee support; it could be this isn't actually a guarantee
>> > > that the community is willing to make, so I am hoping we can discuss it and
>come up with the right term.
>> >
>> > I think it might be helpful to look at what some other projects do.
>> > Rust has a concept of tiered support, and it requires platforms to
>> > have maintainers who will commit to support an OS.  I don't think we
>> > necessarily need to be so formal, but if nobody's stepping up to
>> > monitor an OS or architecture, it may break at any time and we won't
>> > be able to consider it when deciding on features we require from the
>> > platform (such as Rust, C versions, or POSIX versions).
>>
>> It took me a little time to find it, so here's the link for others:
>> https://doc.rust-lang.org/nightly/rustc/platform-support.html
>>
>> I do think it's interesting that while Rust splits their tiers based
>> on how much of it will definitely work (definitely builds+tests,
>> definitely builds, probably builds maybe), which is different from how
>> I sliced it by time (works on release, works on stable, works on
>> unstable). This kind of lines up with what you mentioned next about
>> the tests (or some subset) working, which I hadn't considered, either.
>>
>> >
>> > I think it's also worth discussing what we require from a platform
>> > we're willing to support.  For example, we might require that the
>> > platform pass the entire testsuite (ignoring irrelevant tests or
>> > tests for things that platform doesn't use, such as Perl) or be
>> > actively pursuing an attempt to do so.  We may also want to require
>> > that an OS be actively receiving security support so that we don't
>> > have people asking us to carry patches for actively obsolete OSes,
>> > such as CentOS 6.  Finally, some sort of time limit may be helpful,
>> > since some Linux vendors are now offering 15 years of support, and
>> > we really may not want to target really ancient versions of things like libcurl.
>>
>> I sort of wonder how much of this is taken care of by expressing
>> "fully supported" as "can run in GitHub Actions". Even if an LTS
>> distro is 12 years old and using ancient curl, will GitHub still be
>> able to run it in a VM/container? Maybe there's no such guarantee,
>> since you can hook up self-hosted runners (which sounds more appealing
>> if someone's got something weird enough it doesn't run well in a
>> container).
>>
>> I'm not sure which of these requirements we'd want to enumerate - but
>> does it make sense to tack it onto the end of this doc? Something
>> like:
>>
>> """
>> Minimum Requirements
>> ------
>>
>> Even if tests or CI runners are added to guarantee support, supported
>> platforms must:
>>
>> * Be compatible with C99
>> * Use curl vX.Y.Z or later
>> * Use zlib vA.B.C or later
>> ...
>> """
>
>My concern with actually listing what the minimum requirements are is that we
>then need a process for raising the minimum requirements. For C specification, I can
>see that rightfully being an involved conversation and achieving consensus that this
>is the right time to do it. For things like library versions, I'm less comfortable with it
>because if we have to raise the minimum bar for some urgent reason, there's the
>potential for additional friction with these platforms claiming that we stated we'd
>support them (ex: we say you need to be able to use libfoo v3.x.x (v4.x.x had some
>breaking changes, but coexists with v3, so we just stuck with v3), and some security
>fix that we need to receive only exists on the v4 version, so now we need to port to
>using v4 so that we get the security fix).
>
>I think it's probably fine to list minimum requirements, as long as we have
>something conveying "and possibly other criteria". I don't want this interpreted as a
>"do this, and we will try hard to not break you", it should be interpreted as "if you
>can't do at least this, we won't even look at patches/tests/CI to unbreak you/keep
>you unbroken"

I have similar concerns both in terms of compilers and libraries. I am maintaining two exotic platforms, NonStop x86 and ia64. The ia64 is going off support "soon". In x86, we have more recent tooling, but not everything. It is at an older POSIX level. However, getting libraries built is either going hat in hand to HPE asking for updates on libraries or porting them myself. This is hard because gcc is not available, nor is likely to ever be - so anything with gcc in the mandatory toolchain is out of the question. For ia64, it doesn't matter much, and freezing on 2.49, or slightly later than 2.50 is not a horrible decision. I do have to keep x86 alive for the foreseeable future. My only real time limit is getting a 64-bit time_t (not available yet) in a 64-bit git build (also not possible yet) - which really depends on 64-bit versions of dependencies from the vendor, which is not easy to make happen. So, time limits are a definite concern and policies on those are important to quantify. Fortunately, I am monitoring and building git frequently looking for trouble. I think that part is important for any exotic maintainer and probably should be officially quantified/sanctioned.

>
>>
>> >
>> > At the same time, we do have people actively building Git on a
>> > variety of platforms and a huge number of architectures, including
>> > most Linux distros and the BSDs, and we will want to be cognizant
>> > that we should avoid breaking those environments when possible, even
>> > though, say, the porters for some of those OSes or architectures may
>> > not actively follow the list (due to limited porters and lots of
>> > porting work).  I imagine we might say that released architectures
>> > on certain distros (Debian comes to mind as a very portable option) might be
>implicitly supported.
>>
>> Are they implicitly supported, or are they explicitly supported via
>> the GH runners? Or indirectly supported? For example, the Actions
>> suite tests on Ubuntu; at least once upon a time Ubuntu was derived
>> from Debian (is it still? I don't play with distros much anymore); so
>> would that mean that running tests in Ubuntu also implies they will
>> pass in Debian?
>>
>> (By the way, I think we should probably just add a BSD test runner to
>> Actions config; we test on MacOS but that's not that closely related.
>> It seems like it might be a pretty easy lift to do that.)
>>
>> >
>> > > +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.
>> >
>> > I think this is a particularly helpful approach.  I understand the
>> > Linux runners support nested virtualization, so it's possible to run
>> > tests in a VM on a Linux runner on OSes that Actions doesn't
>> > natively support.  I do this for several of my Rust projects[0] on
>> > FreeBSD and NetBSD, for example, and it should work on platforms
>> > that support Vagrant and run on x86-64.
>> >
>> > That won't catch things like alignment problems which don't affect
>> > x86-64, but it does catch a lot of general portability problems that
>> > are OS-related.
>> >
>> > I'm in agreement with all of your suggestions, by the way, and I
>> > appreciate you opening this discussion.
>> >
>> > [0] An example for the curious is muter: https://github.com/bk2204/muter.
>>
>> Neat :)
>>
>> > --
>> > brian m. carlson (they/them or he/him) Toronto, Ontario, CA
>>

Re: [PATCH] Documentation: add platform support policy

[Kyle Lippincott]

On Thu, Jul 11, 2024 at 11:37 AM Emily Shaffer <nasamuffin@google.com> wrote:
>
> On Wed, Jul 10, 2024 at 12:11 PM Kyle Lippincott <spectral@google.com> wrote:
> >
> > On Tue, Jul 9, 2024 at 3:50 PM Emily Shaffer <emilyshaffer@google.com> wrote:
> > > +* 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.
> >
> > Should we state that we reserve the right to reject these tests if
> > they would put what we feel is an excessive burden on the git
> > developers? i.e. a requirement to use C89 would be rejected
> > (obviously). a requirement to support 16-bit platforms would also be
> > rejected. I don't know that we need to list examples for what we'd
> > reject, they could be implied that we're likely to accept anything
> > else.
>
> brian mentioned something similar in their review, to which I proposed
> a minimum requirements field[1]; I think this would work for that too?
> Thoughts?
>
> > > +** 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.
> >
> > I think that we likely won't have the ability to investigate whether
> > it's _truly_ gone away ourselves, and there's no guarantee that the
> > person that added these tests will be able to vet it either (maybe
> > they've switched jobs, for example).
> >
> > I think we should take a stance that may be considered hostile, but I
> > can't really think of a better one:
> > - there needs to be a regular (6 month? 12 month? no longer than 12
> > month surely...) reaffirmation by the interested party that this is
> > still a requirement for them. This comes in the form of updating a
> > date in the codebase, not just a message on the list. If this
> > reaffirmation does not happen, we are allowed to assume that this is
> > not needed anymore and remove the test that's binding us to supporting
> > that.
>
> I like the idea of the date in code, because that's "polled" rather
> than "pushed" - when I break the test, I can go look at it, and see a
> condition like "Until July 1st, 2024" and say "well it's July 11th, so
> I don't care, deleted!" - or, more likely, I can see that date expired
> a year and a half ago :)
>
> > We should probably go a step further and intentionally violate
> > the test condition, so that any builds done by the interested parties
> > break immediately (which should be caught by the other processes
> > documented here; if they don't break, then it was correct to remove
> > the restriction).
>
> ...but this seems harder to keep track of. Where are we remembering
> these "due dates" and remembering to break them on purpose? I'm not
> sure that there's a good way to enforce this.

Ah, I was unclear - I was saying when we remove the test, we should
intentionally add a use of the thing the test was preventing us from
using. So if there's a test saying "you can't use printf()", when
removing that test, we should add a use of printf in the same series.
I was intentionally being vague about "when" we should remove these
tests, and how long we should consider the newly added printf
provisional (and possibly going to be rolled back), like in our
current test balloons. Just: if you're removing an expired
platform-support-policy test, add something to the codebase (possibly
just another test) that exercises the previously forbidden aspect, if
possible.

This is likely to happen organically: most people aren't going to
notice an expired platform-support-policy test and remove it just
because. They'll trip over it while attempting to work on a feature,
notice it's expired, and remove it as part of the series that makes
use of it. But if someone is trying to be helpful and clean up expired
platform-support-policy tests without having the goal of immediately
using it, they should be encouraged to invert the test so that we
don't have potentially months of time difference between "implicitly
allowed again [since there's no test preventing its use]" and the
actual usage being added.

>
> > - _most_ of these restrictions should probably have a limited number
> > of reaffirmations? I feel like this needs to be handled on a
> > case-by-case basis, but I want us to be clear that just because we
> > accepted these restrictions in the past doesn't mean we will accept
> > them indefinitely.
> > - Just because there's a reaffirmation doesn't mean we're guaranteeing
> > we won't delete the test before the affirmation "expires". If there's
> > an urgent security need to do something, and it can't be done without
> > breaking this, we'll choose to break this test. If there's general
> > consensus to do something (adopt a new language standard version, for
> > example), there's no guarantee we'll wait until all the existing
> > affirmations expire.
>
> I honestly like this point more than the previous one. Limiting by a
> number, even one that changes, feels less flexible than allowing
> ourselves to say "enough of this nonsense, it's the Century of the
> Fruitbat, we really want to use <C11 feature> so you can get
> maintenance updates instead now".

Yeah, that's fair. Let's withdraw my suggestion of a limited number of
reaffirmations. :) That works well if the goal is to have a temporary
restriction while work is actively happening to remove its necessity,
but that's less likely to be the case here. If we can't move to C42
because it's not supported on Linux Distro 2050™ yet, users of Linux
Distro 2050™ aren't able to promise eventual support of C42 or
accelerate that happening.

>
> >
> > The thinking here is that this test is imposing a restriction on the
> > git developers that we've agreed to take on as a favor: we are going
> > to restrict ourselves from doing X _for the time being_ not
> > necessarily because it'll break you, but because it's a bad experience
> > for the git developers to create a patch series that lands and then
> > gets backed out when the breakage on $non_standard_platform is
> > detected on seen/next/master.
>
> 1: https://lore.kernel.org/git/CAO_smVjZ7DSPdL+KYCm2mQ=q55XbEH7Vu_jLxkAa5WTcD9rq8A@mail.gmail.com/T/#m9d7656905be500a97ee6f86b030e94c91a79507a

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Thu, Jul 11, 2024 at 1:12 PM Kyle Lippincott <spectral@google.com> wrote:
>
> On Thu, Jul 11, 2024 at 11:15 AM Emily Shaffer <nasamuffin@google.com> wrote:
> >
> > On Tue, Jul 9, 2024 at 4:16 PM brian m. carlson
> > > I think it's also worth discussing what we require from a platform we're
> > > willing to support.  For example, we might require that the platform
> > > pass the entire testsuite (ignoring irrelevant tests or tests for things
> > > that platform doesn't use, such as Perl) or be actively pursuing an
> > > attempt to do so.  We may also want to require that an OS be actively
> > > receiving security support so that we don't have people asking us to
> > > carry patches for actively obsolete OSes, such as CentOS 6.  Finally,
> > > some sort of time limit may be helpful, since some Linux vendors are now
> > > offering 15 years of support, and we really may not want to target
> > > really ancient versions of things like libcurl.
> >
> > I sort of wonder how much of this is taken care of by expressing
> > "fully supported" as "can run in GitHub Actions". Even if an LTS
> > distro is 12 years old and using ancient curl, will GitHub still be
> > able to run it in a VM/container? Maybe there's no such guarantee,
> > since you can hook up self-hosted runners (which sounds more appealing
> > if someone's got something weird enough it doesn't run well in a
> > container).
> >
> > I'm not sure which of these requirements we'd want to enumerate - but
> > does it make sense to tack it onto the end of this doc? Something
> > like:
> >
> > """
> > Minimum Requirements
> > ------
> >
> > Even if tests or CI runners are added to guarantee support, supported
> > platforms must:
> >
> > * Be compatible with C99
> > * Use curl vX.Y.Z or later
> > * Use zlib vA.B.C or later
> > ...
> > """
>
> My concern with actually listing what the minimum requirements are is
> that we then need a process for raising the minimum requirements. For
> C specification, I can see that rightfully being an involved
> conversation and achieving consensus that this is the right time to do
> it. For things like library versions, I'm less comfortable with it
> because if we have to raise the minimum bar for some urgent reason,
> there's the potential for additional friction with these platforms
> claiming that we stated we'd support them (ex: we say you need to be
> able to use libfoo v3.x.x (v4.x.x had some breaking changes, but
> coexists with v3, so we just stuck with v3), and some security fix
> that we need to receive only exists on the v4 version, so now we need
> to port to using v4 so that we get the security fix).
>
> I think it's probably fine to list minimum requirements, as long as we
> have something conveying "and possibly other criteria". I don't want
> this interpreted as a "do this, and we will try hard to not break
> you", it should be interpreted as "if you can't do at least this, we
> won't even look at patches/tests/CI to unbreak you/keep you unbroken"

Yeah, I agree that I'm somewhat uninterested in enumerating a set of
deps/criteria that will then magically assure it works - that does
sound like a hassle to keep up-to-date, and in fact I think would set
us backwards from the goal of this doc. We'd feel tied to that
criteria without any ability to move forward, which would probably be
our current status quo or worse.

So, I'll make it clear to reflect the second thing you're saying in the reroll.

 - Emily

Re: [PATCH] Documentation: add platform support policy

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 6845 bytes --]

On 2024-07-11 at 18:14:36, Emily Shaffer wrote:
> On Tue, Jul 9, 2024 at 4:16 PM brian m. carlson
> <sandals@crustytoothpaste.net> wrote:
> >
> > I think it's also worth discussing what we require from a platform we're
> > willing to support.  For example, we might require that the platform
> > pass the entire testsuite (ignoring irrelevant tests or tests for things
> > that platform doesn't use, such as Perl) or be actively pursuing an
> > attempt to do so.  We may also want to require that an OS be actively
> > receiving security support so that we don't have people asking us to
> > carry patches for actively obsolete OSes, such as CentOS 6.  Finally,
> > some sort of time limit may be helpful, since some Linux vendors are now
> > offering 15 years of support, and we really may not want to target
> > really ancient versions of things like libcurl.
> 
> I sort of wonder how much of this is taken care of by expressing
> "fully supported" as "can run in GitHub Actions". Even if an LTS
> distro is 12 years old and using ancient curl, will GitHub still be
> able to run it in a VM/container? Maybe there's no such guarantee,
> since you can hook up self-hosted runners (which sounds more appealing
> if someone's got something weird enough it doesn't run well in a
> container).

Some older OSes require kernel features that aren't compiled in by
default, so containers are out.  For example, CentOS 6 won't run on a
modern kernel because it lacks whatever the predecessor to the vDSO was
(which can be recompiled into the kernel, but nobody does that).

We also don't really want to be on the hook for trying to support OSes
that get no security support.  We don't want to be running an OS
connected to the Internet that has known root security holes, even in a
CI environment, so I think _someone_ should be providing security
support for it to their customers or the public free of charge.

I also want to let us use new features from time to time that may not be
able to be conditionally compiled in (such as new Perl features), so I
think maybe setting a hard limit on a supported age of software might be
a good idea.  If we want to have good support for LTS Linux distros, we
could set it at 10 years initially.

Also, if we do decide to adopt Rust in the future, we'll need to
consider a different lifetime policy for that.  I try to support an old
Debian release for a year after the new one comes out, which is about
three years for a compiler version, but anything older that that becomes
a real bear to support because most dependencies won't support older
versions.  Since we're not using Rust now, we don't have to consider
that at the moment, but it's a thing to think about when we're
discussing policy since different language communities have different
expectations.  We might find that we need different policies for, say,
Perl than we do for C.

> """
> Minimum Requirements
> ------
> 
> Even if tests or CI runners are added to guarantee support, supported
> platforms must:
> 
> * Be compatible with C99
> * Use curl vX.Y.Z or later
> * Use zlib vA.B.C or later
> ...
> """

I think to start off, we could say that it has to have C99 or C11, that
dependencies must have been released upstream in the past 10 years, and
that the platform and dependencies must have security support.

I mention C99 or C11 because Windows _does_ have C11 but not C99; they
are mostly compatible, but not entirely.  FreeBSD also _requires_ C11
for its header files and won't compile with C99.  I think the difference
is small enough that we can paper over it ourselves with little
difficulty, though.

> > At the same time, we do have people actively building Git on a variety
> > of platforms and a huge number of architectures, including most Linux
> > distros and the BSDs, and we will want to be cognizant that we should
> > avoid breaking those environments when possible, even though, say, the
> > porters for some of those OSes or architectures may not actively follow
> > the list (due to limited porters and lots of porting work).  I imagine
> > we might say that released architectures on certain distros (Debian
> > comes to mind as a very portable option) might be implicitly supported.
> 
> Are they implicitly supported, or are they explicitly supported via
> the GH runners? Or indirectly supported? For example, the Actions
> suite tests on Ubuntu; at least once upon a time Ubuntu was derived
> from Debian (is it still? I don't play with distros much anymore); so
> would that mean that running tests in Ubuntu also implies they will
> pass in Debian?

Ubuntu is still derived from Debian.  It is likely that things which
work in one will work in another, but not guaranteed.

I mention Debian is because it has a large variety of supported
architectures.  I absolutely don't want to say, "Oh, you have MIPS
hardware, too bad if Git doesn't work for you."  (I assure you the
distro maintainers will be displeased if we break Git on less common
architectures, as will I.)  In fact, MIPS is an architecture that
requires natural alignment and can be big-endian, so it's very useful in
helping us find places we wrote invalid or unportable C.

The reason I'm very hesitant to require that we run everything in GitHub
Actions because it only supports two architectures.  ARM64 and RISC-V
are really popular, and I can tell you that running even a Linux
container in emulation is really quite slow.  I do it for my projects,
but Git LFS only builds one set of non-x86 packages (the latest Debian)
because emulation is far too slow to build the normal suite of five or
six packages.

And it's actually much easier to run Linux binaries in emulation in a
container because QEMU supports that natively.  Most other OSes must run
a full OS in emulation, which is slower.  There also aren't usually
pre-made images for that; I tend to use Vagrant, which has pre-built
images for x86-64, but I don't really want to be bootstrapping OS images
other architectures in CI.

So I'd say that we might want to consider supporting all release
architectures on specific OSes.  I think Debian is one of the more
portable Linux distros (more portable than Ubuntu).  Debian has also
abandoned some architectures that you can't buy anymore, like Itanium,
so that might be a reasonable limit on how far we're willing to go.

> (By the way, I think we should probably just add a BSD test runner to
> Actions config; we test on MacOS but that's not that closely related.
> It seems like it might be a pretty easy lift to do that.)

FreeBSD and NetBSD are pretty easy.  I won't 100% commit to it, but if I
find time I'll try to send a patch.
-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Thu, Jul 11, 2024 at 3:24 PM brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> On 2024-07-11 at 18:14:36, Emily Shaffer wrote:
> > On Tue, Jul 9, 2024 at 4:16 PM brian m. carlson
> > <sandals@crustytoothpaste.net> wrote:
> > >
> > > I think it's also worth discussing what we require from a platform we're
> > > willing to support.  For example, we might require that the platform
> > > pass the entire testsuite (ignoring irrelevant tests or tests for things
> > > that platform doesn't use, such as Perl) or be actively pursuing an
> > > attempt to do so.  We may also want to require that an OS be actively
> > > receiving security support so that we don't have people asking us to
> > > carry patches for actively obsolete OSes, such as CentOS 6.  Finally,
> > > some sort of time limit may be helpful, since some Linux vendors are now
> > > offering 15 years of support, and we really may not want to target
> > > really ancient versions of things like libcurl.
> >
> > I sort of wonder how much of this is taken care of by expressing
> > "fully supported" as "can run in GitHub Actions". Even if an LTS
> > distro is 12 years old and using ancient curl, will GitHub still be
> > able to run it in a VM/container? Maybe there's no such guarantee,
> > since you can hook up self-hosted runners (which sounds more appealing
> > if someone's got something weird enough it doesn't run well in a
> > container).
>
> Some older OSes require kernel features that aren't compiled in by
> default, so containers are out.  For example, CentOS 6 won't run on a
> modern kernel because it lacks whatever the predecessor to the vDSO was
> (which can be recompiled into the kernel, but nobody does that).

Is this hinting that we should mention a minimum kernel version for
Linux-kernel-based OSes?

>
> We also don't really want to be on the hook for trying to support OSes
> that get no security support.  We don't want to be running an OS
> connected to the Internet that has known root security holes, even in a
> CI environment, so I think _someone_ should be providing security
> support for it to their customers or the public free of charge.

Agreed - I added this to the minimum requirement section like you suggest.

>
> I also want to let us use new features from time to time that may not be
> able to be conditionally compiled in (such as new Perl features), so I
> think maybe setting a hard limit on a supported age of software might be
> a good idea.  If we want to have good support for LTS Linux distros, we
> could set it at 10 years initially.

Sure, I added this to the minimum requirements for now.

>
> Also, if we do decide to adopt Rust in the future, we'll need to
> consider a different lifetime policy for that.  I try to support an old
> Debian release for a year after the new one comes out, which is about
> three years for a compiler version, but anything older that that becomes
> a real bear to support because most dependencies won't support older
> versions.  Since we're not using Rust now, we don't have to consider
> that at the moment, but it's a thing to think about when we're
> discussing policy since different language communities have different
> expectations.  We might find that we need different policies for, say,
> Perl than we do for C.

Yes, definitely, the Rust bits will be a whole different conversation.
I do think it's gated behind this - is it ok for us to even add Rust,
given our current support story? - so I'm happy to punt on it for now,
frankly.

>
> > """
> > Minimum Requirements
> > ------
> >
> > Even if tests or CI runners are added to guarantee support, supported
> > platforms must:
> >
> > * Be compatible with C99
> > * Use curl vX.Y.Z or later
> > * Use zlib vA.B.C or later
> > ...
> > """
>
> I think to start off, we could say that it has to have C99 or C11, that
> dependencies must have been released upstream in the past 10 years, and
> that the platform and dependencies must have security support.
>
> I mention C99 or C11 because Windows _does_ have C11 but not C99; they
> are mostly compatible, but not entirely.  FreeBSD also _requires_ C11
> for its header files and won't compile with C99.  I think the difference
> is small enough that we can paper over it ourselves with little
> difficulty, though.

Added both for reroll. Thanks for the thoughtful suggestions :)

>
> > > At the same time, we do have people actively building Git on a variety
> > > of platforms and a huge number of architectures, including most Linux
> > > distros and the BSDs, and we will want to be cognizant that we should
> > > avoid breaking those environments when possible, even though, say, the
> > > porters for some of those OSes or architectures may not actively follow
> > > the list (due to limited porters and lots of porting work).  I imagine
> > > we might say that released architectures on certain distros (Debian
> > > comes to mind as a very portable option) might be implicitly supported.
> >
> > Are they implicitly supported, or are they explicitly supported via
> > the GH runners? Or indirectly supported? For example, the Actions
> > suite tests on Ubuntu; at least once upon a time Ubuntu was derived
> > from Debian (is it still? I don't play with distros much anymore); so
> > would that mean that running tests in Ubuntu also implies they will
> > pass in Debian?
>
> Ubuntu is still derived from Debian.  It is likely that things which
> work in one will work in another, but not guaranteed.
>
> I mention Debian is because it has a large variety of supported
> architectures.  I absolutely don't want to say, "Oh, you have MIPS
> hardware, too bad if Git doesn't work for you."  (I assure you the
> distro maintainers will be displeased if we break Git on less common
> architectures, as will I.)  In fact, MIPS is an architecture that
> requires natural alignment and can be big-endian, so it's very useful in
> helping us find places we wrote invalid or unportable C.
>
> The reason I'm very hesitant to require that we run everything in GitHub
> Actions because it only supports two architectures.  ARM64 and RISC-V
> are really popular, and I can tell you that running even a Linux
> container in emulation is really quite slow.  I do it for my projects,
> but Git LFS only builds one set of non-x86 packages (the latest Debian)
> because emulation is far too slow to build the normal suite of five or
> six packages.

Does that restriction apply to just GitHub-hosted runners, though?
Would it be possible for an interested party to set up self-hosted
runners (configured via GH Actions) that are using AMD or POWER or
whatever? (For example, I think it would be quite feasible for Google
to donate some compute for this, though no promises).

The appeal is not "because GitHub Actions are great!" for me - the
appeal is "because most Git developers run the CI this way if they
remember to or use GGG, and Junio runs it on `seen` all the time". If
there's some other recommendation for self-service CI runs that don't
need some careful reminding or secret knowledge to run, I'm happy with
that too. (For example, if someone wants to set up some bot that looks
for new [PATCH]-shaped emails, applies, builds, runs tests, and mails
test results to the author after run, that would fit into the spirit
of this point, although that sounds like a lot of setup to me.)

>
> And it's actually much easier to run Linux binaries in emulation in a
> container because QEMU supports that natively.  Most other OSes must run
> a full OS in emulation, which is slower.  There also aren't usually
> pre-made images for that; I tend to use Vagrant, which has pre-built
> images for x86-64, but I don't really want to be bootstrapping OS images
> other architectures in CI.
>
> So I'd say that we might want to consider supporting all release
> architectures on specific OSes.  I think Debian is one of the more
> portable Linux distros (more portable than Ubuntu).  Debian has also
> abandoned some architectures that you can't buy anymore, like Itanium,
> so that might be a reasonable limit on how far we're willing to go.

Sounds neat - I wonder if this is something I should start asking
around about within Google and find out if we can contribute. It might
be feasible.

Based on this mail, I'll try to reword the bit about "add a GitHub
runner" to make it a little less GitHub-prescriptive.

Should have a reroll in the next 30min, it was ready to go and then I
got this mail :)

Thanks!
 - Emily

[PATCH v2] Documentation: add platform support policy

[Emily Shaffer]

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

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>

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>
-- 
2.45.2.993.g49e7a77208-goog

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

[Junio C Hamano]

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

Re: [PATCH] Documentation: add platform support policy

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 5437 bytes --]

On 2024-07-11 at 23:15:35, Emily Shaffer wrote:
> On Thu, Jul 11, 2024 at 3:24 PM brian m. carlson
> <sandals@crustytoothpaste.net> wrote:
> > Some older OSes require kernel features that aren't compiled in by
> > default, so containers are out.  For example, CentOS 6 won't run on a
> > modern kernel because it lacks whatever the predecessor to the vDSO was
> > (which can be recompiled into the kernel, but nobody does that).
> 
> Is this hinting that we should mention a minimum kernel version for
> Linux-kernel-based OSes?

This is actually a feature that still exists in the kernel and could be
enabled for newer kernels, but because distros don't use it (they use
the vDSO instead), they don't compile it in.

I'm not sure a minimum kernel version is helpful, because most of the
LTS distro kernels backport features, like Red Hat backported getrandom
for example.  In the interests of getting to a useful agreement, I think
for now we should just punt on this and having a 10 year lifespan will
probably do the trick, and we can determine in the future if we need to
apply more stringent measures.

> > We also don't really want to be on the hook for trying to support OSes
> > Ubuntu is still derived from Debian.  It is likely that things which
> > work in one will work in another, but not guaranteed.
> >
> > I mention Debian is because it has a large variety of supported
> > architectures.  I absolutely don't want to say, "Oh, you have MIPS
> > hardware, too bad if Git doesn't work for you."  (I assure you the
> > distro maintainers will be displeased if we break Git on less common
> > architectures, as will I.)  In fact, MIPS is an architecture that
> > requires natural alignment and can be big-endian, so it's very useful in
> > helping us find places we wrote invalid or unportable C.
> >
> > The reason I'm very hesitant to require that we run everything in GitHub
> > Actions because it only supports two architectures.  ARM64 and RISC-V
> > are really popular, and I can tell you that running even a Linux
> > container in emulation is really quite slow.  I do it for my projects,
> > but Git LFS only builds one set of non-x86 packages (the latest Debian)
> > because emulation is far too slow to build the normal suite of five or
> > six packages.
> 
> Does that restriction apply to just GitHub-hosted runners, though?
> Would it be possible for an interested party to set up self-hosted
> runners (configured via GH Actions) that are using AMD or POWER or
> whatever? (For example, I think it would be quite feasible for Google
> to donate some compute for this, though no promises).

Self-hosted runners on public code are very hard to secure.  You're
basically letting arbitrary people on the Internet run code on those
machines and make outgoing network connections (due to the fact that you
can push whatever into a PR branch), with all of the potential for abuse
that that involves (and as my colleagues can tell you, there's a whole
lot of it).  GitHub has taken extensive pains to secure GitHub Actions
runners in the cloud, and while we use self-hosted runners for some
internal projects, they are absolutely not allowed for any public
project for that reason.

I would be delighted if Google were willing to do that, but I think
you're going to need help from teams like Google Cloud who are going to
be used to dealing with abuse at scale, like cryptocurrency miners and
such.  Unfortunately, there are many people who act in a less than
lovely way and will exploit whatever they can to make a buck.

I will also note that the official Actions runner is in C# and only runs
on a handful of platforms due to the lack of portability of C#.  (It
might theoretically run on Mono, which would increase its portability,
but I must profess my complete ignorance on anything about that code.) I
also know of an unofficial one in Go[0], which I'm for obvious reasons
unable to endorse, encourage, or speak about authoritatively in any way,
but that would still exclude some platforms and architectures which
don't support Go.

> The appeal is not "because GitHub Actions are great!" for me - the
> appeal is "because most Git developers run the CI this way if they
> remember to or use GGG, and Junio runs it on `seen` all the time". If
> there's some other recommendation for self-service CI runs that don't
> need some careful reminding or secret knowledge to run, I'm happy with
> that too. (For example, if someone wants to set up some bot that looks
> for new [PATCH]-shaped emails, applies, builds, runs tests, and mails
> test results to the author after run, that would fit into the spirit
> of this point, although that sounds like a lot of setup to me.)

Yeah, I understand what you're going for.  If there were some super easy
way to get everything running in an automatic CI, I'm all for it.  I
think CI is the easiest way to make sure we don't break anything.

I think it's worth trying to get CI set up for whatever we can, and if
CI is a possibility somewhere, it becomes a lot easier to say yes.

> Should have a reroll in the next 30min, it was ready to go and then I
> got this mail :)

Sounds good.  I don't think anything in this email should affect that
reroll.

[0] https://github.com/ChristopherHX/github-act-runner
-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]

RE: [PATCH] Documentation: add platform support policy

[rsbecker]

On Friday, July 12, 2024 3:34 PM, brian m. carlson wrote:
>Subject: Re: [PATCH] Documentation: add platform support policy
>
>On 2024-07-11 at 23:15:35, Emily Shaffer wrote:
>> On Thu, Jul 11, 2024 at 3:24 PM brian m. carlson
>> <sandals@crustytoothpaste.net> wrote:
>> > Some older OSes require kernel features that aren't compiled in by
>> > default, so containers are out.  For example, CentOS 6 won't run on
>> > a modern kernel because it lacks whatever the predecessor to the
>> > vDSO was (which can be recompiled into the kernel, but nobody does that).
>>
>> Is this hinting that we should mention a minimum kernel version for
>> Linux-kernel-based OSes?
>
>This is actually a feature that still exists in the kernel and could be enabled for newer
>kernels, but because distros don't use it (they use the vDSO instead), they don't
>compile it in.
>
>I'm not sure a minimum kernel version is helpful, because most of the LTS distro
>kernels backport features, like Red Hat backported getrandom for example.  In the
>interests of getting to a useful agreement, I think for now we should just punt on
>this and having a 10 year lifespan will probably do the trick, and we can determine
>in the future if we need to apply more stringent measures.

When looking at the "exotics", many have their own kernel lifespans. When worrying about NonStop, for example, the Kernel version stays around about 5 years under full support, then goes another few until retired. I think it is important for people to know the compatible versions of the kernel builds have. I do track those for the platform.

>> > We also don't really want to be on the hook for trying to support
>> > OSes Ubuntu is still derived from Debian.  It is likely that things
>> > which work in one will work in another, but not guaranteed.
>> >
>> > I mention Debian is because it has a large variety of supported
>> > architectures.  I absolutely don't want to say, "Oh, you have MIPS
>> > hardware, too bad if Git doesn't work for you."  (I assure you the
>> > distro maintainers will be displeased if we break Git on less common
>> > architectures, as will I.)  In fact, MIPS is an architecture that
>> > requires natural alignment and can be big-endian, so it's very
>> > useful in helping us find places we wrote invalid or unportable C.
>> >
>> > The reason I'm very hesitant to require that we run everything in
>> > GitHub Actions because it only supports two architectures.  ARM64
>> > and RISC-V are really popular, and I can tell you that running even
>> > a Linux container in emulation is really quite slow.  I do it for my
>> > projects, but Git LFS only builds one set of non-x86 packages (the
>> > latest Debian) because emulation is far too slow to build the normal
>> > suite of five or six packages.
>>
>> Does that restriction apply to just GitHub-hosted runners, though?
>> Would it be possible for an interested party to set up self-hosted
>> runners (configured via GH Actions) that are using AMD or POWER or
>> whatever? (For example, I think it would be quite feasible for Google
>> to donate some compute for this, though no promises).
>
>Self-hosted runners on public code are very hard to secure.  You're basically letting
>arbitrary people on the Internet run code on those machines and make outgoing
>network connections (due to the fact that you can push whatever into a PR
>branch), with all of the potential for abuse that that involves (and as my colleagues
>can tell you, there's a whole lot of it).  GitHub has taken extensive pains to secure
>GitHub Actions runners in the cloud, and while we use self-hosted runners for some
>internal projects, they are absolutely not allowed for any public project for that
>reason.

I'm not sure this applies to some of the exotics. NonStop cannot run the Google CI code. While we could, in theory, connect to via SSH to run builds, my system is behind a VPN/Firewall, which would make the builds impossible. I do build using Jenkins based on an SCM poll. It's not perfect and some tests do not run correctly in Jenkins but do outside. I would like to provide the feedback to the git team, somehow, on what built successfully or not, outside of the mailing list.

>I would be delighted if Google were willing to do that, but I think you're going to
>need help from teams like Google Cloud who are going to be used to dealing with
>abuse at scale, like cryptocurrency miners and such.  Unfortunately, there are many
>people who act in a less than lovely way and will exploit whatever they can to make
>a buck.
>
>I will also note that the official Actions runner is in C# and only runs on a handful of
>platforms due to the lack of portability of C#.  (It might theoretically run on Mono,
>which would increase its portability, but I must profess my complete ignorance on
>anything about that code.) I also know of an unofficial one in Go[0], which I'm for
>obvious reasons unable to endorse, encourage, or speak about authoritatively in
>any way, but that would still exclude some platforms and architectures which don't
>support Go.

We don't have C# or Go, nor are likely to any time soon, so that is a problem. 

>
>> The appeal is not "because GitHub Actions are great!" for me - the
>> appeal is "because most Git developers run the CI this way if they
>> remember to or use GGG, and Junio runs it on `seen` all the time". If
>> there's some other recommendation for self-service CI runs that don't
>> need some careful reminding or secret knowledge to run, I'm happy with
>> that too. (For example, if someone wants to set up some bot that looks
>> for new [PATCH]-shaped emails, applies, builds, runs tests, and mails
>> test results to the author after run, that would fit into the spirit
>> of this point, although that sounds like a lot of setup to me.)
>
>Yeah, I understand what you're going for.  If there were some super easy way to get
>everything running in an automatic CI, I'm all for it.  I think CI is the easiest way to
>make sure we don't break anything.
>
>I think it's worth trying to get CI set up for whatever we can, and if CI is a possibility
>somewhere, it becomes a lot easier to say yes.
>
>> Should have a reroll in the next 30min, it was ready to go and then I
>> got this mail :)
>
>Sounds good.  I don't think anything in this email should affect that reroll.
>
>[0] https://github.com/ChristopherHX/github-act-runner
>--
>brian m. carlson (they/them or he/him)
>Toronto, Ontario, CA

--Randall

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

[Emily Shaffer]

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?

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Fri, Jul 12, 2024 at 12:33 PM brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> On 2024-07-11 at 23:15:35, Emily Shaffer wrote:
> > On Thu, Jul 11, 2024 at 3:24 PM brian m. carlson
> > <sandals@crustytoothpaste.net> wrote:
> > > Some older OSes require kernel features that aren't compiled in by
> > > default, so containers are out.  For example, CentOS 6 won't run on a
> > > modern kernel because it lacks whatever the predecessor to the vDSO was
> > > (which can be recompiled into the kernel, but nobody does that).
> >
> > Is this hinting that we should mention a minimum kernel version for
> > Linux-kernel-based OSes?
>
> This is actually a feature that still exists in the kernel and could be
> enabled for newer kernels, but because distros don't use it (they use
> the vDSO instead), they don't compile it in.
>
> I'm not sure a minimum kernel version is helpful, because most of the
> LTS distro kernels backport features, like Red Hat backported getrandom
> for example.  In the interests of getting to a useful agreement, I think
> for now we should just punt on this and having a 10 year lifespan will
> probably do the trick, and we can determine in the future if we need to
> apply more stringent measures.

Sounds good, thanks!

>
> > > We also don't really want to be on the hook for trying to support OSes
> > > Ubuntu is still derived from Debian.  It is likely that things which
> > > work in one will work in another, but not guaranteed.
> > >
> > > I mention Debian is because it has a large variety of supported
> > > architectures.  I absolutely don't want to say, "Oh, you have MIPS
> > > hardware, too bad if Git doesn't work for you."  (I assure you the
> > > distro maintainers will be displeased if we break Git on less common
> > > architectures, as will I.)  In fact, MIPS is an architecture that
> > > requires natural alignment and can be big-endian, so it's very useful in
> > > helping us find places we wrote invalid or unportable C.
> > >
> > > The reason I'm very hesitant to require that we run everything in GitHub
> > > Actions because it only supports two architectures.  ARM64 and RISC-V
> > > are really popular, and I can tell you that running even a Linux
> > > container in emulation is really quite slow.  I do it for my projects,
> > > but Git LFS only builds one set of non-x86 packages (the latest Debian)
> > > because emulation is far too slow to build the normal suite of five or
> > > six packages.
> >
> > Does that restriction apply to just GitHub-hosted runners, though?
> > Would it be possible for an interested party to set up self-hosted
> > runners (configured via GH Actions) that are using AMD or POWER or
> > whatever? (For example, I think it would be quite feasible for Google
> > to donate some compute for this, though no promises).
>
> Self-hosted runners on public code are very hard to secure.  You're
> basically letting arbitrary people on the Internet run code on those
> machines and make outgoing network connections (due to the fact that you
> can push whatever into a PR branch), with all of the potential for abuse
> that that involves (and as my colleagues can tell you, there's a whole
> lot of it).  GitHub has taken extensive pains to secure GitHub Actions
> runners in the cloud, and while we use self-hosted runners for some
> internal projects, they are absolutely not allowed for any public
> project for that reason.
>
> I would be delighted if Google were willing to do that, but I think
> you're going to need help from teams like Google Cloud who are going to
> be used to dealing with abuse at scale, like cryptocurrency miners and
> such.  Unfortunately, there are many people who act in a less than
> lovely way and will exploit whatever they can to make a buck.
>
> I will also note that the official Actions runner is in C# and only runs
> on a handful of platforms due to the lack of portability of C#.  (It
> might theoretically run on Mono, which would increase its portability,
> but I must profess my complete ignorance on anything about that code.) I
> also know of an unofficial one in Go[0], which I'm for obvious reasons
> unable to endorse, encourage, or speak about authoritatively in any way,
> but that would still exclude some platforms and architectures which
> don't support Go.

Do you think it's worth us linking out to some helpful doc (like the
official one, and someone who doesn't work at GH adding a link to some
unofficial Golang thing)? I sort of feel like since "you can also DIY
a scraper that looks at the mailing list if you want" is included, the
gist makes it across, so I'm tempted not to go into a bunch of
prescriptive detail here.

>
> > The appeal is not "because GitHub Actions are great!" for me - the
> > appeal is "because most Git developers run the CI this way if they
> > remember to or use GGG, and Junio runs it on `seen` all the time". If
> > there's some other recommendation for self-service CI runs that don't
> > need some careful reminding or secret knowledge to run, I'm happy with
> > that too. (For example, if someone wants to set up some bot that looks
> > for new [PATCH]-shaped emails, applies, builds, runs tests, and mails
> > test results to the author after run, that would fit into the spirit
> > of this point, although that sounds like a lot of setup to me.)
>
> Yeah, I understand what you're going for.  If there were some super easy
> way to get everything running in an automatic CI, I'm all for it.  I
> think CI is the easiest way to make sure we don't break anything.
>
> I think it's worth trying to get CI set up for whatever we can, and if
> CI is a possibility somewhere, it becomes a lot easier to say yes.
>
> > Should have a reroll in the next 30min, it was ready to go and then I
> > got this mail :)
>
> Sounds good.  I don't think anything in this email should affect that
> reroll.
>
> [0] https://github.com/ChristopherHX/github-act-runner
> --
> brian m. carlson (they/them or he/him)
> Toronto, Ontario, CA

Re: [PATCH] Documentation: add platform support policy

[Emily Shaffer]

On Fri, Jul 12, 2024 at 12:46 PM <rsbecker@nexbridge.com> wrote:
>
> On Friday, July 12, 2024 3:34 PM, brian m. carlson wrote:
> >Subject: Re: [PATCH] Documentation: add platform support policy
> >
> >On 2024-07-11 at 23:15:35, Emily Shaffer wrote:
> >> On Thu, Jul 11, 2024 at 3:24 PM brian m. carlson
> >> <sandals@crustytoothpaste.net> wrote:
> >> > Some older OSes require kernel features that aren't compiled in by
> >> > default, so containers are out.  For example, CentOS 6 won't run on
> >> > a modern kernel because it lacks whatever the predecessor to the
> >> > vDSO was (which can be recompiled into the kernel, but nobody does that).
> >>
> >> Is this hinting that we should mention a minimum kernel version for
> >> Linux-kernel-based OSes?
> >
> >This is actually a feature that still exists in the kernel and could be enabled for newer
> >kernels, but because distros don't use it (they use the vDSO instead), they don't
> >compile it in.
> >
> >I'm not sure a minimum kernel version is helpful, because most of the LTS distro
> >kernels backport features, like Red Hat backported getrandom for example.  In the
> >interests of getting to a useful agreement, I think for now we should just punt on
> >this and having a 10 year lifespan will probably do the trick, and we can determine
> >in the future if we need to apply more stringent measures.
>
> When looking at the "exotics", many have their own kernel lifespans. When worrying about NonStop, for example, the Kernel version stays around about 5 years under full support, then goes another few until retired. I think it is important for people to know the compatible versions of the kernel builds have. I do track those for the platform.
>
> >> > We also don't really want to be on the hook for trying to support
> >> > OSes Ubuntu is still derived from Debian.  It is likely that things
> >> > which work in one will work in another, but not guaranteed.
> >> >
> >> > I mention Debian is because it has a large variety of supported
> >> > architectures.  I absolutely don't want to say, "Oh, you have MIPS
> >> > hardware, too bad if Git doesn't work for you."  (I assure you the
> >> > distro maintainers will be displeased if we break Git on less common
> >> > architectures, as will I.)  In fact, MIPS is an architecture that
> >> > requires natural alignment and can be big-endian, so it's very
> >> > useful in helping us find places we wrote invalid or unportable C.
> >> >
> >> > The reason I'm very hesitant to require that we run everything in
> >> > GitHub Actions because it only supports two architectures.  ARM64
> >> > and RISC-V are really popular, and I can tell you that running even
> >> > a Linux container in emulation is really quite slow.  I do it for my
> >> > projects, but Git LFS only builds one set of non-x86 packages (the
> >> > latest Debian) because emulation is far too slow to build the normal
> >> > suite of five or six packages.
> >>
> >> Does that restriction apply to just GitHub-hosted runners, though?
> >> Would it be possible for an interested party to set up self-hosted
> >> runners (configured via GH Actions) that are using AMD or POWER or
> >> whatever? (For example, I think it would be quite feasible for Google
> >> to donate some compute for this, though no promises).
> >
> >Self-hosted runners on public code are very hard to secure.  You're basically letting
> >arbitrary people on the Internet run code on those machines and make outgoing
> >network connections (due to the fact that you can push whatever into a PR
> >branch), with all of the potential for abuse that that involves (and as my colleagues
> >can tell you, there's a whole lot of it).  GitHub has taken extensive pains to secure
> >GitHub Actions runners in the cloud, and while we use self-hosted runners for some
> >internal projects, they are absolutely not allowed for any public project for that
> >reason.
>
> I'm not sure this applies to some of the exotics. NonStop cannot run the Google CI code.


I assume you meant the GitHub CI code?

> While we could, in theory, connect to via SSH to run builds, my system is behind a VPN/Firewall, which would make the builds impossible. I do build using Jenkins based on an SCM poll. It's not perfect and some tests do not run correctly in Jenkins but do outside. I would like to provide the feedback to the git team, somehow, on what built successfully or not, outside of the mailing list.

I hope that the overall intent - you need to give us *something* that
we can self-serve issue reproduction on, or else you can deal with
lower quality of service - is clear and understood. It sounds like
this puts NonStop squarely into this second category, running against
`next` or `seen` on a nightly cadence and publishing breakage reports,
then working closely with developers to make fixes as appropriate (or
making them yourself). (By the way, is this doc something you can
point your manager chain to to explain why Git issues appear and how
to stop them from doing so? Maybe that would make your life easier,
even if the answer to that conversation is "we can't provide what Git
is asking for, so we'll be OK with lower quality of support"...)

>
> >I would be delighted if Google were willing to do that, but I think you're going to
> >need help from teams like Google Cloud who are going to be used to dealing with
> >abuse at scale, like cryptocurrency miners and such.  Unfortunately, there are many
> >people who act in a less than lovely way and will exploit whatever they can to make
> >a buck.
> >
> >I will also note that the official Actions runner is in C# and only runs on a handful of
> >platforms due to the lack of portability of C#.  (It might theoretically run on Mono,
> >which would increase its portability, but I must profess my complete ignorance on
> >anything about that code.) I also know of an unofficial one in Go[0], which I'm for
> >obvious reasons unable to endorse, encourage, or speak about authoritatively in
> >any way, but that would still exclude some platforms and architectures which don't
> >support Go.
>
> We don't have C# or Go, nor are likely to any time soon, so that is a problem.
>
> >
> >> The appeal is not "because GitHub Actions are great!" for me - the
> >> appeal is "because most Git developers run the CI this way if they
> >> remember to or use GGG, and Junio runs it on `seen` all the time". If
> >> there's some other recommendation for self-service CI runs that don't
> >> need some careful reminding or secret knowledge to run, I'm happy with
> >> that too. (For example, if someone wants to set up some bot that looks
> >> for new [PATCH]-shaped emails, applies, builds, runs tests, and mails
> >> test results to the author after run, that would fit into the spirit
> >> of this point, although that sounds like a lot of setup to me.)
> >
> >Yeah, I understand what you're going for.  If there were some super easy way to get
> >everything running in an automatic CI, I'm all for it.  I think CI is the easiest way to
> >make sure we don't break anything.
> >
> >I think it's worth trying to get CI set up for whatever we can, and if CI is a possibility
> >somewhere, it becomes a lot easier to say yes.
> >
> >> Should have a reroll in the next 30min, it was ready to go and then I
> >> got this mail :)
> >
> >Sounds good.  I don't think anything in this email should affect that reroll.
> >
> >[0] https://github.com/ChristopherHX/github-act-runner
> >--
> >brian m. carlson (they/them or he/him)
> >Toronto, Ontario, CA
>
> --Randall
>

RE: [PATCH] Documentation: add platform support policy

[rsbecker]

On Monday, July 15, 2024 6:28 PM, Emily Shaffer wrote:
>On Fri, Jul 12, 2024 at 12:46 PM <rsbecker@nexbridge.com> wrote:
>>
>> On Friday, July 12, 2024 3:34 PM, brian m. carlson wrote:
>> >Subject: Re: [PATCH] Documentation: add platform support policy
>> >
>> >On 2024-07-11 at 23:15:35, Emily Shaffer wrote:
>> >> On Thu, Jul 11, 2024 at 3:24 PM brian m. carlson
>> >> <sandals@crustytoothpaste.net> wrote:
>> >> > Some older OSes require kernel features that aren't compiled in
>> >> > by default, so containers are out.  For example, CentOS 6 won't
>> >> > run on a modern kernel because it lacks whatever the predecessor
>> >> > to the vDSO was (which can be recompiled into the kernel, but nobody does
>that).
>> >>
>> >> Is this hinting that we should mention a minimum kernel version for
>> >> Linux-kernel-based OSes?
>> >
>> >This is actually a feature that still exists in the kernel and could
>> >be enabled for newer kernels, but because distros don't use it (they
>> >use the vDSO instead), they don't compile it in.
>> >
>> >I'm not sure a minimum kernel version is helpful, because most of the
>> >LTS distro kernels backport features, like Red Hat backported
>> >getrandom for example.  In the interests of getting to a useful
>> >agreement, I think for now we should just punt on this and having a
>> >10 year lifespan will probably do the trick, and we can determine in the future if
>we need to apply more stringent measures.
>>
>> When looking at the "exotics", many have their own kernel lifespans. When
>worrying about NonStop, for example, the Kernel version stays around about 5
>years under full support, then goes another few until retired. I think it is important
>for people to know the compatible versions of the kernel builds have. I do track
>those for the platform.
>>
>> >> > We also don't really want to be on the hook for trying to support
>> >> > OSes Ubuntu is still derived from Debian.  It is likely that
>> >> > things which work in one will work in another, but not guaranteed.
>> >> >
>> >> > I mention Debian is because it has a large variety of supported
>> >> > architectures.  I absolutely don't want to say, "Oh, you have
>> >> > MIPS hardware, too bad if Git doesn't work for you."  (I assure
>> >> > you the distro maintainers will be displeased if we break Git on
>> >> > less common architectures, as will I.)  In fact, MIPS is an
>> >> > architecture that requires natural alignment and can be
>> >> > big-endian, so it's very useful in helping us find places we wrote invalid or
>unportable C.
>> >> >
>> >> > The reason I'm very hesitant to require that we run everything in
>> >> > GitHub Actions because it only supports two architectures.  ARM64
>> >> > and RISC-V are really popular, and I can tell you that running
>> >> > even a Linux container in emulation is really quite slow.  I do
>> >> > it for my projects, but Git LFS only builds one set of non-x86
>> >> > packages (the latest Debian) because emulation is far too slow to
>> >> > build the normal suite of five or six packages.
>> >>
>> >> Does that restriction apply to just GitHub-hosted runners, though?
>> >> Would it be possible for an interested party to set up self-hosted
>> >> runners (configured via GH Actions) that are using AMD or POWER or
>> >> whatever? (For example, I think it would be quite feasible for
>> >> Google to donate some compute for this, though no promises).
>> >
>> >Self-hosted runners on public code are very hard to secure.  You're
>> >basically letting arbitrary people on the Internet run code on those
>> >machines and make outgoing network connections (due to the fact that
>> >you can push whatever into a PR branch), with all of the potential
>> >for abuse that that involves (and as my colleagues can tell you,
>> >there's a whole lot of it).  GitHub has taken extensive pains to
>> >secure GitHub Actions runners in the cloud, and while we use
>> >self-hosted runners for some internal projects, they are absolutely not allowed
>for any public project for that reason.
>>
>> I'm not sure this applies to some of the exotics. NonStop cannot run the Google CI
>code.
>
>
>I assume you meant the GitHub CI code?

Yes, sorry.

>> While we could, in theory, connect to via SSH to run builds, my system is behind a
>VPN/Firewall, which would make the builds impossible. I do build using Jenkins
>based on an SCM poll. It's not perfect and some tests do not run correctly in Jenkins
>but do outside. I would like to provide the feedback to the git team, somehow, on
>what built successfully or not, outside of the mailing list.
>
>I hope that the overall intent - you need to give us *something* that we can self-
>serve issue reproduction on, or else you can deal with lower quality of service - is
>clear and understood. It sounds like this puts NonStop squarely into this second
>category, running against `next` or `seen` on a nightly cadence and publishing
>breakage reports, then working closely with developers to make fixes as appropriate
>(or making them yourself). (By the way, is this doc something you can point your
>manager chain to to explain why Git issues appear and how to stop them from
>doing so? Maybe that would make your life easier, even if the answer to that
>conversation is "we can't provide what Git is asking for, so we'll be OK with lower
>quality of support"...)

That is my expectation also.

>> >I would be delighted if Google were willing to do that, but I think
>> >you're going to need help from teams like Google Cloud who are going
>> >to be used to dealing with abuse at scale, like cryptocurrency miners
>> >and such.  Unfortunately, there are many people who act in a less
>> >than lovely way and will exploit whatever they can to make a buck.
>> >
>> >I will also note that the official Actions runner is in C# and only
>> >runs on a handful of platforms due to the lack of portability of C#.
>> >(It might theoretically run on Mono, which would increase its
>> >portability, but I must profess my complete ignorance on anything
>> >about that code.) I also know of an unofficial one in Go[0], which
>> >I'm for obvious reasons unable to endorse, encourage, or speak about
>> >authoritatively in any way, but that would still exclude some platforms and
>architectures which don't support Go.
>>
>> We don't have C# or Go, nor are likely to any time soon, so that is a problem.
>>
>> >
>> >> The appeal is not "because GitHub Actions are great!" for me - the
>> >> appeal is "because most Git developers run the CI this way if they
>> >> remember to or use GGG, and Junio runs it on `seen` all the time".
>> >> If there's some other recommendation for self-service CI runs that
>> >> don't need some careful reminding or secret knowledge to run, I'm
>> >> happy with that too. (For example, if someone wants to set up some
>> >> bot that looks for new [PATCH]-shaped emails, applies, builds, runs
>> >> tests, and mails test results to the author after run, that would
>> >> fit into the spirit of this point, although that sounds like a lot
>> >> of setup to me.)
>> >
>> >Yeah, I understand what you're going for.  If there were some super
>> >easy way to get everything running in an automatic CI, I'm all for
>> >it.  I think CI is the easiest way to make sure we don't break anything.
>> >
>> >I think it's worth trying to get CI set up for whatever we can, and
>> >if CI is a possibility somewhere, it becomes a lot easier to say yes.
>> >
>> >> Should have a reroll in the next 30min, it was ready to go and then
>> >> I got this mail :)
>> >
>> >Sounds good.  I don't think anything in this email should affect that reroll.
>> >
>> >[0] https://github.com/ChristopherHX/github-act-runner
>> >--
>> >brian m. carlson (they/them or he/him) Toronto, Ontario, CA
>>
>> --Randall
>>

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

[Junio C Hamano]

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.

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

[Emily Shaffer]

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 :/)

RE: [PATCH v2] Documentation: add platform support policy

[rsbecker]

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 :/)

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

[Junio C Hamano]

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.

[PATCH v3] Documentation: add platform support policy

[Emily Shaffer]

Supporting many platforms is only easy when we have the right tools to
ensure that support.

Teach platform maintainers how they can help us to help them, by
explaining what kind of tooling support we would like to have, and what
level of support becomes available as a result. Provide examples so that
platform maintainers can see what we're asking for in practice.

With this policy in place, we can make changes with stronger assurance
that we are not breaking anybody we promised not to. Instead, we can
feel confident that our existing testing and integration practices
protect those who care from breakage.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>

---

New in v3:

- Made language to platform maintainers a little clearer (hopefully)
  about this allowing us to provide more predictable support levels.

- Clarified that this covers maintaining previous functionality, not
  adding support for something new.

- Made the bullet point formatting a little less eye-bleedy.

- Asked reporters to make sure that bugs are really a platform
  compatibility bug, and not a regular bug.

- Rephrased section intros to emphasize what the platform maintainer
  gets, rather than emphasize the Git project patch lifecycle.

- Clarified alternatives to GitHub Actions CI: GitLab or list scraping.
  Made some notes about avoiding noise.

- Small fixes to formatting, spacing, etc

Thanks,

 - Emily

v1 description at
https://lore.kernel.org/git/20240709225042.2005233-1-emilyshaffer@google.com/
---
 Documentation/Makefile                       |   1 +
 Documentation/technical/platform-support.txt | 177 +++++++++++++++++++
 2 files changed, 178 insertions(+)
 create mode 100644 Documentation/technical/platform-support.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index dc65759cb1..462af0311f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -118,6 +118,7 @@ TECH_DOCS += technical/multi-pack-index
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
+TECH_DOCS += technical/platform-support
 TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
 TECH_DOCS += technical/scalar
diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt
new file mode 100644
index 0000000000..981997e635
--- /dev/null
+++ b/Documentation/technical/platform-support.txt
@@ -0,0 +1,177 @@
+Platform Support Policy
+=======================
+
+Git has a history of providing broad "support" for exotic platforms and older
+platforms, without an explicit commitment. Stakeholders of these platforms may
+want a more predictable support commitment. This is only possible when platform
+stakeholders supply Git developers with adequate tooling, so we can test for
+compatibility or develop workarounds for platform-specific quirks on our own.
+Various levels of tooling will allow us to make more solid commitments around
+Git's compatibility with your platform.
+
+Note that this document is about maintaining existing support for a platform
+that has generally worked in the past; for adding support to a platform which
+doesn't generally work with Git, the stakeholders for that platform are expected
+to do the bulk of that work themselves. We will consider such patches if they
+don't make life harder for other supported platforms, and you may well find a
+contributor interested in working on that support, but the Git community as a
+whole doesn't feel an obligation to perform such work.
+
+Compatible by next release
+--------------------------
+
+To increase probability that compatibility issues introduced in a release
+will be fixed in a later release:
+
+* You should send a bug report as soon as you notice the breakage on your
+  platform. The sooner you notice, the better; watching `seen` means you can
+  notice problems before they are considered "done with review"; whereas
+  watching `master` means the stable branch could break for your platform, but
+  you have a decent chance of avoiding a tagged release breaking you. See "The
+  Policy" in the link:../howto/maintain-git.txt[maintainer's guide] for an
+  overview of which branches are used in git.git, and how.
+
+* The bug report should include information about what platform you are using.
+
+* You should also use linkgit:git-bisect[1] and determine which commit
+  introduced the breakage.
+
+* Please include any information you have about the nature of the breakage: is
+  it a memory alignment issue? Is an underlying library missing or broken for
+  your platform? Is there some quirk about your platform which means typical
+  practices (like malloc) behave strangely?
+
+** If possible, build Git from the exact same source both for your platform and
+   for a maintstream platform, and make sure the problem you noticed appears
+   only on your platform. If the problem appears in both, then it's not a
+   compatibility issue, but we of course appreciate hearing about it in a bug
+   report anyway, to benefit users of every platform.
+
+* Once we begin to fix the issue, please work closely with the contributor
+  working on it to test the proposed fix against your platform.
+
+Example: NonStop
+https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports
+problems] when they're noticed.
+
+Compatible on `master` and releases
+-----------------------------------------
+
+To make sure all stable builds and regular releases work for your platform the
+first time, you can make sure `master` doesn't break for your platform:
+
+* You should run nightly tests against the `next` branch and publish breakage
+  reports to the mailing list immediately when they happen.
+
+** You may want to ask to join the mailto:git-security@googlegroups.com[security
+   mailing list] in order to run tests against the fixes proposed there, too.
+
+* It may make sense to automate these; if you do, make sure they are not noisy
+  (you don't need to send a report when everything works, only when something
+  breaks; you don't need to send repeated reports for the same breakage night
+  after night).
+
+* Breakage reports should be actionable - include clear error messages that can
+  help developers who may not have access to test directly on your platform.
+
+* You should use git-bisect and determine which commit introduced the breakage;
+  if you can't do this with automation, you should do this yourself manually as
+  soon as you notice a breakage report was sent.
+
+* You should either:
+
+** Provide VM access on-demand to a trusted developer working to fix the issue,
+   so they can test their fix, OR
+
+** Work closely with the developer fixing the issue; the turnaround to check
+   that their proposed fix works for your platform should be fast enough that it
+   doesn't hinder the developer working on that fix. Slow testing turnarounds
+   may cause the fix to miss the next release, or the developer may lose
+   interest in working on the fix at all.
+
+Example:
+https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/[AIX]
+provides a build farm and runs tests against release candidates.
+
+Compatible on `next`
+--------------------
+
+To avoid reactive debugging and fixing when changes hit a release or stable, you
+can aim to ensure `next` works for your platform. (See "The Policy" in the
+link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next`
+is used in the Git project.) To do that:
+
+* You should add a runner for your platform to the GitHub Actions or GitLab CI
+  suite.  This suite is run when any Git developer proposes a new patch, and
+  having a runner for your platform/configuration means every developer will
+  know if they break you, immediately.
+
+** If adding it to an existing CI suite is infeasible (due to architecture
+   constraints or for performance reasons), any other method which runs as
+   automatically and quickly as possible works, too. For example, a service
+   which snoops on the mailing list and automatically runs tests on new [PATCH]
+   emails, replying to the author with the results, would also be within the
+   spirit of this requirement.
+
+* If you rely on Git avoiding a specific pattern that doesn't work well with
+  your platform (like a certain malloc pattern), raise it on the mailing list.
+  There are a few ways to avoid these breakages, so we'll work case-by-case to
+  find a solution that doesn't unnecessarily constrain other platforms to keep
+  compatibility with yours.
+
+* If you rely on some configuration or behavior, add a test for it. Untested
+  behavior is subject to breakage at any time.
+
+** Clearly label these tests as necessary for platform compatibility. Add them
+   to an isolated compatibility-related test suite, like a new t* file or unit
+   test suite, so that they're easy to remove when compatibility is no longer
+   required.  If the specific compatibility need is gated behind an issue with
+   another project, link to documentation of that issue (like a bug or email
+   thread) to make it easier to tell when that compatibility need goes away.
+
+** Include a comment with an expiration date for these tests no more than 1 year
+   from now. You can update the expiration date if your platform still needs
+   that assurance down the road, but we need to know you still care about that
+   compatibility case and are working to make it unnecessary.
+
+Example: We run our
+https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI
+suite] on Windows, Ubuntu, Mac, and others.
+
+Getting help writing platform support patches
+---------------------------------------------
+
+In general, when sending patches to fix platform support problems, follow
+these guidelines to make sure the patch is reviewed with the appropriate level
+of urgency:
+
+* Clearly state in the commit message that you are fixing a platform breakage,
+  and for which platform.
+
+* Use the CI and test suite to ensure that the fix for your platform doesn't
+  break other platforms.
+
+* If possible, add a test ensuring this regression doesn't happen again. If
+  it's not possible to add a test, explain why in the commit message.
+
+Minimum Requirements
+--------------------
+
+Even if platform maintainers are willing to add tests or CI runners, we will
+not consider helping to support platforms that do not meet these minimum
+requirements:
+
+* Has C99 or C11
+
+* Has dependencies which were released in the past 10 years
+
+* Has active security support (taking security releases of dependencies, etc)
+
+Platform Maintainers
+--------------------
+
+If you maintain a platform, or Git for that platform, and intend to work with
+the Git project to ensure compatibility, please send a patch to add yourself to
+this list.
+
+NonStop: Randall S. Becker <rsbecker@nexbridge.com>

Range-diff against v2:
1:  653661002c ! 1:  575c5a5a5f Documentation: add platform support policy
     
    @@ Documentation/technical/platform-support.txt (new)
     +=======================
     +
     +Git has a history of providing broad "support" for exotic platforms and older
    -+platforms, without an explicit commitment. This support becomes easier to
    -+maintain (and possible to commit to) when Git developers are provided with
    -+adequate tooling to test for compatibility. Various levels of tooling will
    -+allow us to make more solid commitments around Git's compatibility with your
    -+platform.
    ++platforms, without an explicit commitment. Stakeholders of these platforms may
    ++want a more predictable support commitment. This is only possible when platform
    ++stakeholders supply Git developers with adequate tooling, so we can test for
    ++compatibility or develop workarounds for platform-specific quirks on our own.
    ++Various levels of tooling will allow us to make more solid commitments around
    ++Git's compatibility with your platform.
    ++
    ++Note that this document is about maintaining existing support for a platform
    ++that has generally worked in the past; for adding support to a platform which
    ++doesn't generally work with Git, the stakeholders for that platform are expected
    ++to do the bulk of that work themselves. We will consider such patches if they
    ++don't make life harder for other supported platforms, and you may well find a
    ++contributor interested in working on that support, but the Git community as a
    ++whole doesn't feel an obligation to perform such work.
     +
     +Compatible by next release
     +--------------------------
    @@ Documentation/technical/platform-support.txt (new)
     +will be fixed in a later release:
     +
     +* You should send a bug report as soon as you notice the breakage on your
    -+platform. The sooner you notice, the better; watching `seen` means you can
    -+notice problems before they are considered "done with review"; whereas watching
    -+`master` means the stable branch could break for your platform, but you have a
    -+decent chance of avoiding a tagged release breaking you. See "The Policy" in the
    -+link:../howto/maintain-git.txt[maintainer's guide] for an overview of which
    -+branches are used in git.git, and how.
    ++  platform. The sooner you notice, the better; watching `seen` means you can
    ++  notice problems before they are considered "done with review"; whereas
    ++  watching `master` means the stable branch could break for your platform, but
    ++  you have a decent chance of avoiding a tagged release breaking you. See "The
    ++  Policy" in the link:../howto/maintain-git.txt[maintainer's guide] for an
    ++  overview of which branches are used in git.git, and how.
    ++
     +* The bug report should include information about what platform you are using.
    ++
     +* You should also use linkgit:git-bisect[1] and determine which commit
    -+introduced the breakage.
    ++  introduced the breakage.
    ++
     +* Please include any information you have about the nature of the breakage: is
    -+it a memory alignment issue? Is an underlying library missing or broken for
    -+your platform? Is there some quirk about your platform which means typical
    -+practices (like malloc) behave strangely?
    ++  it a memory alignment issue? Is an underlying library missing or broken for
    ++  your platform? Is there some quirk about your platform which means typical
    ++  practices (like malloc) behave strangely?
    ++
    ++** If possible, build Git from the exact same source both for your platform and
    ++   for a maintstream platform, and make sure the problem you noticed appears
    ++   only on your platform. If the problem appears in both, then it's not a
    ++   compatibility issue, but we of course appreciate hearing about it in a bug
    ++   report anyway, to benefit users of every platform.
    ++
     +* Once we begin to fix the issue, please work closely with the contributor
    -+working on it to test the proposed fix against your platform.
    ++  working on it to test the proposed fix against your platform.
     +
     +Example: NonStop
     +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports
     +problems] when they're noticed.
     +
    -+Compatible on `master` and point releases
    ++Compatible on `master` and releases
     +-----------------------------------------
     +
    -+To guarantee that `master` and all point releases work for your platform the
    -+first time:
    ++To make sure all stable builds and regular releases work for your platform the
    ++first time, you can make sure `master` doesn't break for your platform:
     +
     +* You should run nightly tests against the `next` branch and publish breakage
    -+reports to the mailing list immediately when they happen.
    ++  reports to the mailing list immediately when they happen.
    ++
     +** You may want to ask to join the mailto:git-security@googlegroups.com[security
    -+mailing list] in order to run tests against the fixes proposed there, too.
    ++   mailing list] in order to run tests against the fixes proposed there, too.
    ++
     +* It may make sense to automate these; if you do, make sure they are not noisy
    -+(you don't need to send a report when everything works, only when something
    -+breaks).
    ++  (you don't need to send a report when everything works, only when something
    ++  breaks; you don't need to send repeated reports for the same breakage night
    ++  after night).
    ++
     +* Breakage reports should be actionable - include clear error messages that can
    -+help developers who may not have access to test directly on your platform.
    ++  help developers who may not have access to test directly on your platform.
    ++
     +* You should use git-bisect and determine which commit introduced the breakage;
    -+if you can't do this with automation, you should do this yourself manually as
    -+soon as you notice a breakage report was sent.
    ++  if you can't do this with automation, you should do this yourself manually as
    ++  soon as you notice a breakage report was sent.
    ++
     +* You should either:
    ++
     +** Provide VM access on-demand to a trusted developer working to fix the issue,
    -+so they can test their fix, OR
    ++   so they can test their fix, OR
    ++
     +** Work closely with the developer fixing the issue; the turnaround to check
    -+that their proposed fix works for your platform should be fast enough that it
    -+doesn't hinder the developer working on that fix. Slow testing turnarounds may
    -+cause the fix to miss the next release, or the developer may lose interest in
    -+working on the fix at all.
    ++   that their proposed fix works for your platform should be fast enough that it
    ++   doesn't hinder the developer working on that fix. Slow testing turnarounds
    ++   may cause the fix to miss the next release, or the developer may lose
    ++   interest in working on the fix at all.
     +
     +Example:
     +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/[AIX]
    @@ Documentation/technical/platform-support.txt (new)
     +Compatible on `next`
     +--------------------
     +
    -+To guarantee that `next` will work for your platform, avoiding reactive
    -+debugging and fixing:
    -+
    -+* You should add a runner for your platform to the GitHub Actions CI suite.
    -+This suite is run when any Git developer proposes a new patch, and having a
    -+runner for your platform/configuration means every developer will know if they
    -+break you, immediately.
    -+** If adding it to GitHub Actions is infeasible (due to architecture constraints
    -+or for performance reasons), any other method which runs as automatically and
    -+quickly as possible works, too. For example, a service which snoops on the
    -+mailing list and automatically runs tests on new [PATCH] emails, replying to the
    -+author with the results, would also be within the spirit of this requirement.
    ++To avoid reactive debugging and fixing when changes hit a release or stable, you
    ++can aim to ensure `next` works for your platform. (See "The Policy" in the
    ++link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next`
    ++is used in the Git project.) To do that:
    ++
    ++* You should add a runner for your platform to the GitHub Actions or GitLab CI
    ++  suite.  This suite is run when any Git developer proposes a new patch, and
    ++  having a runner for your platform/configuration means every developer will
    ++  know if they break you, immediately.
    ++
    ++** If adding it to an existing CI suite is infeasible (due to architecture
    ++   constraints or for performance reasons), any other method which runs as
    ++   automatically and quickly as possible works, too. For example, a service
    ++   which snoops on the mailing list and automatically runs tests on new [PATCH]
    ++   emails, replying to the author with the results, would also be within the
    ++   spirit of this requirement.
    ++
     +* If you rely on Git avoiding a specific pattern that doesn't work well with
    -+your platform (like a certain malloc pattern), raise it on the mailing list.
    -+There are a few ways to avoid these breakages, so we'll work case-by-case to
    -+find a solution that doesn't unnecessarily constrain other platforms to keep
    -+compatibility with yours.
    -+* If you rely on some configuration or behavior, add a test for it.  Untested
    -+behavior is subject to breakage at any time.
    ++  your platform (like a certain malloc pattern), raise it on the mailing list.
    ++  There are a few ways to avoid these breakages, so we'll work case-by-case to
    ++  find a solution that doesn't unnecessarily constrain other platforms to keep
    ++  compatibility with yours.
    ++
    ++* If you rely on some configuration or behavior, add a test for it. Untested
    ++  behavior is subject to breakage at any time.
    ++
     +** Clearly label these tests as necessary for platform compatibility. Add them
    -+to an isolated compatibility-related test suite, like a new t* file or unit test
    -+suite, so that they're easy to remove when compatibility is no longer required.
    -+If the specific compatibility need is gated behind an issue with another
    -+project, link to documentation of that issue (like a bug or email thread) to
    -+make it easier to tell when that compatibility need goes away.
    ++   to an isolated compatibility-related test suite, like a new t* file or unit
    ++   test suite, so that they're easy to remove when compatibility is no longer
    ++   required.  If the specific compatibility need is gated behind an issue with
    ++   another project, link to documentation of that issue (like a bug or email
    ++   thread) to make it easier to tell when that compatibility need goes away.
    ++
     +** Include a comment with an expiration date for these tests no more than 1 year
    -+from now. You can update the expiration date if your platform still needs that
    -+assurance down the road, but we need to know you still care about that
    -+compatibility case and are working to make it unnecessary.
    ++   from now. You can update the expiration date if your platform still needs
    ++   that assurance down the road, but we need to know you still care about that
    ++   compatibility case and are working to make it unnecessary.
     +
     +Example: We run our
     +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI
    @@ Documentation/technical/platform-support.txt (new)
     +of urgency:
     +
     +* Clearly state in the commit message that you are fixing a platform breakage,
    -+and for which platform.
    ++  and for which platform.
    ++
     +* Use the CI and test suite to ensure that the fix for your platform doesn't
    -+break other platforms.
    ++  break other platforms.
    ++
     +* If possible, add a test ensuring this regression doesn't happen again. If
    -+it's not possible to add a test, explain why in the commit message.
    ++  it's not possible to add a test, explain why in the commit message.
     +
     +Minimum Requirements
     +--------------------
    @@ Documentation/technical/platform-support.txt (new)
     +requirements:
     +
     +* Has C99 or C11
    ++
     +* Has dependencies which were released in the past 10 years
    ++
     +* Has active security support (taking security releases of dependencies, etc)
     +
     +Platform Maintainers
-- 
2.45.2.1089.g2a221341d9-goog

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

[Emily Shaffer]

On Thu, Jul 18, 2024 at 10:38 AM Emily Shaffer <emilyshaffer@google.com> wrote:
>
> Supporting many platforms is only easy when we have the right tools to
> ensure that support.
>
> Teach platform maintainers how they can help us to help them, by
> explaining what kind of tooling support we would like to have, and what
> level of support becomes available as a result. Provide examples so that
> platform maintainers can see what we're asking for in practice.
>
> With this policy in place, we can make changes with stronger assurance
> that we are not breaking anybody we promised not to. Instead, we can
> feel confident that our existing testing and integration practices
> protect those who care from breakage.
>
> Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
>
> ---
>
> New in v3:

FYI, the asciidoctor build failed upstream. I won't have a chance to
fix it til at least the afternoon (if not tomorrow), but I'll prepare
a scissors fixup when I can, and include it into the reroll if/when
the next one is needed.

https://github.com/nasamuffin/git/actions/runs/9996112167/job/27629731071

 - Emily

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

[Junio C Hamano]

Emily Shaffer <nasamuffin@google.com> writes:

> FYI, the asciidoctor build failed upstream. I won't have a chance to
> fix it til at least the afternoon (if not tomorrow), but I'll prepare
> a scissors fixup when I can, and include it into the reroll if/when
> the next one is needed.

diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt
index 981997e635..65c0fa20de 100644
--- a/Documentation/technical/platform-support.txt
+++ b/Documentation/technical/platform-support.txt
@@ -54,8 +54,9 @@ Example: NonStop
 https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports
 problems] when they're noticed.
 
+
 Compatible on `master` and releases
------------------------------------------
+-----------------------------------
 
 To make sure all stable builds and regular releases work for your platform the
 first time, you can make sure `master` doesn't break for your platform:

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

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

> Supporting many platforms is only easy when we have the right tools to
> ensure that support.

"easy" -> "possible".

> +Compatible by next release
> +--------------------------
> +
> +To increase probability that compatibility issues introduced in a release
> +will be fixed in a later release:
> +
> +* You should send a bug report as soon as you notice the breakage on your
> +  platform. The sooner you notice, the better; watching `seen` means you can
> +  notice problems before they are considered "done with review"; whereas
> +  watching `master` means the stable branch could break for your platform, but
> +  you have a decent chance of avoiding a tagged release breaking you. See "The
> +  Policy" in the link:../howto/maintain-git.txt[maintainer's guide] for an

Running

    $ make -C Documentation howto/maintain-git.html
    $ lynx Documentation/howto/maintain-git.html

tells me that the title of the document is "How to maintain Git".

> +  overview of which branches are used in git.git, and how.

"git.git" -> "the Git project"

> +Compatible on `master` and releases
> +-----------------------------------------

Underline that signals what level the header is is drawn to the same
column as the header title itself, or you'd confuse the formatter.


> +To make sure all stable builds and regular releases work for your platform the
> +first time, you can make sure `master` doesn't break for your platform:

"can" -> "want to"?  

But "to make sure X, you can make sure Y" feels a bit awkward.

    To make sure ... work for your platform, help us avoid breaking the
    tip of `master` by merging topics that break your platform.

> +* You should run nightly tests against the `next` branch and publish breakage
> +  reports to the mailing list immediately when they happen.

Can't it be daily instead of nightly ;-), or is it better than
nothing if you can afford to run only once every other day?

A topic (unless it is during the shuffle time around -rc0) usually
spends no less than 7 calendar days in 'next', so while I would
appreciate if somebody runs tests twice a day, in practice you
should be able to catch a new breakage in 'next' if you run a full
and thorough test twice a week.

> +* You should either:
> +
> +** Provide VM access on-demand to a trusted developer working to fix the issue,
> +   so they can test their fix, OR

"VM access on-demand" -> "on-demand access to your platform" (iow,
physical iron is also fine for our purpose).

> +Compatible on `next`
> +--------------------
> +
> +To avoid reactive debugging and fixing when changes hit a release or stable, you
> +can aim to ensure `next` works for your platform. (See "The Policy" in the
> +link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next`
> +is used in the Git project.) To do that:
> +
> +* You should add a runner for your platform to the GitHub Actions or GitLab CI
> +  suite.  This suite is run when any Git developer proposes a new patch, and
> +  having a runner for your platform/configuration means every developer will
> +  know if they break you, immediately.
> +
> +** If adding it to an existing CI suite is infeasible (due to architecture
> +   constraints or for performance reasons), any other method which runs as
> +   automatically and quickly as possible works, too. For example, a service
> +   which snoops on the mailing list and automatically runs tests on new [PATCH]
> +   emails, replying to the author with the results, would also be within the
> +   spirit of this requirement.

It would be very nice if they did this, indeed.  Explaining that
something that mechanically looks vastly different is within the
spirit is a very good move.

> +Minimum Requirements
> +--------------------
> +
> +Even if platform maintainers are willing to add tests or CI runners, we will
> +not consider helping to support platforms that do not meet these minimum
> +requirements:
> +
> +* Has C99 or C11

OK.

> +* Has dependencies which were released in the past 10 years

This is hard to understand and I wonder if we can clarify.  I get
what you want to say: suppose we rely on library X that is getting
regular feature and security updates in reasonable cadence, say
every 6 months there is an upstream release of library X, but a
niche platform has ported the library only once long time ago, and
hasn't updated it ever since.  Now the Git project may consider
helping a port to such a platform if the initial port of library X
was 8 years ago, but will not if it was 12 years ago.

But if Git depends on an ultra stable library whose last public
release was 12 years ago, disqualify everybody is not what this
requirement wants to do.

I attempted to formulate my version along ...

    Keep up with the versions of dependencies (libraries, etc.) and
    not to lag behind compared to typical mainstream platforms by
    more than X years.

... the above line, but to me it is no better than the original, so
I failed miserably.  But the idea I am bringing to the table here is
that time of release is not absolute.  If typical mainstream
platforms consider a release of a library made 8 years ago from the
upstream performant, functional, and secure enough and fit for use,
we do not consider that they are approaching the limit.  But if
another platform uses the same library from 12 years ago, i.e.
lagging behind others by 4 years is a problem at the same graveness
using another library that was released 6 years ago, when other
platforms are using a much younger vintage of the same library
released at 2 years ago.

Having said all that, everything I removed from my quote I found
agreeable.  Very well written.

Thanks.

RE: [PATCH v3] Documentation: add platform support policy

[rsbecker]

On Thursday, July 18, 2024 6:46 PM, Junio C Hamano wrote:
>Emily Shaffer <emilyshaffer@google.com> writes:
>
>> Supporting many platforms is only easy when we have the right tools to
>> ensure that support.
>
>"easy" -> "possible".
>
>> +Compatible by next release
>> +--------------------------
>> +
>> +To increase probability that compatibility issues introduced in a
>> +release will be fixed in a later release:
>> +
>> +* You should send a bug report as soon as you notice the breakage on
>> +your
>> +  platform. The sooner you notice, the better; watching `seen` means
>> +you can
>> +  notice problems before they are considered "done with review";
>> +whereas
>> +  watching `master` means the stable branch could break for your
>> +platform, but
>> +  you have a decent chance of avoiding a tagged release breaking you.
>> +See "The
>> +  Policy" in the link:../howto/maintain-git.txt[maintainer's guide]
>> +for an
>
>Running
>
>    $ make -C Documentation howto/maintain-git.html
>    $ lynx Documentation/howto/maintain-git.html
>
>tells me that the title of the document is "How to maintain Git".
>
>> +  overview of which branches are used in git.git, and how.
>
>"git.git" -> "the Git project"
>
>> +Compatible on `master` and releases
>> +-----------------------------------------
>
>Underline that signals what level the header is is drawn to the same column as the
>header title itself, or you'd confuse the formatter.
>
>
>> +To make sure all stable builds and regular releases work for your
>> +platform the first time, you can make sure `master` doesn't break for your
>platform:
>
>"can" -> "want to"?
>
>But "to make sure X, you can make sure Y" feels a bit awkward.
>
>    To make sure ... work for your platform, help us avoid breaking the
>    tip of `master` by merging topics that break your platform.
>
>> +* You should run nightly tests against the `next` branch and publish
>> +breakage
>> +  reports to the mailing list immediately when they happen.
>
>Can't it be daily instead of nightly ;-), or is it better than nothing if you can afford to
>run only once every other day?
>
>A topic (unless it is during the shuffle time around -rc0) usually spends no less than
>7 calendar days in 'next', so while I would appreciate if somebody runs tests twice a
>day, in practice you should be able to catch a new breakage in 'next' if you run a full
>and thorough test twice a week.
>
>> +* You should either:
>> +
>> +** Provide VM access on-demand to a trusted developer working to fix the issue,
>> +   so they can test their fix, OR
>
>"VM access on-demand" -> "on-demand access to your platform" (iow, physical
>iron is also fine for our purpose).
>
>> +Compatible on `next`
>> +--------------------
>> +
>> +To avoid reactive debugging and fixing when changes hit a release or
>> +stable, you can aim to ensure `next` works for your platform. (See
>> +"The Policy" in the link:../howto/maintain-git.txt[maintainer's
>> +guide] for an overview of how `next` is used in the Git project.) To do that:
>> +
>> +* You should add a runner for your platform to the GitHub Actions or
>> +GitLab CI
>> +  suite.  This suite is run when any Git developer proposes a new
>> +patch, and
>> +  having a runner for your platform/configuration means every
>> +developer will
>> +  know if they break you, immediately.
>> +
>> +** If adding it to an existing CI suite is infeasible (due to architecture
>> +   constraints or for performance reasons), any other method which runs as
>> +   automatically and quickly as possible works, too. For example, a service
>> +   which snoops on the mailing list and automatically runs tests on new [PATCH]
>> +   emails, replying to the author with the results, would also be within the
>> +   spirit of this requirement.
>
>It would be very nice if they did this, indeed.  Explaining that something that
>mechanically looks vastly different is within the spirit is a very good move.
>
>> +Minimum Requirements
>> +--------------------
>> +
>> +Even if platform maintainers are willing to add tests or CI runners,
>> +we will not consider helping to support platforms that do not meet
>> +these minimum
>> +requirements:
>> +
>> +* Has C99 or C11
>
>OK.
>
>> +* Has dependencies which were released in the past 10 years
>
>This is hard to understand and I wonder if we can clarify.  I get what you want to
>say: suppose we rely on library X that is getting regular feature and security updates
>in reasonable cadence, say every 6 months there is an upstream release of library X,
>but a niche platform has ported the library only once long time ago, and hasn't
>updated it ever since.  Now the Git project may consider helping a port to such a
>platform if the initial port of library X was 8 years ago, but will not if it was 12 years
>ago.
>
>But if Git depends on an ultra stable library whose last public release was 12 years
>ago, disqualify everybody is not what this requirement wants to do.
>
>I attempted to formulate my version along ...
>
>    Keep up with the versions of dependencies (libraries, etc.) and
>    not to lag behind compared to typical mainstream platforms by
>    more than X years.
>
>... the above line, but to me it is no better than the original, so I failed miserably.  But
>the idea I am bringing to the table here is that time of release is not absolute.  If
>typical mainstream platforms consider a release of a library made 8 years ago from
>the upstream performant, functional, and secure enough and fit for use, we do not
>consider that they are approaching the limit.  But if another platform uses the same
>library from 12 years ago, i.e.
>lagging behind others by 4 years is a problem at the same graveness using another
>library that was released 6 years ago, when other platforms are using a much
>younger vintage of the same library released at 2 years ago.
>
>Having said all that, everything I removed from my quote I found agreeable.  Very
>well written.

I am concerned about setting a specific limit here. The reason is that, as a platform/community maintainer:
1.  I do not control the library versions that are available - in most cases
2. I do not control the available toolchain - in all cases
3. Support is required for all OS releases dating back 5 years from the close of sales - this is not actually a huge problem except for #1 and #2. However, it does not serious constraints on what toolchains are available. Most of what we do is use static linkage to avoid a lot of compatibility issues, other than OpenSSL that has to be flexible based on the rate of CVEs raised and solved.
4. Porting some new tools (e.g., GO, Rust, gcc, libc, glibc), is usually impossible no matter what my skill level based on platform prohibitions.

I'm sorry to have to complain about this, but it is a reality of exotic, non-linux, platforms that are still being maintained and active (the last major NonStop OS release was 11 months ago, and another is due to drop imminently, so this is not a dead or dying platform). The last thing I want to have is having users locked out of future git versions, based on the increasing adoption of git on NonStop that has been (immodestly said) mostly my fault. Can we solve this in some acceptable way?

Sincerely,
Randall

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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1092 bytes --]

On Thu, Jul 18, 2024 at 10:38:43AM -0700, Emily Shaffer wrote:
> +* If you rely on Git avoiding a specific pattern that doesn't work well with
> +  your platform (like a certain malloc pattern), raise it on the mailing list.
> +  There are a few ways to avoid these breakages, so we'll work case-by-case to
> +  find a solution that doesn't unnecessarily constrain other platforms to keep
> +  compatibility with yours.

I found the latter part of this bullet point a bit weird. We don't yet
know about the specific pattern that may fail on any future supported
platform, so claiming that there are ways to avoid them goes a bit too
far, no?

> +** Include a comment with an expiration date for these tests no more than 1 year
> +   from now. You can update the expiration date if your platform still needs
> +   that assurance down the road, but we need to know you still care about that
> +   compatibility case and are working to make it unnecessary.

Do we maybe want to replace "from now" with "from when you add them"?

Other than that this document looks great to me, thanks!

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Josh Steadmon]

On 2024.07.18 10:38, Emily Shaffer wrote:
> Supporting many platforms is only easy when we have the right tools to
> ensure that support.
> 
> Teach platform maintainers how they can help us to help them, by
> explaining what kind of tooling support we would like to have, and what
> level of support becomes available as a result. Provide examples so that
> platform maintainers can see what we're asking for in practice.
> 
> With this policy in place, we can make changes with stronger assurance
> that we are not breaking anybody we promised not to. Instead, we can
> feel confident that our existing testing and integration practices
> protect those who care from breakage.
> 
> Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
> 
> ---
> 
> New in v3:
> 
> - Made language to platform maintainers a little clearer (hopefully)
>   about this allowing us to provide more predictable support levels.
> 
> - Clarified that this covers maintaining previous functionality, not
>   adding support for something new.
> 
> - Made the bullet point formatting a little less eye-bleedy.
> 
> - Asked reporters to make sure that bugs are really a platform
>   compatibility bug, and not a regular bug.
> 
> - Rephrased section intros to emphasize what the platform maintainer
>   gets, rather than emphasize the Git project patch lifecycle.
> 
> - Clarified alternatives to GitHub Actions CI: GitLab or list scraping.
>   Made some notes about avoiding noise.
> 
> - Small fixes to formatting, spacing, etc
> 
> Thanks,
> 
>  - Emily
> 
> v1 description at
> https://lore.kernel.org/git/20240709225042.2005233-1-emilyshaffer@google.com/
> ---
>  Documentation/Makefile                       |   1 +
>  Documentation/technical/platform-support.txt | 177 +++++++++++++++++++
>  2 files changed, 178 insertions(+)
>  create mode 100644 Documentation/technical/platform-support.txt
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index dc65759cb1..462af0311f 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -118,6 +118,7 @@ TECH_DOCS += technical/multi-pack-index
>  TECH_DOCS += technical/pack-heuristics
>  TECH_DOCS += technical/parallel-checkout
>  TECH_DOCS += technical/partial-clone
> +TECH_DOCS += technical/platform-support
>  TECH_DOCS += technical/racy-git
>  TECH_DOCS += technical/reftable
>  TECH_DOCS += technical/scalar
> diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt
> new file mode 100644
> index 0000000000..981997e635
> --- /dev/null
> +++ b/Documentation/technical/platform-support.txt
> @@ -0,0 +1,177 @@
> +Platform Support Policy
> +=======================
> +
> +Git has a history of providing broad "support" for exotic platforms and older
> +platforms, without an explicit commitment. Stakeholders of these platforms may
> +want a more predictable support commitment. This is only possible when platform
> +stakeholders supply Git developers with adequate tooling, so we can test for
> +compatibility or develop workarounds for platform-specific quirks on our own.
> +Various levels of tooling will allow us to make more solid commitments around
> +Git's compatibility with your platform.
> +
> +Note that this document is about maintaining existing support for a platform
> +that has generally worked in the past; for adding support to a platform which
> +doesn't generally work with Git, the stakeholders for that platform are expected
> +to do the bulk of that work themselves. We will consider such patches if they
> +don't make life harder for other supported platforms, and you may well find a
> +contributor interested in working on that support, but the Git community as a
> +whole doesn't feel an obligation to perform such work.
> +
> +Compatible by next release
> +--------------------------
> +
> +To increase probability that compatibility issues introduced in a release
> +will be fixed in a later release:
> +
> +* You should send a bug report as soon as you notice the breakage on your
> +  platform. The sooner you notice, the better; watching `seen` means you can
> +  notice problems before they are considered "done with review"; whereas
> +  watching `master` means the stable branch could break for your platform, but
> +  you have a decent chance of avoiding a tagged release breaking you. See "The
> +  Policy" in the link:../howto/maintain-git.txt[maintainer's guide] for an
> +  overview of which branches are used in git.git, and how.
> +
> +* The bug report should include information about what platform you are using.
> +
> +* You should also use linkgit:git-bisect[1] and determine which commit
> +  introduced the breakage.
> +
> +* Please include any information you have about the nature of the breakage: is
> +  it a memory alignment issue? Is an underlying library missing or broken for
> +  your platform? Is there some quirk about your platform which means typical
> +  practices (like malloc) behave strangely?
> +
> +** If possible, build Git from the exact same source both for your platform and
> +   for a maintstream platform, and make sure the problem you noticed appears

Typo: "maintstream"


> +   only on your platform. If the problem appears in both, then it's not a
> +   compatibility issue, but we of course appreciate hearing about it in a bug
> +   report anyway, to benefit users of every platform.
> +
> +* Once we begin to fix the issue, please work closely with the contributor
> +  working on it to test the proposed fix against your platform.
> +
> +Example: NonStop
> +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports
> +problems] when they're noticed.
> +
> +Compatible on `master` and releases
> +-----------------------------------------
> +
> +To make sure all stable builds and regular releases work for your platform the
> +first time, you can make sure `master` doesn't break for your platform:
> +
> +* You should run nightly tests against the `next` branch and publish breakage
> +  reports to the mailing list immediately when they happen.
> +
> +** You may want to ask to join the mailto:git-security@googlegroups.com[security
> +   mailing list] in order to run tests against the fixes proposed there, too.
> +
> +* It may make sense to automate these; if you do, make sure they are not noisy
> +  (you don't need to send a report when everything works, only when something
> +  breaks; you don't need to send repeated reports for the same breakage night
> +  after night).
> +
> +* Breakage reports should be actionable - include clear error messages that can
> +  help developers who may not have access to test directly on your platform.
> +
> +* You should use git-bisect and determine which commit introduced the breakage;
> +  if you can't do this with automation, you should do this yourself manually as
> +  soon as you notice a breakage report was sent.
> +
> +* You should either:
> +
> +** Provide VM access on-demand to a trusted developer working to fix the issue,
> +   so they can test their fix, OR
> +
> +** Work closely with the developer fixing the issue; the turnaround to check
> +   that their proposed fix works for your platform should be fast enough that it
> +   doesn't hinder the developer working on that fix. Slow testing turnarounds
> +   may cause the fix to miss the next release, or the developer may lose
> +   interest in working on the fix at all.
> +
> +Example:
> +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/[AIX]
> +provides a build farm and runs tests against release candidates.
> +
> +Compatible on `next`
> +--------------------
> +
> +To avoid reactive debugging and fixing when changes hit a release or stable, you
> +can aim to ensure `next` works for your platform. (See "The Policy" in the
> +link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next`
> +is used in the Git project.) To do that:
> +
> +* You should add a runner for your platform to the GitHub Actions or GitLab CI
> +  suite.  This suite is run when any Git developer proposes a new patch, and
> +  having a runner for your platform/configuration means every developer will
> +  know if they break you, immediately.
> +
> +** If adding it to an existing CI suite is infeasible (due to architecture
> +   constraints or for performance reasons), any other method which runs as
> +   automatically and quickly as possible works, too. For example, a service
> +   which snoops on the mailing list and automatically runs tests on new [PATCH]
> +   emails, replying to the author with the results, would also be within the
> +   spirit of this requirement.
> +
> +* If you rely on Git avoiding a specific pattern that doesn't work well with
> +  your platform (like a certain malloc pattern), raise it on the mailing list.
> +  There are a few ways to avoid these breakages, so we'll work case-by-case to
> +  find a solution that doesn't unnecessarily constrain other platforms to keep
> +  compatibility with yours.
> +
> +* If you rely on some configuration or behavior, add a test for it. Untested
> +  behavior is subject to breakage at any time.
> +
> +** Clearly label these tests as necessary for platform compatibility. Add them
> +   to an isolated compatibility-related test suite, like a new t* file or unit
> +   test suite, so that they're easy to remove when compatibility is no longer
> +   required.  If the specific compatibility need is gated behind an issue with
> +   another project, link to documentation of that issue (like a bug or email
> +   thread) to make it easier to tell when that compatibility need goes away.
> +
> +** Include a comment with an expiration date for these tests no more than 1 year
> +   from now. You can update the expiration date if your platform still needs
> +   that assurance down the road, but we need to know you still care about that
> +   compatibility case and are working to make it unnecessary.
> +
> +Example: We run our
> +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI
> +suite] on Windows, Ubuntu, Mac, and others.
> +
> +Getting help writing platform support patches
> +---------------------------------------------
> +
> +In general, when sending patches to fix platform support problems, follow
> +these guidelines to make sure the patch is reviewed with the appropriate level
> +of urgency:
> +
> +* Clearly state in the commit message that you are fixing a platform breakage,
> +  and for which platform.
> +
> +* Use the CI and test suite to ensure that the fix for your platform doesn't
> +  break other platforms.
> +
> +* If possible, add a test ensuring this regression doesn't happen again. If
> +  it's not possible to add a test, explain why in the commit message.
> +
> +Minimum Requirements
> +--------------------

It might make more sense to move this section immediately after the
introduction. I don't feel too strongly about it though.


> +Even if platform maintainers are willing to add tests or CI runners, we will
> +not consider helping to support platforms that do not meet these minimum
> +requirements:
> +
> +* Has C99 or C11
> +
> +* Has dependencies which were released in the past 10 years
> +
> +* Has active security support (taking security releases of dependencies, etc)
> +
> +Platform Maintainers
> +--------------------
> +
> +If you maintain a platform, or Git for that platform, and intend to work with
> +the Git project to ensure compatibility, please send a patch to add yourself to
> +this list.
> +
> +NonStop: Randall S. Becker <rsbecker@nexbridge.com>


Overall, looks good to me, thanks!

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

[Emily Shaffer]

On Thu, Jul 18, 2024 at 4:45 PM <rsbecker@nexbridge.com> wrote:
>
> On Thursday, July 18, 2024 6:46 PM, Junio C Hamano wrote:
> >Emily Shaffer <emilyshaffer@google.com> writes:
> >
> >> Supporting many platforms is only easy when we have the right tools to
> >> ensure that support.
> >
> >"easy" -> "possible".
> >
> >> +Compatible by next release
> >> +--------------------------
> >> +
> >> +To increase probability that compatibility issues introduced in a
> >> +release will be fixed in a later release:
> >> +
> >> +* You should send a bug report as soon as you notice the breakage on
> >> +your
> >> +  platform. The sooner you notice, the better; watching `seen` means
> >> +you can
> >> +  notice problems before they are considered "done with review";
> >> +whereas
> >> +  watching `master` means the stable branch could break for your
> >> +platform, but
> >> +  you have a decent chance of avoiding a tagged release breaking you.
> >> +See "The
> >> +  Policy" in the link:../howto/maintain-git.txt[maintainer's guide]
> >> +for an
> >
> >Running
> >
> >    $ make -C Documentation howto/maintain-git.html
> >    $ lynx Documentation/howto/maintain-git.html
> >
> >tells me that the title of the document is "How to maintain Git".
> >
> >> +  overview of which branches are used in git.git, and how.
> >
> >"git.git" -> "the Git project"
> >
> >> +Compatible on `master` and releases
> >> +-----------------------------------------
> >
> >Underline that signals what level the header is is drawn to the same column as the
> >header title itself, or you'd confuse the formatter.
> >
> >
> >> +To make sure all stable builds and regular releases work for your
> >> +platform the first time, you can make sure `master` doesn't break for your
> >platform:
> >
> >"can" -> "want to"?
> >
> >But "to make sure X, you can make sure Y" feels a bit awkward.
> >
> >    To make sure ... work for your platform, help us avoid breaking the
> >    tip of `master` by merging topics that break your platform.
> >
> >> +* You should run nightly tests against the `next` branch and publish
> >> +breakage
> >> +  reports to the mailing list immediately when they happen.
> >
> >Can't it be daily instead of nightly ;-), or is it better than nothing if you can afford to
> >run only once every other day?
> >
> >A topic (unless it is during the shuffle time around -rc0) usually spends no less than
> >7 calendar days in 'next', so while I would appreciate if somebody runs tests twice a
> >day, in practice you should be able to catch a new breakage in 'next' if you run a full
> >and thorough test twice a week.
> >
> >> +* You should either:
> >> +
> >> +** Provide VM access on-demand to a trusted developer working to fix the issue,
> >> +   so they can test their fix, OR
> >
> >"VM access on-demand" -> "on-demand access to your platform" (iow, physical
> >iron is also fine for our purpose).
> >
> >> +Compatible on `next`
> >> +--------------------
> >> +
> >> +To avoid reactive debugging and fixing when changes hit a release or
> >> +stable, you can aim to ensure `next` works for your platform. (See
> >> +"The Policy" in the link:../howto/maintain-git.txt[maintainer's
> >> +guide] for an overview of how `next` is used in the Git project.) To do that:
> >> +
> >> +* You should add a runner for your platform to the GitHub Actions or
> >> +GitLab CI
> >> +  suite.  This suite is run when any Git developer proposes a new
> >> +patch, and
> >> +  having a runner for your platform/configuration means every
> >> +developer will
> >> +  know if they break you, immediately.
> >> +
> >> +** If adding it to an existing CI suite is infeasible (due to architecture
> >> +   constraints or for performance reasons), any other method which runs as
> >> +   automatically and quickly as possible works, too. For example, a service
> >> +   which snoops on the mailing list and automatically runs tests on new [PATCH]
> >> +   emails, replying to the author with the results, would also be within the
> >> +   spirit of this requirement.
> >
> >It would be very nice if they did this, indeed.  Explaining that something that
> >mechanically looks vastly different is within the spirit is a very good move.
> >
> >> +Minimum Requirements
> >> +--------------------
> >> +
> >> +Even if platform maintainers are willing to add tests or CI runners,
> >> +we will not consider helping to support platforms that do not meet
> >> +these minimum
> >> +requirements:
> >> +
> >> +* Has C99 or C11
> >
> >OK.
> >
> >> +* Has dependencies which were released in the past 10 years
> >
> >This is hard to understand and I wonder if we can clarify.  I get what you want to
> >say: suppose we rely on library X that is getting regular feature and security updates
> >in reasonable cadence, say every 6 months there is an upstream release of library X,
> >but a niche platform has ported the library only once long time ago, and hasn't
> >updated it ever since.  Now the Git project may consider helping a port to such a
> >platform if the initial port of library X was 8 years ago, but will not if it was 12 years
> >ago.
> >
> >But if Git depends on an ultra stable library whose last public release was 12 years
> >ago, disqualify everybody is not what this requirement wants to do.
> >
> >I attempted to formulate my version along ...
> >
> >    Keep up with the versions of dependencies (libraries, etc.) and
> >    not to lag behind compared to typical mainstream platforms by
> >    more than X years.
> >
> >... the above line, but to me it is no better than the original, so I failed miserably.  But
> >the idea I am bringing to the table here is that time of release is not absolute.  If
> >typical mainstream platforms consider a release of a library made 8 years ago from
> >the upstream performant, functional, and secure enough and fit for use, we do not
> >consider that they are approaching the limit.  But if another platform uses the same
> >library from 12 years ago, i.e.
> >lagging behind others by 4 years is a problem at the same graveness using another
> >library that was released 6 years ago, when other platforms are using a much
> >younger vintage of the same library released at 2 years ago.
> >
> >Having said all that, everything I removed from my quote I found agreeable.  Very
> >well written.
>
> I am concerned about setting a specific limit here. The reason is that, as a platform/community maintainer:
> 1.  I do not control the library versions that are available - in most cases
> 2. I do not control the available toolchain - in all cases
> 3. Support is required for all OS releases dating back 5 years from the close of sales - this is not actually a huge problem except for #1 and #2. However, it does not serious constraints on what toolchains are available. Most of what we do is use static linkage to avoid a lot of compatibility issues, other than OpenSSL that has to be flexible based on the rate of CVEs raised and solved.
> 4. Porting some new tools (e.g., GO, Rust, gcc, libc, glibc), is usually impossible no matter what my skill level based on platform prohibitions.

I actually think what level of control the platform maintainer has is
beside the point.

The intent of this line in the doc is to say: even if there is an
active maintainer and there are active users, Git developers need to
be able to use relatively modern tooling to be able to keep Git
healthy and evolving. The more Git development is locked into past
tooling, the less it can keep up with the needs of most of the
industry, and the higher the risk comes of Git being abandoned because
the cost to overhaul it to meet industry needs is too high. So, if a
platform isn't compatible with those reasonably modern tools (and I do
think "a C compiler that's less than 10 years out-of-date" is really
stretching the meaning of "modern"), sorry, but it's not workable for
us.

That is, it's not about whether the maintainer is virtuous and doing
everything in their power; it's about whether the platform itself is
feasible to support and whether the abilities of the platform line up
with the Git project's needs to make forward progress and keep up with
the times.

Whether or not that paraphrasal is something the rest of the Git
community agrees with, though, is the whole reason I sent this doc up
for review ;) So far I haven't seen any other disagreement than this
mail, but we also haven't gotten a ton of reviews on this patch, less
than half a dozen individuals. (By the way, "others may find Git too
far gone and build something new instead" is actually already
happening[1][2], including at Google.)

> I'm sorry to have to complain about this, but it is a reality of exotic, non-linux, platforms that are still being maintained and active (the last major NonStop OS release was 11 months ago, and another is due to drop imminently, so this is not a dead or dying platform). The last thing I want to have is having users locked out of future git versions, based on the increasing adoption of git on NonStop that has been (immodestly said) mostly my fault. Can we solve this in some acceptable way?

As it stands, we currently don't have any tooling available to make
sure that changes we make work on NonStop, anyway - we basically need
to take your word for it when something breaks, and that's quite
difficult for the contributor base to cater to. So even if we were to
relax the minimum requirement bits here, we'd have difficulty
supporting NonStop in the capacity that you sound interested in. Do
you have any suggestions to make NonStop easier to support in that
regard?

I wonder if it is better worth explaining what maintenance branch
support users can expect - how long a given version will receive
security patches, what kind of backporting work platform maintainers
could reasonably do, and so on. Thoughts?

 - Emily

1: https://github.com/martinvonz/jj
2: https://sapling-scm.com/

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

[Emily Shaffer]

On Thu, Jul 18, 2024 at 3:46 PM Junio C Hamano <gitster@pobox.com> wrote:

[..snipped nits, I have fixed them for v4]

> > +* You should run nightly tests against the `next` branch and publish breakage
> > +  reports to the mailing list immediately when they happen.
>
> Can't it be daily instead of nightly ;-), or is it better than
> nothing if you can afford to run only once every other day?
>
> A topic (unless it is during the shuffle time around -rc0) usually
> spends no less than 7 calendar days in 'next', so while I would
> appreciate if somebody runs tests twice a day, in practice you
> should be able to catch a new breakage in 'next' if you run a full
> and thorough test twice a week.

I ended up adding a sub-point to explain cadence preference and
reasoning, since that's a lot to fit into a parenthetical. Thanks.

>
> > +* You should either:
> > +
> > +** Provide VM access on-demand to a trusted developer working to fix the issue,
> > +   so they can test their fix, OR
>
> "VM access on-demand" -> "on-demand access to your platform" (iow,
> physical iron is also fine for our purpose).

Done, thanks.

> > +Minimum Requirements
> > +--------------------
> > +
> > +Even if platform maintainers are willing to add tests or CI runners, we will
> > +not consider helping to support platforms that do not meet these minimum
> > +requirements:
> > +
> > +* Has C99 or C11
>
> OK.
>
> > +* Has dependencies which were released in the past 10 years
>
> This is hard to understand and I wonder if we can clarify.  I get
> what you want to say: suppose we rely on library X that is getting
> regular feature and security updates in reasonable cadence, say
> every 6 months there is an upstream release of library X, but a
> niche platform has ported the library only once long time ago, and
> hasn't updated it ever since.  Now the Git project may consider
> helping a port to such a platform if the initial port of library X
> was 8 years ago, but will not if it was 12 years ago.
>
> But if Git depends on an ultra stable library whose last public
> release was 12 years ago, disqualify everybody is not what this
> requirement wants to do.
>
> I attempted to formulate my version along ...
>
>     Keep up with the versions of dependencies (libraries, etc.) and
>     not to lag behind compared to typical mainstream platforms by
>     more than X years.
>
> ... the above line, but to me it is no better than the original, so
> I failed miserably.  But the idea I am bringing to the table here is
> that time of release is not absolute.  If typical mainstream
> platforms consider a release of a library made 8 years ago from the
> upstream performant, functional, and secure enough and fit for use,
> we do not consider that they are approaching the limit.  But if
> another platform uses the same library from 12 years ago, i.e.
> lagging behind others by 4 years is a problem at the same graveness
> using another library that was released 6 years ago, when other
> platforms are using a much younger vintage of the same library
> released at 2 years ago.

Yeah, I think it makes sense to relax just a little bit more, and give
ourselves flexibility to use common sense. I ended up with:

"""
* Uses versions of dependencies which are generally accepted as stable
and
  supportable, e.g., in line with the version used by other
long-term-support
  distributions
"""

It's not quite my favorite, still, because I guess that LTS distros
could get to a point we don't want to support (do we really want to
provide cutting-edge git features to a 25-year-old LTS distro, for
example?). Plus, "just look at everyone else's homework and use that"
feels a little weird.

Will keep thinking on this, I'd welcome other suggestions for phrasing.

>
> Having said all that, everything I removed from my quote I found
> agreeable.  Very well written.

Thanks. :)

 - Emily

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

[Junio C Hamano]

Emily Shaffer <nasamuffin@google.com> writes:

> It's not quite my favorite, still, because I guess that LTS distros
> could get to a point we don't want to support (do we really want to
> provide cutting-edge git features to a 25-year-old LTS distro, for
> example?). Plus, "just look at everyone else's homework and use that"
> feels a little weird.

But essentially that is what we end up doing anyway, no?  If a
platform is used heavily by some of us, they get more attention
because we would be the first to notice breakage on it.  Like it or
not, the population distribution of development community members on
different platforms would not align with the population distribution
of general public, but without access to and familiarlity with the
platform, and without motivation and time we can spend on it, none
of us would feel compelled to look into an issue that only surfaces
on an unfamiliar platform.  So it is inevitable that "you'd have
better chance of being helped by us if you make it as similar to
platforms that we are familiar with as you can" holds true.

> Will keep thinking on this, I'd welcome other suggestions for phrasing.

Likewise here.

RE: [PATCH v3] Documentation: add platform support policy

[rsbecker]

On Thursday, July 25, 2024 2:53 PM, Emily Shaffer wrote:
>On Thu, Jul 18, 2024 at 3:46 PM Junio C Hamano <gitster@pobox.com> wrote:
>
>[..snipped nits, I have fixed them for v4]
>
>> > +* You should run nightly tests against the `next` branch and
>> > +publish breakage
>> > +  reports to the mailing list immediately when they happen.
>>
>> Can't it be daily instead of nightly ;-), or is it better than nothing
>> if you can afford to run only once every other day?
>>
>> A topic (unless it is during the shuffle time around -rc0) usually
>> spends no less than 7 calendar days in 'next', so while I would
>> appreciate if somebody runs tests twice a day, in practice you should
>> be able to catch a new breakage in 'next' if you run a full and
>> thorough test twice a week.
>
>I ended up adding a sub-point to explain cadence preference and reasoning, since
>that's a lot to fit into a parenthetical. Thanks.
>
>>
>> > +* You should either:
>> > +
>> > +** Provide VM access on-demand to a trusted developer working to fix the
>issue,
>> > +   so they can test their fix, OR
>>
>> "VM access on-demand" -> "on-demand access to your platform" (iow,
>> physical iron is also fine for our purpose).
>
>Done, thanks.
>
>> > +Minimum Requirements
>> > +--------------------
>> > +
>> > +Even if platform maintainers are willing to add tests or CI
>> > +runners, we will not consider helping to support platforms that do
>> > +not meet these minimum
>> > +requirements:
>> > +
>> > +* Has C99 or C11
>>
>> OK.
>>
>> > +* Has dependencies which were released in the past 10 years
>>
>> This is hard to understand and I wonder if we can clarify.  I get what
>> you want to say: suppose we rely on library X that is getting regular
>> feature and security updates in reasonable cadence, say every 6 months
>> there is an upstream release of library X, but a niche platform has
>> ported the library only once long time ago, and hasn't updated it ever
>> since.  Now the Git project may consider helping a port to such a
>> platform if the initial port of library X was 8 years ago, but will
>> not if it was 12 years ago.
>>
>> But if Git depends on an ultra stable library whose last public
>> release was 12 years ago, disqualify everybody is not what this
>> requirement wants to do.
>>
>> I attempted to formulate my version along ...
>>
>>     Keep up with the versions of dependencies (libraries, etc.) and
>>     not to lag behind compared to typical mainstream platforms by
>>     more than X years.
>>
>> ... the above line, but to me it is no better than the original, so I
>> failed miserably.  But the idea I am bringing to the table here is
>> that time of release is not absolute.  If typical mainstream platforms
>> consider a release of a library made 8 years ago from the upstream
>> performant, functional, and secure enough and fit for use, we do not
>> consider that they are approaching the limit.  But if another platform
>> uses the same library from 12 years ago, i.e.
>> lagging behind others by 4 years is a problem at the same graveness
>> using another library that was released 6 years ago, when other
>> platforms are using a much younger vintage of the same library
>> released at 2 years ago.
>
>Yeah, I think it makes sense to relax just a little bit more, and give ourselves flexibility
>to use common sense. I ended up with:
>
>"""
>* Uses versions of dependencies which are generally accepted as stable and
>  supportable, e.g., in line with the version used by other long-term-support
>  distributions
>"""
>
>It's not quite my favorite, still, because I guess that LTS distros could get to a point
>we don't want to support (do we really want to provide cutting-edge git features to
>a 25-year-old LTS distro, for example?). Plus, "just look at everyone else's
>homework and use that"
>feels a little weird.

A common practice across many commercial and Open Source projects is to fix LTS at a 5 year limit and usually for
High-CVE class security fixes. That is, at least, when there is a commitment to retroactively fix problems. The
Impression (from the outside of git - until about a year ago when "friends" fixes where done) is that the way to get
a git fix is to upgrade. Somewhere in the middle would be more appropriate, I think. I do not think 25 year LTS
is common, useful, or even likely, even for exotics (we use 5 year since a fixed announcement of a "closed selling
date"). We could designate 2.46 as LTS 5 years from next week, as an example, which might not be so terrible. But
LTS tends to be for qualified fixes only, like CVEs at a certain level, with functional stability (no enhancements
allowed after a specific date - say "official release + 1 year"). OpenSSL is a bit more stringent, where once an LTS
designated release moves past beta, there are no functional changes allowed, just bug fixes, and about a year later,
just security fixes. When establishing an LTS, my core requirement is that I have a compatible supported
compiler, not just a compiler available. For example, the minimum OS I support is 7 years old - 2 during active
sales + 5 years after, which aligns with the vendor's OS policy. This also means that I might use c99, but only a
fully supported c99+toolchain, not just one that is available that might run on the box. This means that any
shipped binaries are not guaranteed to run on any OS version that is no longer supported, including the
compilers on that version - probably more rigid than git would need though. May 2024 was a big month
because a bunch of things were deprecated/dropped. This type of policy does take active product
management, which, in gits case, would need volunteers who actively watch conditions on relevant platforms - I
do that for the git builds on NonStop, so my team stops building git versions for dropped OS releases.
My only issue there is cleaning up "dead" versions so people cannot download git builds that we are pretty
sure will no longer run (there are complex reasons it is a difficult activity).

... but I have gone on too long, but LTS is a very heavy-weighted term with generally stringent rules. The above
was really just context for decision-making around LTS, not specific comments about the content. Sorry.

>Will keep thinking on this, I'd welcome other suggestions for phrasing.
>
>>
>> Having said all that, everything I removed from my quote I found
>> agreeable.  Very well written.

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

[Emily Shaffer]

On Tue, Jul 23, 2024 at 2:02 AM Patrick Steinhardt <ps@pks.im> wrote:
>
> On Thu, Jul 18, 2024 at 10:38:43AM -0700, Emily Shaffer wrote:
> > +* If you rely on Git avoiding a specific pattern that doesn't work well with
> > +  your platform (like a certain malloc pattern), raise it on the mailing list.
> > +  There are a few ways to avoid these breakages, so we'll work case-by-case to
> > +  find a solution that doesn't unnecessarily constrain other platforms to keep
> > +  compatibility with yours.
>
> I found the latter part of this bullet point a bit weird. We don't yet
> know about the specific pattern that may fail on any future supported
> platform, so claiming that there are ways to avoid them goes a bit too
> far, no?

I guess I had in mind "some entry in contrib/ that happens at compile
time" or "some preprocessor define hack that happens at compile time"
or "???", which is where I got "a few" from. I can drop it, it is
wordy and "we want to work with you to find something that doesn't
suck for everyone" is the important part. Thanks.

>
> > +** Include a comment with an expiration date for these tests no more than 1 year
> > +   from now. You can update the expiration date if your platform still needs
> > +   that assurance down the road, but we need to know you still care about that
> > +   compatibility case and are working to make it unnecessary.
>
> Do we maybe want to replace "from now" with "from when you add them"?

Sure, thanks.

>
> Other than that this document looks great to me, thanks!

Thanks for the review.

 - Emily

>
> Patrick

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

[Emily Shaffer]

On Tue, Jul 23, 2024 at 2:49 PM Josh Steadmon <steadmon@google.com> wrote:
>
> On 2024.07.18 10:38, Emily Shaffer wrote:
> > Supporting many platforms is only easy when we have the right tools to
> > ensure that support.
> >
> > Teach platform maintainers how they can help us to help them, by
> > explaining what kind of tooling support we would like to have, and what
> > level of support becomes available as a result. Provide examples so that
> > platform maintainers can see what we're asking for in practice.
> >
> > With this policy in place, we can make changes with stronger assurance
> > that we are not breaking anybody we promised not to. Instead, we can
> > feel confident that our existing testing and integration practices
> > protect those who care from breakage.
> >
> > Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
> >
> > ---
> >
> > New in v3:
> >
> > - Made language to platform maintainers a little clearer (hopefully)
> >   about this allowing us to provide more predictable support levels.
> >
> > - Clarified that this covers maintaining previous functionality, not
> >   adding support for something new.
> >
> > - Made the bullet point formatting a little less eye-bleedy.
> >
> > - Asked reporters to make sure that bugs are really a platform
> >   compatibility bug, and not a regular bug.
> >
> > - Rephrased section intros to emphasize what the platform maintainer
> >   gets, rather than emphasize the Git project patch lifecycle.
> >
> > - Clarified alternatives to GitHub Actions CI: GitLab or list scraping.
> >   Made some notes about avoiding noise.
> >
> > - Small fixes to formatting, spacing, etc
> >
> > Thanks,
> >
> >  - Emily
> >
> > v1 description at
> > https://lore.kernel.org/git/20240709225042.2005233-1-emilyshaffer@google.com/
> > ---
> >  Documentation/Makefile                       |   1 +
> >  Documentation/technical/platform-support.txt | 177 +++++++++++++++++++
> >  2 files changed, 178 insertions(+)
> >  create mode 100644 Documentation/technical/platform-support.txt
> >
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index dc65759cb1..462af0311f 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -118,6 +118,7 @@ TECH_DOCS += technical/multi-pack-index
> >  TECH_DOCS += technical/pack-heuristics
> >  TECH_DOCS += technical/parallel-checkout
> >  TECH_DOCS += technical/partial-clone
> > +TECH_DOCS += technical/platform-support
> >  TECH_DOCS += technical/racy-git
> >  TECH_DOCS += technical/reftable
> >  TECH_DOCS += technical/scalar
> > diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt
> > new file mode 100644
> > index 0000000000..981997e635
> > --- /dev/null
> > +++ b/Documentation/technical/platform-support.txt
> > @@ -0,0 +1,177 @@
> > +Platform Support Policy
> > +=======================
> > +
> > +Git has a history of providing broad "support" for exotic platforms and older
> > +platforms, without an explicit commitment. Stakeholders of these platforms may
> > +want a more predictable support commitment. This is only possible when platform
> > +stakeholders supply Git developers with adequate tooling, so we can test for
> > +compatibility or develop workarounds for platform-specific quirks on our own.
> > +Various levels of tooling will allow us to make more solid commitments around
> > +Git's compatibility with your platform.
> > +
> > +Note that this document is about maintaining existing support for a platform
> > +that has generally worked in the past; for adding support to a platform which
> > +doesn't generally work with Git, the stakeholders for that platform are expected
> > +to do the bulk of that work themselves. We will consider such patches if they
> > +don't make life harder for other supported platforms, and you may well find a
> > +contributor interested in working on that support, but the Git community as a
> > +whole doesn't feel an obligation to perform such work.
> > +
> > +Compatible by next release
> > +--------------------------
> > +
> > +To increase probability that compatibility issues introduced in a release
> > +will be fixed in a later release:
> > +
> > +* You should send a bug report as soon as you notice the breakage on your
> > +  platform. The sooner you notice, the better; watching `seen` means you can
> > +  notice problems before they are considered "done with review"; whereas
> > +  watching `master` means the stable branch could break for your platform, but
> > +  you have a decent chance of avoiding a tagged release breaking you. See "The
> > +  Policy" in the link:../howto/maintain-git.txt[maintainer's guide] for an
> > +  overview of which branches are used in git.git, and how.
> > +
> > +* The bug report should include information about what platform you are using.
> > +
> > +* You should also use linkgit:git-bisect[1] and determine which commit
> > +  introduced the breakage.
> > +
> > +* Please include any information you have about the nature of the breakage: is
> > +  it a memory alignment issue? Is an underlying library missing or broken for
> > +  your platform? Is there some quirk about your platform which means typical
> > +  practices (like malloc) behave strangely?
> > +
> > +** If possible, build Git from the exact same source both for your platform and
> > +   for a maintstream platform, and make sure the problem you noticed appears
>
> Typo: "maintstream"

Oop, thanks :)

>
>
> > +   only on your platform. If the problem appears in both, then it's not a
> > +   compatibility issue, but we of course appreciate hearing about it in a bug
> > +   report anyway, to benefit users of every platform.
> > +
> > +* Once we begin to fix the issue, please work closely with the contributor
> > +  working on it to test the proposed fix against your platform.
> > +
> > +Example: NonStop
> > +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports
> > +problems] when they're noticed.
> > +
> > +Compatible on `master` and releases
> > +-----------------------------------------
> > +
> > +To make sure all stable builds and regular releases work for your platform the
> > +first time, you can make sure `master` doesn't break for your platform:
> > +
> > +* You should run nightly tests against the `next` branch and publish breakage
> > +  reports to the mailing list immediately when they happen.
> > +
> > +** You may want to ask to join the mailto:git-security@googlegroups.com[security
> > +   mailing list] in order to run tests against the fixes proposed there, too.
> > +
> > +* It may make sense to automate these; if you do, make sure they are not noisy
> > +  (you don't need to send a report when everything works, only when something
> > +  breaks; you don't need to send repeated reports for the same breakage night
> > +  after night).
> > +
> > +* Breakage reports should be actionable - include clear error messages that can
> > +  help developers who may not have access to test directly on your platform.
> > +
> > +* You should use git-bisect and determine which commit introduced the breakage;
> > +  if you can't do this with automation, you should do this yourself manually as
> > +  soon as you notice a breakage report was sent.
> > +
> > +* You should either:
> > +
> > +** Provide VM access on-demand to a trusted developer working to fix the issue,
> > +   so they can test their fix, OR
> > +
> > +** Work closely with the developer fixing the issue; the turnaround to check
> > +   that their proposed fix works for your platform should be fast enough that it
> > +   doesn't hinder the developer working on that fix. Slow testing turnarounds
> > +   may cause the fix to miss the next release, or the developer may lose
> > +   interest in working on the fix at all.
> > +
> > +Example:
> > +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/[AIX]
> > +provides a build farm and runs tests against release candidates.
> > +
> > +Compatible on `next`
> > +--------------------
> > +
> > +To avoid reactive debugging and fixing when changes hit a release or stable, you
> > +can aim to ensure `next` works for your platform. (See "The Policy" in the
> > +link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next`
> > +is used in the Git project.) To do that:
> > +
> > +* You should add a runner for your platform to the GitHub Actions or GitLab CI
> > +  suite.  This suite is run when any Git developer proposes a new patch, and
> > +  having a runner for your platform/configuration means every developer will
> > +  know if they break you, immediately.
> > +
> > +** If adding it to an existing CI suite is infeasible (due to architecture
> > +   constraints or for performance reasons), any other method which runs as
> > +   automatically and quickly as possible works, too. For example, a service
> > +   which snoops on the mailing list and automatically runs tests on new [PATCH]
> > +   emails, replying to the author with the results, would also be within the
> > +   spirit of this requirement.
> > +
> > +* If you rely on Git avoiding a specific pattern that doesn't work well with
> > +  your platform (like a certain malloc pattern), raise it on the mailing list.
> > +  There are a few ways to avoid these breakages, so we'll work case-by-case to
> > +  find a solution that doesn't unnecessarily constrain other platforms to keep
> > +  compatibility with yours.
> > +
> > +* If you rely on some configuration or behavior, add a test for it. Untested
> > +  behavior is subject to breakage at any time.
> > +
> > +** Clearly label these tests as necessary for platform compatibility. Add them
> > +   to an isolated compatibility-related test suite, like a new t* file or unit
> > +   test suite, so that they're easy to remove when compatibility is no longer
> > +   required.  If the specific compatibility need is gated behind an issue with
> > +   another project, link to documentation of that issue (like a bug or email
> > +   thread) to make it easier to tell when that compatibility need goes away.
> > +
> > +** Include a comment with an expiration date for these tests no more than 1 year
> > +   from now. You can update the expiration date if your platform still needs
> > +   that assurance down the road, but we need to know you still care about that
> > +   compatibility case and are working to make it unnecessary.
> > +
> > +Example: We run our
> > +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI
> > +suite] on Windows, Ubuntu, Mac, and others.
> > +
> > +Getting help writing platform support patches
> > +---------------------------------------------
> > +
> > +In general, when sending patches to fix platform support problems, follow
> > +these guidelines to make sure the patch is reviewed with the appropriate level
> > +of urgency:
> > +
> > +* Clearly state in the commit message that you are fixing a platform breakage,
> > +  and for which platform.
> > +
> > +* Use the CI and test suite to ensure that the fix for your platform doesn't
> > +  break other platforms.
> > +
> > +* If possible, add a test ensuring this regression doesn't happen again. If
> > +  it's not possible to add a test, explain why in the commit message.
> > +
> > +Minimum Requirements
> > +--------------------
>
> It might make more sense to move this section immediately after the
> introduction. I don't feel too strongly about it though.

Yeah, I could see it: "here's a lot of nice things you could do, oh
but just kidding at the very end we pull the rug and say actually your
ancient/weird OS is not supported because it is missing XYZ" is not as
nice as "hey, do you support XYZ? great start, these are the next
things you need to do after."

I'll move it and see about adding some clarification to make it flow
(and definitely to not promise that with those minimum quals we will
absolutely support your thing, full stop).

>
>
> > +Even if platform maintainers are willing to add tests or CI runners, we will
> > +not consider helping to support platforms that do not meet these minimum
> > +requirements:
> > +
> > +* Has C99 or C11
> > +
> > +* Has dependencies which were released in the past 10 years
> > +
> > +* Has active security support (taking security releases of dependencies, etc)
> > +
> > +Platform Maintainers
> > +--------------------
> > +
> > +If you maintain a platform, or Git for that platform, and intend to work with
> > +the Git project to ensure compatibility, please send a patch to add yourself to
> > +this list.
> > +
> > +NonStop: Randall S. Becker <rsbecker@nexbridge.com>
>
>
> Overall, looks good to me, thanks!

Thanks for taking a look.

 - Emily

>

[PATCH v4] Documentation: add platform support policy

[Emily Shaffer]

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

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>

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
     +--------------------
     +
-- 
2.46.0.rc1.232.g9752f9e123-goog

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

[Junio C Hamano]

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

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

[Emily Shaffer]

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

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

[Junio C Hamano]

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.

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

[rsbecker]

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

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

[Emily Shaffer]

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

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

[rsbecker]

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

[PATCH v5] Documentation: add platform support policy

[Emily Shaffer]

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>

---

New in v4:

- Wording and bulleting format 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.

I believe that this version addresses Randall's concerns with the
"minimum requirements" policy. Are there any other outstanding concerns
with the policy itself, as written, or is this ready to go in (modulo
nits)?

Thanks,

 - Emily

v1 description at
https://lore.kernel.org/git/20240709225042.2005233-1-emilyshaffer@google.com/
---
 Documentation/Makefile                       |   1 +
 Documentation/technical/platform-support.txt | 190 +++++++++++++++++++
 2 files changed, 191 insertions(+)
 create mode 100644 Documentation/technical/platform-support.txt

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..a227c363d7
--- /dev/null
+++ b/Documentation/technical/platform-support.txt
@@ -0,0 +1,190 @@
+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 platform-specific tooling will allow us to make more solid
+commitments around Git's compatibility with that 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 or for Git contributors.
+Some contributors may volunteer to help with the initial or continued support,
+but that's not a given. Support work which is too intrusive or difficult for the
+project to maintain may still not be accepted.
+
+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, to see if 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. If it appears only on your
+  platform, mention clearly that it is a compatibility issue in your report.
+
+* 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 breaking `master` 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. They must run more often than
+   weekly, as topics generally spend at least 7 days in `next` before graduating
+   to `master`, and it takes time to put the brakes on a patch once it lands in
+   `next`.
+
+** 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` always works for your platform. (See "The Policy" in
+link:../howto/maintain-git.txt["How to maintain Git"] 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>

Range-diff against v4:
1:  02fda7106e ! 1:  6b8123acb6 Documentation: add platform support policy
    @@ Documentation/technical/platform-support.txt (new)
     +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.
    ++Various levels of platform-specific tooling will allow us to make more solid
    ++commitments around Git's compatibility with that 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.
    ++don't make life harder for other supported platforms or for Git contributors.
    ++Some contributors may volunteer to help with the initial or continued support,
    ++but that's not a given. Support work which is too intrusive or difficult for the
    ++project to maintain may still not be accepted.
     +
     +Minimum Requirements
     +--------------------
    @@ Documentation/technical/platform-support.txt (new)
     +  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.
    ++* If possible, build Git from the exact same source both for your platform and
    ++  for a mainstream platform, to see if 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. If it appears only on your
    ++  platform, mention clearly that it is a compatibility issue in your report.
     +
     +* Once we begin to fix the issue, please work closely with the contributor
     +  working on it to test the proposed fix against your platform.
    @@ Documentation/technical/platform-support.txt (new)
     +-----------------------------------
     +
     +To make sure all stable builds and regular releases work for your platform the
    -+first time, help us avoid `master` breaking for your platform:
    ++first time, help us avoid breaking `master` 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`.
    ++** Ideally, these tests should run daily. They must run more often than
    ++   weekly, as topics generally spend at least 7 days in `next` before graduating
    ++   to `master`, and it takes time to put the brakes on a patch once it lands in
    ++   `next`.
     +
     +** 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)
     +--------------------
     +
     +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:
    ++can aim to ensure `next` always works for your platform. (See "The Policy" in
    ++link:../howto/maintain-git.txt["How to maintain Git"] 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
-- 
2.46.0.rc2.264.g509ed76dc8-goog

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

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

> - Wording and bulleting format 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.
>
> I believe that this version addresses Randall's concerns with the
> "minimum requirements" policy. Are there any other outstanding concerns
> with the policy itself, as written, or is this ready to go in (modulo
> nits)?

I won't be able to speak for Randall, but I didn't see anything
questionable in the changes since the previous iteration (I have
not yet read the whole thing again, which I will later).

Thanks.

RE: [PATCH v5] Documentation: add platform support policy

[rsbecker]

On Friday, August 2, 2024 7:32 PM, Junio C Hamano wrote:
>Emily Shaffer <emilyshaffer@google.com> writes:
>
>> - Wording and bulleting format 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.
>>
>> I believe that this version addresses Randall's concerns with the
>> "minimum requirements" policy. Are there any other outstanding
>> concerns with the policy itself, as written, or is this ready to go in
>> (modulo nits)?
>
>I won't be able to speak for Randall, but I didn't see anything questionable in the
>changes since the previous iteration (I have not yet read the whole thing again,
>which I will later).

I still have to think about it, but so far, it looks like I can live with this.