diff --git a/DecisionMaking.html b/DecisionMaking.html index 67d70016e..b45314dca 100644 --- a/DecisionMaking.html +++ b/DecisionMaking.html @@ -442,7 +442,7 @@
diff --git a/MyFirstContribution.html b/MyFirstContribution.html index 88d0f3c81..6e9ab54e0 100644 --- a/MyFirstContribution.html +++ b/MyFirstContribution.html @@ -442,7 +442,7 @@
diff --git a/MyFirstObjectWalk.html b/MyFirstObjectWalk.html index ec4b7128e..0d2e87c58 100644 --- a/MyFirstObjectWalk.html +++ b/MyFirstObjectWalk.html @@ -442,7 +442,7 @@
diff --git a/RelNotes/2.47.0.txt b/RelNotes/2.47.0.txt index b948fa4db..5e1af5788 100644 --- a/RelNotes/2.47.0.txt +++ b/RelNotes/2.47.0.txt @@ -21,6 +21,12 @@ UI, Workflows & Features discard it when we taught proxy auth code path to use the credential helpers, which has been corrected. + * The code paths to compact multiple reftable files have been updated + to correctly deal with multiple compaction triggering at the same + time. + + * Support to specify ref backend for submodules has been enhanced. + Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -51,6 +57,16 @@ Performance, Internal Implementation, Development Support etc. less likely to cause trouble by lengthening the expiry value it uses. + * An existing test of hashmap API has been rewritten with the + unit-test framework. + + * A policy document that describes platform support levels and + expectation on platform stakeholders has been introduced. + + * The refs API has been taught to give symref target information to + the users of ref iterators, allowing for-each-ref and friends to + avoid an extra ref_resolve_* API call per a symbolic ref. + Fixes since v2.46 ----------------- @@ -118,6 +134,14 @@ Fixes since v2.46 fixed. (merge ec60bb9fc4 kl/test-fixes later to maint). + * Follow-up on 2.45.1 regression fix. + (merge ee0be850b0 jc/safe-directory later to maint). + + * "git rev-list ... | git diff-tree -p --remerge-diff --stdin" should + behave more or less like "git log -p --remerge-diff" but instead it + crashed, forgetting to prepare a temporary object store needed. + (merge a77554ea09 xx/diff-tree-remerge-diff-fix later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 8db8786fc2 jt/doc-post-receive-hook-update later to maint). (merge 1c473dd6af tn/doc-commit-fix later to maint). @@ -131,3 +155,4 @@ Fixes since v2.46 (merge e2e373ba82 ss/packed-ref-store-leakfix later to maint). (merge 0c4d5aa22d rs/use-decimal-width later to maint). (merge 67be8c4de5 jc/document-use-of-local later to maint). + (merge 098be29f5b rs/t-example-simplify later to maint). diff --git a/ReviewingGuidelines.html b/ReviewingGuidelines.html index 4d0ffc09e..efc4ba8d2 100644 --- a/ReviewingGuidelines.html +++ b/ReviewingGuidelines.html @@ -442,7 +442,7 @@
diff --git a/SubmittingPatches.html b/SubmittingPatches.html index 480773864..05ad458fa 100644 --- a/SubmittingPatches.html +++ b/SubmittingPatches.html @@ -442,7 +442,7 @@
diff --git a/ToolsForGit.html b/ToolsForGit.html index f2ee1ddd8..ab94d27fd 100644 --- a/ToolsForGit.html +++ b/ToolsForGit.html @@ -442,7 +442,7 @@
diff --git a/everyday.html b/everyday.html index faf3b1a42..30293fb1d 100644 --- a/everyday.html +++ b/everyday.html @@ -442,7 +442,7 @@
diff --git a/git-remote-helpers.html b/git-remote-helpers.html index d52b4051b..6bdc743ec 100644 --- a/git-remote-helpers.html +++ b/git-remote-helpers.html @@ -442,7 +442,7 @@
diff --git a/git-submodule.html b/git-submodule.html index 6503f8e7a..013e005f7 100644 --- a/git-submodule.html +++ b/git-submodule.html @@ -486,7 +486,7 @@

COMMANDS

-
add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
+
add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]

Add the given repository as a submodule at the given path to the changeset to be committed next to the current @@ -528,6 +528,10 @@

COMMANDS

git-submodule will correctly locate the submodule using the relative URL in .gitmodules.

+
+

If --ref-format <format> is specified, the ref storage format of newly +cloned submodules will be set accordingly.

+
status [--cached] [--recursive] [--] [<path>…​]
@@ -606,7 +610,7 @@

COMMANDS

options.

-
update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>…​]
+
update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>…​]
@@ -680,6 +684,10 @@

COMMANDS

registered submodules, and update any nested submodules within.

+

If --ref-format <format> is specified, the ref storage format of newly +cloned submodules will be set accordingly.

