Emily Shaffer <emilyshaffer@xxxxxxxxxx> 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.
