From ef9fc0d308e02ccaf28625e17f4cc19f74d1f308 Mon Sep 17 00:00:00 2001 From: g-samroberts Date: Sun, 7 Jun 2026 15:53:22 -0700 Subject: [PATCH] Add changelog generation guide. --- .gemini/skills/docs-changelog/SKILL.md | 3 +- .../references/changelog-automation.md | 87 +++++++++++++++++++ .github/workflows/release-notes.yml | 2 + 3 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 .gemini/skills/docs-changelog/references/changelog-automation.md diff --git a/.gemini/skills/docs-changelog/SKILL.md b/.gemini/skills/docs-changelog/SKILL.md index a0c0ad8600..203f30560b 100644 --- a/.gemini/skills/docs-changelog/SKILL.md +++ b/.gemini/skills/docs-changelog/SKILL.md @@ -2,7 +2,8 @@ name: docs-changelog description: >- Generates and formats changelog files for a new release based on provided - version and raw changelog data. + version and raw changelog data. For maintenance and troubleshooting help, see + references/changelog-automation.md. --- # Procedure: Updating Changelog for New Releases diff --git a/.gemini/skills/docs-changelog/references/changelog-automation.md b/.gemini/skills/docs-changelog/references/changelog-automation.md new file mode 100644 index 0000000000..6484098269 --- /dev/null +++ b/.gemini/skills/docs-changelog/references/changelog-automation.md @@ -0,0 +1,87 @@ +# Guide to automated release notes maintenance + +This guide is for maintainers and reviewers who manage the automated release +notes generated by Gemini CLI. It covers the architecture of the automation and +provides troubleshooting steps for common issues. + +## Architecture and governance + +The automated release notes process is divided between a GitHub Action and a +Gemini CLI skill. + +### GitHub Action + +The GitHub Action (`.github/workflows/release-notes.yml`) governs the triggering +mechanism and infrastructure. It runs automatically when a release is published +or when manually dispatched. The action is responsible for: + +- Extracting the release **version**, **date**, and **raw notes** from the + GitHub release. +- Passing the extracted information to Gemini CLI. +- Updating changelog pages. +- Creating a pull request with the generated changelog files. + +### docs-changelog skill + +The `docs-changelog` skill governs the actual content generation. It takes the +provided version, date, and raw data, processes it, and updates the markdown +files. It formats the content according to project standards and determines +whether to append to an existing page or create a new one based on the semantic +version. + +Specifically, the skill updates the following pages based on the release +version: + +- **New Minor Stable Versions (e.g., `v1.2.0`):** + - Fully replaces `docs/changelogs/latest.md` with a new highlights section and + the full changelog. + - Prepends a brief announcement summary to `docs/changelogs/index.md`. +- **New Minor Preview Versions (e.g., `v1.3.0-preview.0`):** + - Fully replaces `docs/changelogs/preview.md` with a new highlights section + and the full changelog. +- **Patch Stable Versions (e.g., `v1.2.1`):** + - Edits `docs/changelogs/latest.md` by updating the version header, date, and + "Full Changelog" link, and prepending new "What's Changed" items without + replacing the entire file. +- **Patch Preview Versions (e.g., `v1.3.0-preview.1`):** + - Edits `docs/changelogs/preview.md` similarly to stable patches, updating the + header, date, and link, and appending new items without rewriting the file. +- **Nightly Releases:** + - The skill skips nightly versions entirely and makes no updates. + +## Troubleshooting + +This section covers common issues you might encounter with the automated release +notes and how to resolve them. + +### Skipped minor versions do not create a new entry + +Sometimes new releases skip straight to a minor or patch version, such as +`x.x.1`. In these cases, a new entry is not created. + +The skill expects to update the date and append a line for any new changes to an +existing `x.x.0` page, instead of fully refreshing the page. If the `x.x.0` page +does not exist, the skill cannot append the notes. + +To fix this issue: + +1. Navigate to the **Actions** tab and select the **Generate Release Notes** + workflow. +2. Manually run the action. +3. Copy and paste the version information, but use the `x.x.0` nomenclature (for + example, `1.2.0` instead of `1.2.1`) to force the skill to generate a fresh + page. +4. Once the pull request is created, manually edit the version number in the + generated markdown file to match the correct `x.x.1` version before merging. + +### Pull request contains too many changed files + +Occasionally, the generation process results in a pull request that has too many +changed files. The exact cause of this behavior is unknown. + +To fix this issue: + +1. Go to the Actions run that generated the pull request (this fix also applies + to failed runs). +2. Rerun the action. A fresh run typically resolves the issue and correctly + scopes the file changes to only the changelog. diff --git a/.github/workflows/release-notes.yml b/.github/workflows/release-notes.yml index d516ee928a..1262916a3e 100644 --- a/.github/workflows/release-notes.yml +++ b/.github/workflows/release-notes.yml @@ -97,6 +97,8 @@ jobs: body: | This PR contains the auto-generated changelog for the ${{ steps.release_info.outputs.VERSION }} release. + For troubleshooting the automated release notes, see the [maintenance guide](.gemini/skills/docs-changelog/references/changelog-automation.md). + Please review and merge. Related to #18505