From 53691bf8f01c4702d09c4df07cde99bab4d60367 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:41:20 +0900 Subject: [PATCH 01/12] bisect: add docs.yml alone to a known-green ci.yml --- .github/workflows/docs.yml | 85 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..09dbf6d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,85 @@ +name: Docs + +on: + push: + branches: [main] + # The generated pages under docs/ are what a CLI change moves, and the + # `rust` job of CI fails until they are regenerated in the same commit, so + # a change that alters `--help` reaches this filter as a docs/ change. + paths: + - docs/** + - spec/** + - tools/gen_docs.py + - .github/workflows/docs.yml + # No path filter here: `docs` is a required status check, so it has to run on + # every pull request rather than only on the ones that touch the book. + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: docs-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +env: + CARGO_TERM_COLOR: always + +jobs: + docs: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false + - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable + - uses: taiki-e/install-action@b6ff580856c41316412a0b9b60540fbc6f8c82cc # v2 + with: + # Pinned: mdBook decides the rendered HTML, so an unpinned tool would + # let the published site change under a commit that touched nothing. + tool: mdbook@0.5.4 + - run: cargo build --manifest-path rust/Cargo.toml --locked -p ocomment + # The site may not restate anything the binary or spec/ no longer says. + - run: python3 tools/gen_docs.py --check + - run: mdbook build docs + # `create-missing = false` in docs/book.toml makes the build above fail on + # a SUMMARY entry with no file behind it, so this only has to catch the + # opposite: a chapter that was written and never linked from SUMMARY.md. + - name: Every page under docs/ is in the book + run: | + set -euo pipefail + status=0 + for page in docs/*.md; do + name=$(basename "$page") + if [ "$name" = "SUMMARY.md" ]; then continue; fi + if ! grep -q "($name)" docs/SUMMARY.md; then + echo "::error file=docs/SUMMARY.md::${name} is not listed in docs/SUMMARY.md" + status=1 + fi + done + exit "$status" + - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5 + with: + path: target/book + + deploy-pages: + # Pages serves one site, so a deploy is never cancelled halfway and never + # races another: this group is deliberately separate from the workflow's. + concurrency: + group: pages + cancel-in-progress: false + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: docs + runs-on: ubuntu-latest + timeout-minutes: 10 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + permissions: + pages: write # Publish the built book as this repository's Pages site. + id-token: write # Prove to the Pages API which workflow run is deploying. + steps: + - id: deployment + uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5 From 11a0bf628b52ff48d00091957ce6c9714cf1f606 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:44:55 +0900 Subject: [PATCH 02/12] bisect: drop deploy-pages job --- .github/workflows/docs.yml | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 09dbf6d..77cbd2f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -63,23 +63,3 @@ jobs: - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5 with: path: target/book - - deploy-pages: - # Pages serves one site, so a deploy is never cancelled halfway and never - # races another: this group is deliberately separate from the workflow's. - concurrency: - group: pages - cancel-in-progress: false - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - needs: docs - runs-on: ubuntu-latest - timeout-minutes: 10 - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - permissions: - pages: write # Publish the built book as this repository's Pages site. - id-token: write # Prove to the Pages API which workflow run is deploying. - steps: - - id: deployment - uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5 From e75f53cd151ccd3983be25ad2ffeab031b89ff58 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:46:28 +0900 Subject: [PATCH 03/12] bisect: drop upload-pages-artifact step --- .github/workflows/docs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 77cbd2f..291c529 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -60,6 +60,3 @@ jobs: fi done exit "$status" - - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5 - with: - path: target/book From c53f1ba3c1e84fca00665cf8889000663ebe163d Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:47:57 +0900 Subject: [PATCH 04/12] bisect: drop install-action step --- .github/workflows/docs.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 291c529..05830a7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,11 +35,6 @@ jobs: with: persist-credentials: false - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable - - uses: taiki-e/install-action@b6ff580856c41316412a0b9b60540fbc6f8c82cc # v2 - with: - # Pinned: mdBook decides the rendered HTML, so an unpinned tool would - # let the published site change under a commit that touched nothing. - tool: mdbook@0.5.4 - run: cargo build --manifest-path rust/Cargo.toml --locked -p ocomment # The site may not restate anything the binary or spec/ no longer says. - run: python3 tools/gen_docs.py --check From d8fe95ac3ec227248dabf8c2bb346c42716b2983 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:49:56 +0900 Subject: [PATCH 05/12] bisect: re-add install-action with plain tool --- .github/workflows/docs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 05830a7..96a955c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,6 +35,9 @@ jobs: with: persist-credentials: false - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable + - uses: taiki-e/install-action@b6ff580856c41316412a0b9b60540fbc6f8c82cc # v2 + with: + tool: mdbook - run: cargo build --manifest-path rust/Cargo.toml --locked -p ocomment # The site may not restate anything the binary or spec/ no longer says. - run: python3 tools/gen_docs.py --check From fd6f8fa9869602659f964e1466d307e601f8a0db Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:51:30 +0900 Subject: [PATCH 06/12] bisect: install-action@v2 tag ref --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 96a955c..9ef9b13 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,7 +35,7 @@ jobs: with: persist-credentials: false - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable - - uses: taiki-e/install-action@b6ff580856c41316412a0b9b60540fbc6f8c82cc # v2 + - uses: taiki-e/install-action@v2 with: tool: mdbook - run: cargo build --manifest-path rust/Cargo.toml --locked -p ocomment From 96e64ecdbd07fabcd9da8162b865d65471186af3 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:54:09 +0900 Subject: [PATCH 07/12] bisect: replace install-action with setup-python --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9ef9b13..bb53226 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,7 +35,7 @@ jobs: with: persist-credentials: false - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable - - uses: taiki-e/install-action@v2 + - uses: actions/setup-python@v5 with: tool: mdbook - run: cargo build --manifest-path rust/Cargo.toml --locked -p ocomment From 758d6f41ee0990b0e66f3b9138ab6ce6f4cb79fb Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:57:21 +0900 Subject: [PATCH 08/12] bisect: bare setup-python, no with --- .github/workflows/docs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bb53226..ae23d4d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -36,8 +36,6 @@ jobs: persist-credentials: false - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable - uses: actions/setup-python@v5 - with: - tool: mdbook - run: cargo build --manifest-path rust/Cargo.toml --locked -p ocomment # The site may not restate anything the binary or spec/ no longer says. - run: python3 tools/gen_docs.py --check From d34a7d072a536df9cc757b77da5ac37c79aff433 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 08:08:51 +0900 Subject: [PATCH 09/12] bisect: scratch probe workflow --- .github/workflows/scratch.yml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .github/workflows/scratch.yml diff --git a/.github/workflows/scratch.yml b/.github/workflows/scratch.yml new file mode 100644 index 0000000..9866e43 --- /dev/null +++ b/.github/workflows/scratch.yml @@ -0,0 +1,18 @@ +name: Scratch + +on: + pull_request: + +permissions: + contents: read + +jobs: + probe: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false + - uses: actions/setup-python@v5 + - run: python3 --version From 70a4649dbe47615d162258221431f40ed567cf4d Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 08:10:08 +0900 Subject: [PATCH 10/12] bisect: scratch checkout@v4 tag --- .github/workflows/scratch.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/scratch.yml b/.github/workflows/scratch.yml index 9866e43..12b0007 100644 --- a/.github/workflows/scratch.yml +++ b/.github/workflows/scratch.yml @@ -14,5 +14,5 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 with: persist-credentials: false - - uses: actions/setup-python@v5 + - uses: actions/checkout@v4 - run: python3 --version From 913e1dcc94225acd563747f926acfb0b2e337f50 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 08:11:14 +0900 Subject: [PATCH 11/12] bisect: scratch setup-python@sha --- .github/workflows/scratch.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/scratch.yml b/.github/workflows/scratch.yml index 12b0007..1a51698 100644 --- a/.github/workflows/scratch.yml +++ b/.github/workflows/scratch.yml @@ -14,5 +14,5 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 with: persist-credentials: false - - uses: actions/checkout@v4 + - uses: actions/setup-python@751276eafca55f10f252026015f43c488f2322ba - run: python3 --version From 984d41248209f6125cd9e944fff35043e5b18205 Mon Sep 17 00:00:00 2001 From: Yasunobu <42543015+P4suta@users.noreply.github.com> Date: Fri, 28 Aug 2026 08:12:27 +0900 Subject: [PATCH 12/12] bisect: scratch install-action@sha --- .github/workflows/scratch.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/scratch.yml b/.github/workflows/scratch.yml index 1a51698..5d71918 100644 --- a/.github/workflows/scratch.yml +++ b/.github/workflows/scratch.yml @@ -14,5 +14,5 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 with: persist-credentials: false - - uses: actions/setup-python@751276eafca55f10f252026015f43c488f2322ba + - uses: taiki-e/install-action@37f7c5781271959fb65b6b35224e28652ff2b63d - run: python3 --version