RE: [PATCH] Documentation: add platform support policy

[<rsbecker@nexbridge.com>]

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