+
+

If --filter <filter-spec> is specified, the given partial clone filter will be applied to the submodule. See git-rev-list(1) for details on filter specifications.

@@ -1031,7 +1039,7 @@

GIT

diff --git a/git-submodule.txt b/git-submodule.txt index ca0347a37..87d8e0f0c 100644 --- a/git-submodule.txt +++ b/git-submodule.txt @@ -34,7 +34,7 @@ COMMANDS With no arguments, shows the status of existing submodules. Several subcommands are available to perform operations on the submodules. -add [-b ] [-f|--force] [--name ] [--reference ] [--depth ] [--] []:: +add [-b ] [-f|--force] [--name ] [--reference ] [--ref-format ] [--depth ] [--] []:: Add the given repository as a submodule at the given path to the changeset to be committed next to the current project: the current project is termed the "superproject". @@ -71,6 +71,9 @@ submodule repositories will be kept together in the same relative location, and only the superproject's URL needs to be provided. git-submodule will correctly locate the submodule using the relative URL in `.gitmodules`. ++ +If `--ref-format ` is specified, the ref storage format of newly +cloned submodules will be set accordingly. status [--cached] [--recursive] [--] [...]:: Show the status of the submodules. This will print the SHA-1 of the @@ -136,7 +139,7 @@ If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal options. -update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference ] [--depth ] [--recursive] [--jobs ] [--[no-]single-branch] [--filter ] [--] [...]:: +update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference ] [--ref-format ] [--depth ] [--recursive] [--jobs ] [--[no-]single-branch] [--filter ] [--] [...]:: + -- Update the registered submodules to match what the superproject @@ -185,6 +188,9 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. +If `--ref-format ` is specified, the ref storage format of newly +cloned submodules will be set accordingly. + If `--filter ` is specified, the given partial clone filter will be applied to the submodule. See linkgit:git-rev-list[1] for details on filter specifications. diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index 7a028b33a..e3c9a28e1 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html @@ -442,7 +442,7 @@
@@ -705,7 +705,7 @@

Keep authoritative canonical history correct with git pull

diff --git a/howto/maintain-git.html b/howto/maintain-git.html index cdc2ab37f..86521f837 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html @@ -442,7 +442,7 @@
@@ -1235,7 +1235,7 @@

Preparing a "merge-fix"

diff --git a/howto/new-command.html b/howto/new-command.html index 290a7811b..60882bff5 100644 --- a/howto/new-command.html +++ b/howto/new-command.html @@ -442,7 +442,7 @@
@@ -584,7 +584,7 @@

Integrating a command

diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index 5dae93a61..ee13e55fe 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html @@ -442,7 +442,7 @@
@@ -656,7 +656,7 @@

How to rebase from an internal branch

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index 2cfd8be42..bb104e253 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html @@ -442,7 +442,7 @@
@@ -563,7 +563,7 @@

How to rebuild from update hook

diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index 160c2dc19..0f6158021 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html @@ -442,7 +442,7 @@
@@ -641,7 +641,7 @@

How to recover a corrupted blob object

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index 9891f97fa..1d188a2d6 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html @@ -442,7 +442,7 @@
@@ -967,7 +967,7 @@

The adventure continues…​

diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index 0b22da0c6..b406107b1 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html @@ -442,7 +442,7 @@
@@ -829,7 +829,7 @@

How to revert a faulty merge

diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index b290334ca..0e9b89d93 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html @@ -442,7 +442,7 @@
@@ -649,7 +649,7 @@

How to revert an existing commit

diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index ddbe24f8e..125068517 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html @@ -442,7 +442,7 @@
@@ -568,7 +568,7 @@

How to separate topic branches

diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index ab243d09d..a0bc7103f 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html @@ -442,7 +442,7 @@
@@ -882,7 +882,7 @@

Troubleshooting:

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index 9e30a77fa..8175276f6 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html @@ -442,7 +442,7 @@
@@ -648,7 +648,7 @@

How to use the update hook

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index 0191ea4c9..1ab486909 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html @@ -442,7 +442,7 @@
@@ -524,7 +524,7 @@

How to use git-daemon

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index efc417fc8..1e0fa487d 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html @@ -442,7 +442,7 @@
@@ -554,7 +554,7 @@

Additional tips

diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index ca4a7e5f2..79cab6ae4 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html @@ -442,7 +442,7 @@
@@ -712,7 +712,7 @@

Auditors

