technical/platform-support.txt

   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:../howto/maintain-git.html["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/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[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:git-security@googlegroups.com[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:../howto/maintain-git.html["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 <rsbecker@nexbridge.com>