mirrors/git
0
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-11-27 20:14:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: add platform support policy

Browse Source 
Supporting many platforms is only possible when we have the right tools to
ensure that support.

Teach platform maintainers how they can help us to help them, by
explaining what kind of tooling support we would like to have, and what
level of support becomes available as a result. Provide examples so that
platform maintainers can see what we're asking for in practice.

With this policy in place, we can make changes with stronger assurance
that we are not breaking anybody we promised not to. Instead, we can
feel confident that our existing testing and integration practices
protect those who care from breakage.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Emily Shaffer 2024-08-02 15:19:48 -07:00 committed by Junio C Hamano
parent a7dae3bdc8
commit d53db106e0
2 changed files with 191 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/Makefile
View File

@ -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
View 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>