Documentation/technical/platform-support.txt - jrn/git - Git at Google

 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.html["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.html["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>
	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.html["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.html["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>