diff --git a/external/docs/asciidoc/817d53c8da22db548200fb25ec14c9d0f51cfded b/external/docs/asciidoc/817d53c8da22db548200fb25ec14c9d0f51cfded new file mode 100644 index 0000000000..25f3a2f20a --- /dev/null +++ b/external/docs/asciidoc/817d53c8da22db548200fb25ec14c9d0f51cfded @@ -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:/docs/../howto/maintain-git["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:/docs/../howto/maintain-git["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 diff --git a/external/docs/content/docs/howto/maintain-git.html b/external/docs/content/docs/howto/maintain-git.html new file mode 100644 index 0000000000..238722b92f --- /dev/null +++ b/external/docs/content/docs/howto/maintain-git.html @@ -0,0 +1,5 @@ +--- +### DO NOT EDIT! Generated by script/update-docs.rb + +redirect_to: https://github.com/git/git/blob/HEAD/Documentation/howto/maintain-git.txt +--- diff --git a/external/docs/content/docs/platform-support.html b/external/docs/content/docs/platform-support.html index 71c6d6a2c2..98cef6bd2a 100644 --- a/external/docs/content/docs/platform-support.html +++ b/external/docs/content/docs/platform-support.html @@ -80,7 +80,7 @@

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 "How to maintain Git" for an +Policy" in }}">"How to maintain Git" for an overview of which branches are used in the Git project, and how.

  • @@ -192,7 +192,7 @@

    C

    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 -"How to maintain Git" for an overview of how +}}">"How to maintain Git" for an overview of how next is used in the Git project.) To do that:

    diff --git a/external/docs/content/docs/platform-support/2.47.0.html b/external/docs/content/docs/platform-support/2.47.0.html index ce233d99d6..94fbc582d6 100644 --- a/external/docs/content/docs/platform-support/2.47.0.html +++ b/external/docs/content/docs/platform-support/2.47.0.html @@ -79,7 +79,7 @@

    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 "How to maintain Git" for an +Policy" in }}">"How to maintain Git" for an overview of which branches are used in the Git project, and how.

  • @@ -191,7 +191,7 @@

    C

    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 -"How to maintain Git" for an overview of how +}}">"How to maintain Git" for an overview of how next is used in the Git project.) To do that:

    diff --git a/external/docs/data/docs.yml b/external/docs/data/docs.yml index e91d09d081..12e3482234 100644 --- a/external/docs/data/docs.yml +++ b/external/docs/data/docs.yml @@ -71365,7 +71365,7 @@ pages: removed: 0 platform-support: version-map: - 2.47.0: 16dd48c906456ee4beb3635b7795761fc483363d + 2.47.0: 817d53c8da22db548200fb25ec14c9d0f51cfded latest-changes: 2.47.0 page-versions: - name: 2.47.0