Skip to content

changelog.md

Latest commit

 

History

History
112 lines (76 loc) · 4.27 KB

changelog.md

File metadata and controls

112 lines (76 loc) · 4.27 KB
Raw

Automated changelog generation

When a version bump PR merges on Lightprotocol/light-protocol, a GitHub Action generates a Mintlify <Update> changelog entry and opens a PR on this docs repo.

The real changes are in the ~20 PRs merged between consecutive version bumps (fixes, features, security items), not in the bump PR itself.

How it works

  1. Trigger: repository_dispatch from light-protocol after release, or manual workflow_dispatch with PR number
  2. Context fetch: bash step fetches the release PR body and all inter-release PRs via gh CLI
  3. Generation: claude-code-action@v1 reads the context, categorizes PRs, and writes a new <Update> entry in changelog.mdx
  4. PR creation: peter-evans/create-pull-request@v5 opens a PR for human review

Triggers

Trigger When Payload
repository_dispatch type new-release Automated: light-protocol sends after release { pr_number, version, commit }
workflow_dispatch Manual fallback Paste the bump PR number (e.g. 2293)

Release patterns

PR Labels Generated by
#2272 [release] create-release-pr.sh (automated, body has old -> new versions)
#2293 none publish-local.sh (manual, body has only new versions)

Individual release tags (e.g., light-sdk-v0.22.0) have empty bodies. The workflow reads the bump PR to find versions and the inter-release PRs for actual changes.

Context fetching

The bash step fetches four things:

  1. Release PR body -> /tmp/release-pr.json (version bump list, merge date)
  2. Primary version — extracts light-sdk version as canonical (e.g., 0.22.0). Falls back to first crate listed.
  3. Previous bump PR merge date — most recent merged PR with "bump" in the title before this one. Falls back to epoch if none found.
  4. Inter-release PRs -> /tmp/inter-release-prs.json — all PRs merged between the two bump dates, excluding bump PRs

Claude prompt design

Claude receives the context files and changelog.mdx. It:

  1. Categorizes PRs:

    • Security: titles with (L-xx), (M-xx), (H-xx) suffixes (audit findings)
    • Features: feat: prefix
    • Fixes: fix: prefix
    • Refactors: refactor: prefix
    • Skips chore: / test: from highlights (keeps them in the table)

  2. Selects tags from: SDK, Programs, Security, Token, Tooling

  3. Writes the <Update> block:

<Update label="{Month Year}" description="v{version}" tags={["SDK", "Security"]}>

### Highlights

- 3-5 terse bullets, most important first
- Link PR numbers: [#123](https://github.com/Lightprotocol/light-protocol/pull/123)

### Breaking changes

(only if applicable, otherwise omitted)

### All changes

| PR | Description |
|:---|:------------|
| [#xxx](link) | one-line description |

</Update>
  1. Inserts after frontmatter, before existing entries

Style rules

  • No promotional language ("exciting", "comprehensive", "enables")
  • Imperative mood ("fix", "add", "reject" — not "fixed", "added")
  • One sentence per bullet, max 15 words
  • Sentence case headings
  • Drop fix: / feat: prefixes in table descriptions

Constraints

  • --max-turns 10 prevents runaway
  • --model claude-sonnet-4-5-20250929
  • Restricted tools: Read, Edit, Bash

Secrets

Secret Repo Purpose
ANTHROPIC_API_KEY docs repo Claude Code API
GITHUB_TOKEN docs repo (auto) Read public light-protocol PRs
DOCS_DISPATCH_TOKEN light-protocol repo POST repository_dispatch to docs repo

Edge cases

  1. No inter-release PRs (pr_count=0): Claude and PR creation steps skip via if condition
  2. Manual release (no dispatch): use workflow_dispatch with PR number
  3. PR body format differs: regex handles both X.Y.Z -> A.B.C and crate: A.B.C
  4. No previous bump PR found: falls back to epoch, captures all history
  5. Duplicate runs: branch name includes version (changelog/v0.22.0), re-run updates the same PR

Testing

  1. Manually trigger workflow_dispatch with PR 2293
  2. Check the generated PR edits changelog.mdx correctly
  3. Run npm run format:check && npm run lint && npm run spellcheck on the branch
  4. Verify the <Update> block renders in Mintlify preview