Add changelog generation guide.

.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

.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.

.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