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 "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 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 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 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: 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 "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 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>