[dhruv8sh]

Summary

• Stop proposing documentation on every push to main; maintainers start the workflow from the Actions tab and choose what it covers.
• New inputs: branch (default main), since (required; the proposal covers every change after it) and an optional sha (defaults to the branch head). The PR opens against the chosen branch.
• A since that is not an earlier commit of sha now fails the run instead of silently falling back to a single-commit proposal.

Changes

File	Change
.github/workflows/docs-proposal.yml	Drop the push trigger; add branch/since/sha inputs; propose resolves the commit once and validate/publish use that job output
scripts/docs-proposal/lib.sh	Check reachability against origin/$DOCS_PROPOSAL_BRANCH (default main)
scripts/docs-proposal/publish.sh	Open the PR with --base "$DOCS_PROPOSAL_BRANCH"
scripts/docs-proposal/propose.sh	Reject a base that is not an earlier commit; an empty base still defaults to the first parent
scripts/docs-proposal/test.sh	Expect failures for unrelated, all-zero and self bases; cover a non-main branch for reachability and the PR base

Closes

No linked issue.

Spec

Not a feature

Test plan

• cargo test-fastly && cargo test-axum
• cargo clippy-fastly && cargo clippy-axum
• cargo fmt --all -- --check
• JS tests: cd crates/trusted-server-js/lib && npx vitest run
• JS format: cd crates/trusted-server-js/lib && npm run format
• Docs format: cd docs && npm run format
• WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
• Manual testing via fastly compute serve
• Other: scripts/docs-proposal/test.sh passes; propose + validate jobs run with act against local scripts (valid since passes, bad since fails before Copilot runs). Publish was not run with act since it would push and open a real PR; test.sh covers it with a stubbed gh. shellcheck was not run locally.

Checklist

• Feature PRs: spec linked above, ending in a review log of two or more agent review rounds
• Changes follow AGENTS.md conventions
• No unwrap() in production code — use expect("should ...")
• Uses log macros (not println!)
• New code has tests
• No secrets or credentials committed

[ChristianPavilonis]

Summary

This change makes documentation proposals manually dispatched for a chosen branch and commit range, and pins the resolved commit across jobs. The branch selection is not yet reflected in proposal identity, allowing runs for different target branches to overwrite or reuse the same proposal.

Blocking

🔧 wrench

• Scope proposal identity to the target branch — see inline at scripts/docs-proposal/publish.sh:108

Verification

• Reproduced the cross-branch collision using a temporary local Git repository and stubbed GitHub calls: publishing the same SHA for release overwrote the shared proposal branch, edited the existing main PR, and created no release PR.
• The proposed fix has not been applied or tested. No one-click suggestions are included.
• The original checkout and reviewer worktree remain clean.

CI Status

• integration tests (Fastly EC lifecycle): PASS
• integration tests: PASS
• browser integration tests: PASS
• trace runtime and browser acceptance: PASS
• CodeQL: PASS
• Analyze (rust): PASS
• prepare integration artifacts: PASS
• worker-deadlines (cloudflare): PASS
• cargo fmt: PASS (required)
• cargo test (ts CLI, native) (ubuntu-latest): PASS
• Analyze (javascript-typescript): PASS
• CI Node pin guard: PASS
• HTML EOF runtime (Fastly): PASS
• Analyze (actions): PASS
• vitest: PASS
• cargo test (axum native): PASS
• cargo test: PASS (required)
• format-typescript: PASS (required)
• cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• CLAUDE.md symlink guard: PASS
• format-docs: PASS (required)
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• docs-proposal scripts: PASS
• cargo test (cross-adapter parity): PASS
• worker-deadlines (spin): PASS
• cargo test (ts CLI, native) (macos-latest): PASS
• ts dev lint domains (changed lines): PASS
• Analyze (javascript-typescript): PASS
• Analyze (python): PASS

[ChristianPavilonis]

🔧 wrench — Scope proposal identity to the target branch

docs_proposal_branch() still keys proposals only by SHA. When main and release contain the same commit, publishing for release finds the existing main proposal and edits it without changing its base. It can also overwrite that proposal’s generated changes—or skip publication entirely if the original PR is closed.

Verified with a temporary local Git repository and stubbed GitHub calls: the release run overwrote the shared proposal branch, edited the main PR, and created no release PR.

Proposed fix: include the target branch in proposal identity, preserving existing names for main:

docs_proposal_branch() {
  if [ "$DOCS_PROPOSAL_BRANCH" = main ]; then
    printf 'docs/auto/%s\n' "${1:0:12}"
  else
    local branch_hash
    branch_hash="$(printf '%s' "$DOCS_PROPOSAL_BRANCH" | git hash-object --stdin)"
    printf 'docs/auto/%s/%s\n' "$branch_hash" "${1:0:12}"
  fi
}

Update the release test’s expected branch and add coverage publishing the same SHA against both branches.

Apply manually — the helper is outside the diff hunks, and regression coverage requires separate edits. Proposed fix not yet tested.