191 lines
8.9 KiB
Plaintext
191 lines
8.9 KiB
Plaintext
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>
|