From 729c5bfe245b710c70b87babae338d4b35a34021 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Mon, 7 Oct 2024 18:05:51 +0200 Subject: [PATCH 1/5] ci: do open an issue when a broken link is detected As of v2.47.0, there is a problem where `/docs/platform-support` links to `/howto/maintain-git` (it should be prefixed with `/docs` is the bug). And indeed, directing a web browser to https://git-scm.com/docs/platform-support and following the "How to maintain Git" link will lead to a 404. This problem was identified correctly by https://github.com/git/git-scm.com/actions/runs/11219313103, but when that workflow run tried to open a ticket about the problem, it failed https://github.com/git/git-scm.com/actions/runs/11219313103/job/31184984303#step:11:127081 ReferenceError: req is not defined at eval (eval at callAsyncFunction (/home/runner/work/_actions/actions/github-script/v7/dist/index.js:35424:16), :33:42) at process.processTicksAndRejections (node:internal/process/task_queues:95:5) at async main (/home/runner/work/_actions/actions/github-script/v7/dist/index.js:35522:20) Error: Unhandled error: ReferenceError: req is not defined The problem is that the variable `req` was defined within too narrow a scope, which is fixed by this here commit. Signed-off-by: Johannes Schindelin --- .github/actions/deploy-to-github-pages/action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/actions/deploy-to-github-pages/action.yml b/.github/actions/deploy-to-github-pages/action.yml index 180b8780d8..5083f536de 100644 --- a/.github/actions/deploy-to-github-pages/action.yml +++ b/.github/actions/deploy-to-github-pages/action.yml @@ -150,8 +150,8 @@ runs: return s.replace(/^([^]{0,65000}\n)[^]*\n(.+)\n?$/, '$1\n[...]\n\n$2') })(await fs.promises.readFile('lychee.md', 'utf8')) + const req = { owner: context.repo.owner, repo: context.repo.repo } const issues = await (async () => { - const req = { owner: context.repo.owner, repo: context.repo.repo } const q = `"Link+Checker+Report"+in:title+is:issue+label:linkchecker+is:open+repo:${req.owner}/${req.repo}` try { return await github.rest.search.issuesAndPullRequests({ ...req, q, sort: 'created', per_page: 1 }) From 72d3f4f5bf6049c09c65d8807ae46cd0678f80b9 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Mon, 7 Oct 2024 22:59:54 +0200 Subject: [PATCH 2/5] ci(lychee): do detect incorrect `../` links Links should not "try to break outside" by starting with `../`. Let's detect that also when deploying in forks. Signed-off-by: Johannes Schindelin --- .github/actions/deploy-to-github-pages/action.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/actions/deploy-to-github-pages/action.yml b/.github/actions/deploy-to-github-pages/action.yml index 5083f536de..8b3948c85b 100644 --- a/.github/actions/deploy-to-github-pages/action.yml +++ b/.github/actions/deploy-to-github-pages/action.yml @@ -106,7 +106,7 @@ runs: -H "Content-Type: application/json" \ -d '{ "purge_everything": true }' - - name: construct `--remap` option for lychee + - name: construct `--remap` options for lychee id: remap shell: bash run: | @@ -114,6 +114,11 @@ runs: echo "result=$(echo "$base_url" | sed 's|^\(.*\)\(/git-scm\.com\)$|(\1)?\2(.*)|') file://$PWD/public\$2" \ >>$GITHUB_OUTPUT + # When running in forks, do detect when links try to break out of the + # `/git-scm.com/` subdirectory + echo "remap-dotdot=$(echo "$base_url" | + sed 's|^\(.*\)\(/git-scm\.com\)$|--remap '\''(\1.*) file://../$1'\''|')" \ + >>$GITHUB_OUTPUT - name: check for broken links id: lychee @@ -125,6 +130,7 @@ runs: --fallback-extensions html --base '${{ steps.pages.outputs.base_url }}' --remap '${{ steps.remap.outputs.result }}' + ${{ steps.remap.outputs.remap-dotdot }} --exclude file:///path/to/repo.git/ --exclude file:///caminho/para/o/reposit%C3%B3rio.git/ --exclude file:///ruta/a/repositorio.git/ From 56a9595e2cc29609a8b9dbe6ad1fda2a690a8d39 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Mon, 7 Oct 2024 20:15:34 +0200 Subject: [PATCH 3/5] update-docs: work around a problem introduced in v2.47.0 In v2.47.0, the new `platform-support` document contains a link to a `.txt` file when it should point to a `.html` file instead. Let's add a work-around for that, to avoid a broken link. Signed-off-by: Johannes Schindelin --- script/update-docs.rb | 3 +++ 1 file changed, 3 insertions(+) diff --git a/script/update-docs.rb b/script/update-docs.rb index 07c168fd1a..922ca28a9d 100644 --- a/script/update-docs.rb +++ b/script/update-docs.rb @@ -400,6 +400,9 @@ def index_doc(filter_tags, doc_list, get_content) page_data = data["pages"][docname] content = expand_content((get_content.call sha).force_encoding("UTF-8"), path, get_content_f, generated) + # Handle `link:../howto/maintain-git.txt`, which should point to + # a `.html` target instead + content.gsub!(/link:\.\.\/howto\/maintain-git\.txt/, 'link:../howto/maintain-git.html') # Handle `gitlink:` mistakes (the last of which was fixed in # dbf47215e32b (rebase docs: fix "gitlink" typo, 2019-02-27)) content.gsub!(/gitlink:/, "linkgit:") From 375afd4ccc49a456bbb6d97c9a5dfb0b834dca60 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Mon, 7 Oct 2024 21:07:29 +0200 Subject: [PATCH 4/5] update-docs: fix whitespace issue Indentation here is done using spaces. Signed-off-by: Johannes Schindelin --- script/update-docs.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/script/update-docs.rb b/script/update-docs.rb index 922ca28a9d..b227ebcb3f 100644 --- a/script/update-docs.rb +++ b/script/update-docs.rb @@ -409,8 +409,8 @@ def index_doc(filter_tags, doc_list, get_content) # Handle erroneous `link:api-trace2.txt`, see 4945f046c7f5 (api docs: # link to html version of api-trace2, 2022-09-16) content.gsub!(/link:api-trace2.txt/, 'link:api-trace2.html') - # Handle `linkgit:git-config.txt` mistake, fixed in ad52148a7d0 - # (Documentation: fix broken linkgit to git-config, 2016-03-21) + # Handle `linkgit:git-config.txt` mistake, fixed in ad52148a7d0 + # (Documentation: fix broken linkgit to git-config, 2016-03-21) content.gsub!(/linkgit:git-config.txt/, 'linkgit:git-config') content.gsub!(/link:(?:technical\/)?(\S*?)\.html(\#\S*?)?\[(.*?)\]/m, "link:/docs/\\1\\2[\\3]") From 4593a42bc6f0ffce49214d257924fea1a206fe80 Mon Sep 17 00:00:00 2001 From: dscho Date: Mon, 7 Oct 2024 21:24:53 +0000 Subject: [PATCH 5/5] Update manual pages (manually forced rebuild) Updated via the `update-git-version-and-manual-pages.yml` GitHub workflow. --- .../817d53c8da22db548200fb25ec14c9d0f51cfded | 190 ++++++++++++++++++ .../docs/content/docs/howto/maintain-git.html | 5 + .../docs/content/docs/platform-support.html | 4 +- .../content/docs/platform-support/2.47.0.html | 4 +- external/docs/data/docs.yml | 2 +- 5 files changed, 200 insertions(+), 5 deletions(-) create mode 100644 external/docs/asciidoc/817d53c8da22db548200fb25ec14c9d0f51cfded create mode 100644 external/docs/content/docs/howto/maintain-git.html diff --git a/external/docs/asciidoc/817d53c8da22db548200fb25ec14c9d0f51cfded b/external/docs/asciidoc/817d53c8da22db548200fb25ec14c9d0f51cfded new file mode 100644 index 0000000000..25f3a2f20a --- /dev/null +++ b/external/docs/asciidoc/817d53c8da22db548200fb25ec14c9d0f51cfded @@ -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:/docs/../howto/maintain-git["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:/docs/../howto/maintain-git["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/external/docs/content/docs/howto/maintain-git.html b/external/docs/content/docs/howto/maintain-git.html new file mode 100644 index 0000000000..238722b92f --- /dev/null +++ b/external/docs/content/docs/howto/maintain-git.html @@ -0,0 +1,5 @@ +--- +### DO NOT EDIT! Generated by script/update-docs.rb + +redirect_to: https://github.com/git/git/blob/HEAD/Documentation/howto/maintain-git.txt +--- diff --git a/external/docs/content/docs/platform-support.html b/external/docs/content/docs/platform-support.html index 71c6d6a2c2..98cef6bd2a 100644 --- a/external/docs/content/docs/platform-support.html +++ b/external/docs/content/docs/platform-support.html @@ -80,7 +80,7 @@

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 +Policy" in }}">"How to maintain Git" for an overview of which branches are used in the Git project, and how.

  • @@ -192,7 +192,7 @@

    C

    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 +}}">"How to maintain Git" for an overview of how next is used in the Git project.) To do that:

    diff --git a/external/docs/content/docs/platform-support/2.47.0.html b/external/docs/content/docs/platform-support/2.47.0.html index ce233d99d6..94fbc582d6 100644 --- a/external/docs/content/docs/platform-support/2.47.0.html +++ b/external/docs/content/docs/platform-support/2.47.0.html @@ -79,7 +79,7 @@

    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 +Policy" in }}">"How to maintain Git" for an overview of which branches are used in the Git project, and how.

  • @@ -191,7 +191,7 @@

    C

    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 +}}">"How to maintain Git" for an overview of how next is used in the Git project.) To do that:

    diff --git a/external/docs/data/docs.yml b/external/docs/data/docs.yml index e91d09d081..12e3482234 100644 --- a/external/docs/data/docs.yml +++ b/external/docs/data/docs.yml @@ -71365,7 +71365,7 @@ pages: removed: 0 platform-support: version-map: - 2.47.0: 16dd48c906456ee4beb3635b7795761fc483363d + 2.47.0: 817d53c8da22db548200fb25ec14c9d0f51cfded latest-changes: 2.47.0 page-versions: - name: 2.47.0