diff --git a/technical/api-error-handling.html b/technical/api-error-handling.html index bf10a3b90..ae5425a55 100644 --- a/technical/api-error-handling.html +++ b/technical/api-error-handling.html @@ -437,7 +437,7 @@
diff --git a/technical/api-index.html b/technical/api-index.html index f147e9da5..36850346a 100644 --- a/technical/api-index.html +++ b/technical/api-index.html @@ -437,7 +437,7 @@
diff --git a/technical/api-merge.html b/technical/api-merge.html index e775af014..9936ec291 100644 --- a/technical/api-merge.html +++ b/technical/api-merge.html @@ -437,7 +437,7 @@
diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html index 5f296b98b..8ca283495 100644 --- a/technical/api-parse-options.html +++ b/technical/api-parse-options.html @@ -437,7 +437,7 @@
diff --git a/technical/api-simple-ipc.html b/technical/api-simple-ipc.html index b602df3b2..084ab1cc2 100644 --- a/technical/api-simple-ipc.html +++ b/technical/api-simple-ipc.html @@ -437,7 +437,7 @@
diff --git a/technical/api-trace2.html b/technical/api-trace2.html index 2247361a1..f7e99d1fb 100644 --- a/technical/api-trace2.html +++ b/technical/api-trace2.html @@ -437,7 +437,7 @@
diff --git a/technical/bitmap-format.html b/technical/bitmap-format.html index 496706cb5..487c686fc 100644 --- a/technical/bitmap-format.html +++ b/technical/bitmap-format.html @@ -437,7 +437,7 @@
diff --git a/technical/bundle-uri.html b/technical/bundle-uri.html index 10449fe93..f25fa95a8 100644 --- a/technical/bundle-uri.html +++ b/technical/bundle-uri.html @@ -437,7 +437,7 @@
diff --git a/technical/hash-function-transition.html b/technical/hash-function-transition.html index 022872a0b..29c491151 100644 --- a/technical/hash-function-transition.html +++ b/technical/hash-function-transition.html @@ -437,7 +437,7 @@
diff --git a/technical/long-running-process-protocol.html b/technical/long-running-process-protocol.html index f3380e24e..188283a36 100644 --- a/technical/long-running-process-protocol.html +++ b/technical/long-running-process-protocol.html @@ -437,7 +437,7 @@
diff --git a/technical/multi-pack-index.html b/technical/multi-pack-index.html index 3dc546935..97db8242c 100644 --- a/technical/multi-pack-index.html +++ b/technical/multi-pack-index.html @@ -437,7 +437,7 @@
diff --git a/technical/pack-heuristics.html b/technical/pack-heuristics.html index cd538e6f2..a68a3fa5f 100644 --- a/technical/pack-heuristics.html +++ b/technical/pack-heuristics.html @@ -437,7 +437,7 @@
diff --git a/technical/parallel-checkout.html b/technical/parallel-checkout.html index 39af4650e..12f8e5e49 100644 --- a/technical/parallel-checkout.html +++ b/technical/parallel-checkout.html @@ -437,7 +437,7 @@
diff --git a/technical/partial-clone.html b/technical/partial-clone.html index 311b84c73..2981894ed 100644 --- a/technical/partial-clone.html +++ b/technical/partial-clone.html @@ -437,7 +437,7 @@
diff --git a/technical/platform-support.html b/technical/platform-support.html new file mode 100644 index 000000000..9fc6c79fd --- /dev/null +++ b/technical/platform-support.html @@ -0,0 +1,731 @@ + + + + + + + +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 "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>

+
+
+
+
+ + + \ No newline at end of file diff --git a/technical/platform-support.txt b/technical/platform-support.txt new file mode 100644 index 000000000..a227c363d --- /dev/null +++ b/technical/platform-support.txt @@ -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:../howto/maintain-git.txt["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.txt["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/technical/racy-git.html b/technical/racy-git.html index f9a4ff377..10c045c96 100644 --- a/technical/racy-git.html +++ b/technical/racy-git.html @@ -437,7 +437,7 @@
diff --git a/technical/scalar.html b/technical/scalar.html index f77f9387f..64591dd9f 100644 --- a/technical/scalar.html +++ b/technical/scalar.html @@ -437,7 +437,7 @@
diff --git a/technical/send-pack-pipeline.html b/technical/send-pack-pipeline.html index e4ef31706..d73b6a4f7 100644 --- a/technical/send-pack-pipeline.html +++ b/technical/send-pack-pipeline.html @@ -437,7 +437,7 @@
diff --git a/technical/shallow.html b/technical/shallow.html index 266a0248b..538357279 100644 --- a/technical/shallow.html +++ b/technical/shallow.html @@ -437,7 +437,7 @@
diff --git a/technical/trivial-merge.html b/technical/trivial-merge.html index 5d97beec0..9cafbcd22 100644 --- a/technical/trivial-merge.html +++ b/technical/trivial-merge.html @@ -437,7 +437,7 @@
diff --git a/technical/unit-tests.html b/technical/unit-tests.html index 3f4ad3c73..d2747c436 100644 --- a/technical/unit-tests.html +++ b/technical/unit-tests.html @@ -437,7 +437,7 @@