|
| 1 | +Platform Support Policy |
| 2 | +======================= |
| 3 | + |
| 4 | +Git has a history of providing broad "support" for exotic platforms and older |
| 5 | +platforms, without an explicit commitment. Stakeholders of these platforms may |
| 6 | +want a more predictable support commitment. This is only possible when platform |
| 7 | +stakeholders supply Git developers with adequate tooling, so we can test for |
| 8 | +compatibility or develop workarounds for platform-specific quirks on our own. |
| 9 | +Various levels of platform-specific tooling will allow us to make more solid |
| 10 | +commitments around Git's compatibility with that platform. |
| 11 | + |
| 12 | +Note that this document is about maintaining existing support for a platform |
| 13 | +that has generally worked in the past; for adding support to a platform which |
| 14 | +doesn't generally work with Git, the stakeholders for that platform are expected |
| 15 | +to do the bulk of that work themselves. We will consider such patches if they |
| 16 | +don't make life harder for other supported platforms or for Git contributors. |
| 17 | +Some contributors may volunteer to help with the initial or continued support, |
| 18 | +but that's not a given. Support work which is too intrusive or difficult for the |
| 19 | +project to maintain may still not be accepted. |
| 20 | + |
| 21 | +Minimum Requirements |
| 22 | +-------------------- |
| 23 | + |
| 24 | +The rest of this doc describes best practices for platforms to make themselves |
| 25 | +easy to support. However, before considering support at all, platforms need to |
| 26 | +meet the following minimum requirements: |
| 27 | + |
| 28 | +* Has C99 or C11 |
| 29 | + |
| 30 | +* Uses versions of dependencies which are generally accepted as stable and |
| 31 | + supportable, e.g., in line with the version used by other long-term-support |
| 32 | + distributions |
| 33 | + |
| 34 | +* Has active security support (taking security releases of dependencies, etc) |
| 35 | + |
| 36 | +These requirements are a starting point, and not sufficient on their own for the |
| 37 | +Git community to be enthusiastic about supporting your platform. Maintainers of |
| 38 | +platforms which do meet these requirements can follow the steps below to make it |
| 39 | +more likely that Git updates will respect the platform's needs. |
| 40 | + |
| 41 | +Compatible by next release |
| 42 | +-------------------------- |
| 43 | + |
| 44 | +To increase probability that compatibility issues introduced in a release |
| 45 | +will be fixed in a later release: |
| 46 | + |
| 47 | +* You should send a bug report as soon as you notice the breakage on your |
| 48 | + platform. The sooner you notice, the better; watching `seen` means you can |
| 49 | + notice problems before they are considered "done with review"; whereas |
| 50 | + watching `master` means the stable branch could break for your platform, but |
| 51 | + you have a decent chance of avoiding a tagged release breaking you. See "The |
| 52 | + Policy" in link:/docs/../howto/maintain-git["How to maintain Git"] for an |
| 53 | + overview of which branches are used in the Git project, and how. |
| 54 | + |
| 55 | +* The bug report should include information about what platform you are using. |
| 56 | + |
| 57 | +* You should also use linkgit:git-bisect[1] and determine which commit |
| 58 | + introduced the breakage. |
| 59 | + |
| 60 | +* Please include any information you have about the nature of the breakage: is |
| 61 | + it a memory alignment issue? Is an underlying library missing or broken for |
| 62 | + your platform? Is there some quirk about your platform which means typical |
| 63 | + practices (like malloc) behave strangely? |
| 64 | + |
| 65 | +* If possible, build Git from the exact same source both for your platform and |
| 66 | + for a mainstream platform, to see if the problem you noticed appears only |
| 67 | + on your platform. If the problem appears in both, then it's not a |
| 68 | + compatibility issue, but we of course appreciate hearing about it in a bug |
| 69 | + report anyway, to benefit users of every platform. If it appears only on your |
| 70 | + platform, mention clearly that it is a compatibility issue in your report. |
| 71 | + |
| 72 | +* Once we begin to fix the issue, please work closely with the contributor |
| 73 | + working on it to test the proposed fix against your platform. |
| 74 | + |
| 75 | +Example: NonStop |
| 76 | +https://lore.kernel.org/git/ [email protected]/[reports |
| 77 | +problems] when they're noticed. |
| 78 | + |
| 79 | +Compatible on `master` and releases |
| 80 | +----------------------------------- |
| 81 | + |
| 82 | +To make sure all stable builds and regular releases work for your platform the |
| 83 | +first time, help us avoid breaking `master` for your platform: |
| 84 | + |
| 85 | +* You should run regular tests against the `next` branch and |
| 86 | + publish breakage reports to the mailing list immediately when they happen. |
| 87 | + |
| 88 | +** Ideally, these tests should run daily. They must run more often than |
| 89 | + weekly, as topics generally spend at least 7 days in `next` before graduating |
| 90 | + to `master`, and it takes time to put the brakes on a patch once it lands in |
| 91 | + `next`. |
| 92 | + |
| 93 | +** You may want to ask to join the mailto: [email protected][security |
| 94 | + mailing list] in order to run tests against the fixes proposed there, too. |
| 95 | + |
| 96 | +* It may make sense to automate these; if you do, make sure they are not noisy |
| 97 | + (you don't need to send a report when everything works, only when something |
| 98 | + breaks; you don't need to send repeated reports for the same breakage night |
| 99 | + after night). |
| 100 | + |
| 101 | +* Breakage reports should be actionable - include clear error messages that can |
| 102 | + help developers who may not have access to test directly on your platform. |
| 103 | + |
| 104 | +* You should use git-bisect and determine which commit introduced the breakage; |
| 105 | + if you can't do this with automation, you should do this yourself manually as |
| 106 | + soon as you notice a breakage report was sent. |
| 107 | + |
| 108 | +* You should either: |
| 109 | + |
| 110 | +** Provide on-demand access to your platform to a trusted developer working to |
| 111 | + fix the issue, so they can test their fix, OR |
| 112 | + |
| 113 | +** Work closely with the developer fixing the issue; the turnaround to check |
| 114 | + that their proposed fix works for your platform should be fast enough that it |
| 115 | + doesn't hinder the developer working on that fix. Slow testing turnarounds |
| 116 | + may cause the fix to miss the next release, or the developer may lose |
| 117 | + interest in working on the fix at all. |
| 118 | + |
| 119 | +Example: |
| 120 | +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/[AIX] |
| 121 | +provides a build farm and runs tests against release candidates. |
| 122 | + |
| 123 | +Compatible on `next` |
| 124 | +-------------------- |
| 125 | + |
| 126 | +To avoid reactive debugging and fixing when changes hit a release or stable, you |
| 127 | +can aim to ensure `next` always works for your platform. (See "The Policy" in |
| 128 | +link:/docs/../howto/maintain-git["How to maintain Git"] for an overview of how |
| 129 | +`next` is used in the Git project.) To do that: |
| 130 | + |
| 131 | +* You should add a runner for your platform to the GitHub Actions or GitLab CI |
| 132 | + suite. This suite is run when any Git developer proposes a new patch, and |
| 133 | + having a runner for your platform/configuration means every developer will |
| 134 | + know if they break you, immediately. |
| 135 | + |
| 136 | +** If adding it to an existing CI suite is infeasible (due to architecture |
| 137 | + constraints or for performance reasons), any other method which runs as |
| 138 | + automatically and quickly as possible works, too. For example, a service |
| 139 | + which snoops on the mailing list and automatically runs tests on new [PATCH] |
| 140 | + emails, replying to the author with the results, would also be within the |
| 141 | + spirit of this requirement. |
| 142 | + |
| 143 | +* If you rely on Git avoiding a specific pattern that doesn't work well with |
| 144 | + your platform (like a certain malloc pattern), raise it on the mailing list. |
| 145 | + We'll work case-by-case to look for a solution that doesn't unnecessarily |
| 146 | + constrain other platforms to keep compatibility with yours. |
| 147 | + |
| 148 | +* If you rely on some configuration or behavior, add a test for it. Untested |
| 149 | + behavior is subject to breakage at any time. |
| 150 | + |
| 151 | +** Clearly label these tests as necessary for platform compatibility. Add them |
| 152 | + to an isolated compatibility-related test suite, like a new t* file or unit |
| 153 | + test suite, so that they're easy to remove when compatibility is no longer |
| 154 | + required. If the specific compatibility need is gated behind an issue with |
| 155 | + another project, link to documentation of that issue (like a bug or email |
| 156 | + thread) to make it easier to tell when that compatibility need goes away. |
| 157 | + |
| 158 | +** Include a comment with an expiration date for these tests no more than 1 year |
| 159 | + from now. You can update the expiration date if your platform still needs |
| 160 | + that assurance down the road, but we need to know you still care about that |
| 161 | + compatibility case and are working to make it unnecessary. |
| 162 | + |
| 163 | +Example: We run our |
| 164 | +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI |
| 165 | +suite] on Windows, Ubuntu, Mac, and others. |
| 166 | + |
| 167 | +Getting help writing platform support patches |
| 168 | +--------------------------------------------- |
| 169 | + |
| 170 | +In general, when sending patches to fix platform support problems, follow |
| 171 | +these guidelines to make sure the patch is reviewed with the appropriate level |
| 172 | +of urgency: |
| 173 | + |
| 174 | +* Clearly state in the commit message that you are fixing a platform breakage, |
| 175 | + and for which platform. |
| 176 | + |
| 177 | +* Use the CI and test suite to ensure that the fix for your platform doesn't |
| 178 | + break other platforms. |
| 179 | + |
| 180 | +* If possible, add a test ensuring this regression doesn't happen again. If |
| 181 | + it's not possible to add a test, explain why in the commit message. |
| 182 | + |
| 183 | +Platform Maintainers |
| 184 | +-------------------- |
| 185 | + |
| 186 | +If you maintain a platform, or Git for that platform, and intend to work with |
| 187 | +the Git project to ensure compatibility, please send a patch to add yourself to |
| 188 | +this list. |
| 189 | + |
| 190 | +NonStop: Randall S. Becker < [email protected]> |
0 commit comments