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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 18, 2024, 22:46 UTC
Message-ID: <xmqqh6cmmi8n.fsf@gitster.g>
In-Reply-To: <20240718173843.2411415-1-emilyshaffer@google.com>

Emily Shaffer <emilyshaffer@google.com> writes:

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

"easy" -> "possible".

Show 12 quoted lines

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

Show 19 quoted lines

> +Compatible on `next`
> +--------------------
> +
> +To avoid reactive debugging and fixing when changes hit a release or stable, you
> +can aim to ensure `next` works for your platform. (See "The Policy" in the
> +link:../howto/maintain-git.txt[maintainer's guide] for an overview of how `next`
> +is used in the Git project.) To do that:
> +
> +* 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.

Show 8 quoted lines

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