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