From c3e15bf4925ce28b7bbd6ebb42539ad651ee340d Mon Sep 17 00:00:00 2001 From: dhruv8sh Date: Mon, 28 Sep 2026 18:34:41 +0530 Subject: [PATCH] Open a draft documentation PR when code merges to main Each push to main that changes more than Markdown runs scripts/open-docs-pr.sh, which pushes a docs/ branch with one empty commit and opens a draft PR linking the source PR and listing the files it changed. Closes #1105. Signed-off-by: dhruv8sh --- .github/workflows/docs-pr.yml | 30 +++++++++++++++ scripts/README.md | 31 +++++++-------- scripts/open-docs-pr.sh | 72 +++++++++++++++++++++++++++++++++++ 3 files changed, 118 insertions(+), 15 deletions(-) create mode 100644 .github/workflows/docs-pr.yml create mode 100755 scripts/open-docs-pr.sh diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml new file mode 100644 index 000000000..bd95653be --- /dev/null +++ b/.github/workflows/docs-pr.yml @@ -0,0 +1,30 @@ +name: Open docs PR + +# Opens a draft documentation pull request for each code merge to main. +# Documentation-only merges are skipped. +on: + push: + branches: [main] + paths-ignore: + - "docs/**" + - "**.md" + +permissions: + contents: read + +jobs: + open-docs-pr: + name: Open draft documentation PR + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Open draft documentation PR + env: + GH_TOKEN: ${{ github.token }} + run: ./scripts/open-docs-pr.sh "${{ github.event.before }}" "${{ github.sha }}" diff --git a/scripts/README.md b/scripts/README.md index ad4ecf926..b87810439 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -3,21 +3,22 @@ Run these scripts from the repository root. They fail on command errors unless their documented orchestration handles a probe deliberately. -| Script | Inputs and prerequisites | Side effects and cleanup | -| ----------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `batch-sync.sh` | Endpoint, bearer token, EC ID, partner UID; `curl` and Python | Sends one authenticated batch-sync request. Its temporary response file is removed on exit. | -| `benchmark.sh` | A running server; `curl`, `bc`, and optionally `hey` | May install `hey` through Homebrew. `--save` writes under `benchmark-results/`; it does not stop the server. | -| `profile.sh` | Fastly CLI, Rust WASM target, `curl`; endpoint and request options | Builds and starts the Fastly app, stops the owned process, and retains a profile under `benchmark-results/profiles/`. `--open` launches the local viewer. | -| `generate-integration-viceroy-configs.sh` | Rust toolchain; optional origin port and artifact directory | Builds the native generator and writes Viceroy config under `target/integration-test-artifacts/`; generated files persist. | -| `integration-tests.sh` | Docker, Viceroy, Rust WASM target, pinned Node | Builds WASM/native artifacts and two Docker images, generates Viceroy config, and runs native integration tests serially. Build products and images persist. | -| `integration-tests-browser.sh` | The integration prerequisites plus npm and Playwright | Installs package/browser dependencies, builds fixtures and images, runs both browser suites, and stops matching test containers on exit. Build and npm artifacts persist. | -| `smoke-axum.sh` | `cargo`, `curl`, Python | Uses an isolated temporary config/store and stub origin; stops owned processes and removes its workspace. | -| `smoke-fastly.sh` | Fastly CLI, `cargo`, `curl`, Python | Uses an isolated Fastly project and application config; stops owned processes and removes its workspace. | -| `smoke-cloudflare.sh` | Pinned Wrangler, `cargo`, `curl`, `jq`, and Python | Uses isolated Wrangler manifests, KV state, ports, and logs; stops owned processes and removes its workspace. | -| `smoke-spin.sh` | Spin CLI, `cargo`, `curl`, and Python | Uses an isolated Spin manifest and SQLite KV store; stops owned processes and removes its workspace. | -| `smoke-common.sh` | Sourced by the four smoke scripts | Defines bounded port, process, config, secret, and response assertions. Do not invoke it as a standalone smoke. | -| `template-cache-local-test.sh` | Viceroy, Node, OpenSSL, `curl`, `lsof`; optional ports and mode | Builds local artifacts, generates certificates and fixtures in a temporary directory, stops owned servers, and removes the directory. | -| `test-cli.sh` | Rustup and the host toolchain; optional host triple | May install the selected Rust target, then runs native CLI and browser-audit tests. Cargo artifacts persist. | +| Script | Inputs and prerequisites | Side effects and cleanup | +| ----------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `batch-sync.sh` | Endpoint, bearer token, EC ID, partner UID; `curl` and Python | Sends one authenticated batch-sync request. Its temporary response file is removed on exit. | +| `benchmark.sh` | A running server; `curl`, `bc`, and optionally `hey` | May install `hey` through Homebrew. `--save` writes under `benchmark-results/`; it does not stop the server. | +| `open-docs-pr.sh` | Before and after commit SHAs, `GH_TOKEN`, `GITHUB_REPOSITORY`; `git` and `gh` | Pushes a `docs/` branch with one empty commit and opens a draft PR listing the merged changes. `DRY_RUN=1` prints the PR instead. Used by the Open docs PR workflow. | +| `profile.sh` | Fastly CLI, Rust WASM target, `curl`; endpoint and request options | Builds and starts the Fastly app, stops the owned process, and retains a profile under `benchmark-results/profiles/`. `--open` launches the local viewer. | +| `generate-integration-viceroy-configs.sh` | Rust toolchain; optional origin port and artifact directory | Builds the native generator and writes Viceroy config under `target/integration-test-artifacts/`; generated files persist. | +| `integration-tests.sh` | Docker, Viceroy, Rust WASM target, pinned Node | Builds WASM/native artifacts and two Docker images, generates Viceroy config, and runs native integration tests serially. Build products and images persist. | +| `integration-tests-browser.sh` | The integration prerequisites plus npm and Playwright | Installs package/browser dependencies, builds fixtures and images, runs both browser suites, and stops matching test containers on exit. Build and npm artifacts persist. | +| `smoke-axum.sh` | `cargo`, `curl`, Python | Uses an isolated temporary config/store and stub origin; stops owned processes and removes its workspace. | +| `smoke-fastly.sh` | Fastly CLI, `cargo`, `curl`, Python | Uses an isolated Fastly project and application config; stops owned processes and removes its workspace. | +| `smoke-cloudflare.sh` | Pinned Wrangler, `cargo`, `curl`, `jq`, and Python | Uses isolated Wrangler manifests, KV state, ports, and logs; stops owned processes and removes its workspace. | +| `smoke-spin.sh` | Spin CLI, `cargo`, `curl`, and Python | Uses an isolated Spin manifest and SQLite KV store; stops owned processes and removes its workspace. | +| `smoke-common.sh` | Sourced by the four smoke scripts | Defines bounded port, process, config, secret, and response assertions. Do not invoke it as a standalone smoke. | +| `template-cache-local-test.sh` | Viceroy, Node, OpenSSL, `curl`, `lsof`; optional ports and mode | Builds local artifacts, generates certificates and fixtures in a temporary directory, stops owned servers, and removes the directory. | +| `test-cli.sh` | Rustup and the host toolchain; optional host triple | May install the selected Rust target, then runs native CLI and browser-audit tests. Cargo artifacts persist. | The four adapter smoke contracts are documented in the [deployment guides](../docs/guide/integrations-overview.md#adapter-support). diff --git a/scripts/open-docs-pr.sh b/scripts/open-docs-pr.sh new file mode 100755 index 000000000..fd0032446 --- /dev/null +++ b/scripts/open-docs-pr.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +# +# Open a draft documentation pull request for code merged to main. +# +# The PR starts from the merged commit with one empty commit, so there is a +# branch to push documentation updates to. Its body links the source PR and +# lists the files the merge changed. +# +# Usage: scripts/open-docs-pr.sh +# +# Environment: +# GH_TOKEN token allowed to push branches and open pull requests +# GITHUB_REPOSITORY owner/name of the repository +# DRY_RUN=1 print the branch, title, and body instead of pushing +# +set -euo pipefail + +if [ "$#" -ne 2 ]; then + echo "usage: $0 " >&2 + exit 2 +fi + +BEFORE_SHA="$1" +AFTER_SHA="$2" +: "${GITHUB_REPOSITORY:?GITHUB_REPOSITORY must be set}" +MAX_LISTED_FILES=100 + +SHORT_SHA="$(git rev-parse --short=7 "$AFTER_SHA")" +BRANCH="docs/$SHORT_SHA" +SUBJECT="$(git log -1 --format=%s "$AFTER_SHA")" + +# A push that creates the branch reports an all-zero BEFORE_SHA; fall back to +# the merged commit's own changes. +if git cat-file -e "${BEFORE_SHA}^{commit}" 2>/dev/null; then + CHANGED_FILES="$(git diff --name-only "$BEFORE_SHA" "$AFTER_SHA")" +else + CHANGED_FILES="$(git diff-tree --no-commit-id --name-only -r "$AFTER_SHA")" +fi +CHANGED_COUNT="$(printf '%s\n' "$CHANGED_FILES" | grep -c . || true)" + +SOURCE_PR="$(gh api "repos/$GITHUB_REPOSITORY/commits/$AFTER_SHA/pulls" --jq '.[0].number // empty' 2>/dev/null || true)" +if [ -n "$SOURCE_PR" ]; then + SOURCE="#$SOURCE_PR ($SHORT_SHA)" +else + SOURCE="$SHORT_SHA" +fi + +TITLE="Update documentation for $SUBJECT" +BODY="$( + echo "Code merged to \`main\` in $SOURCE. Push documentation updates for that change to this branch, or close this PR if none are needed." + echo + echo "Changed files ($CHANGED_COUNT):" + echo + # The backticks are literal Markdown, not command substitution. + # shellcheck disable=SC2016 + printf '%s\n' "$CHANGED_FILES" | head -n "$MAX_LISTED_FILES" | sed 's/.*/- `&`/' + if [ "$CHANGED_COUNT" -gt "$MAX_LISTED_FILES" ]; then + echo "- … and $((CHANGED_COUNT - MAX_LISTED_FILES)) more" + fi +)" + +if [ "${DRY_RUN:-0}" = "1" ]; then + printf 'branch: %s\ntitle: %s\n\n%s\n' "$BRANCH" "$TITLE" "$BODY" + exit 0 +fi + +git switch --create "$BRANCH" "$AFTER_SHA" +git -c user.name="github-actions[bot]" \ + -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \ + commit --allow-empty --message "$TITLE" +git push origin "$BRANCH" +gh pr create --draft --base main --head "$BRANCH" --title "$TITLE" --body "$BODY"