Skip to content

Open a draft documentation PR when code merges to main #1217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dhruv8sh wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Open a draft documentation PR when code merges to main #1217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/docs-pr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 }}"
31 changes: 16 additions & 15 deletions scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<sha>` 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).
Expand Down
72 changes: 72 additions & 0 deletions scripts/open-docs-pr.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <BEFORE_SHA> <AFTER_SHA>
#
# 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 <BEFORE_SHA> <AFTER_SHA>" >&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"
Loading