Merge branch 'es/doc-platform-support-policy'
A policy document that describes platform support levels and expectation on platform stakeholders has been introduced. * es/doc-platform-support-policy: Documentation: add platform support policy
This commit is contained in:
Junio C Hamano
@ -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
|
||||
|
||||
190
Documentation/technical/platform-support.txt
Normal file
190
Documentation/technical/platform-support.txt
Normal file
@ -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>
|
||||
Reference in New Issue
Block a user