Docs Changelog

1---2name: docs-changelog3description: >-4  Generates and formats changelog files for a new release based on provided5  version and raw changelog data.6---7 8# Procedure: Updating Changelog for New Releases9 10## Objective11 12To standardize the process of updating changelog files (`latest.md`,13`preview.md`, `index.md`) based on automated release information.14 15## Inputs16 17- **version**: The release version string (e.g., `v0.28.0`,18  `v0.29.0-preview.2`).19- **TIME**: The release timestamp (e.g., `2026-02-12T20:33:15Z`).20- **BODY**: The raw markdown release notes, containing a "What's Changed"21  section and a "Full Changelog" link.22 23## Guidelines for `latest.md` and `preview.md` Highlights24 25- Aim for **3-5 key highlight points**.26- Each highlight point must start with a bold-typed title that summarizes the27  change (e.g., `**New Feature:** A brief description...`).28- **Prioritize** summarizing new features over other changes like bug fixes or29  chores.30- **Avoid** mentioning features that are "experimental" or "in preview" in31  Stable Releases.32- **DO NOT** include PR numbers, links, or author names in these highlights.33- Refer to `.gemini/skills/docs-changelog/references/highlights_examples.md`34  for the correct style and tone.35 36## Initial Processing37 381.  **Analyze Version**: Determine the release path based on the `version`39    string.40    - If `version` contains "nightly", **STOP**. No changes are made.41    - If `version` ends in `.0`, follow the **Path A: New Minor Version**42      procedure.43    - If `version` does not end in `.0`, follow the **Path B: Patch Version**44      procedure.452.  **Process Time**: Convert the `TIME` input into two formats for later use:46    `yyyy-mm-dd` and `Month dd, yyyy`.473.  **Process Body**:48    - Save the incoming `BODY` content to a temporary file for processing.49    - In the "What's Changed" section of the temporary file, reformat all pull50      request URLs to be markdown links with the PR number as the text (e.g.,51      `[#12345](URL)`).52    - If a "New Contributors" section exists, delete it.53    - Preserve the "**Full Changelog**" link. The processed content of this54      temporary file will be used in subsequent steps.55 56---57 58## Path A: New Minor Version59 60*Use this path if the version number ends in `.0`.*61 62**Important:** Based on the version, you must choose to follow either section63A.1 for stable releases or A.2 for preview releases. Do not follow the64instructions for the other section.65 66### A.1: Stable Release (e.g., `v0.28.0`)67 68For a stable release, you will generate two distinct summaries from the69changelog: a concise **announcement** for the main changelog page, and a more70detailed **highlights** section for the release-specific page.71 721.  **Create the Announcement for `index.md`**:73    -   Generate a concise announcement summarizing the most important changes.74        Each announcement entry must start with a bold-typed title that75        summarizes the change.76    -   **Important**: The format for this announcement is unique. You **must**77        use the existing announcements in `docs/changelogs/index.md` and the78        example within79        `.gemini/skills/docs-changelog/references/index_template.md` as your80        guide. This format includes PR links and authors. Stick to 1 or 2 PR81        links and authors.82    -   Add this new announcement to the top of `docs/changelogs/index.md`.83 842.  **Create Highlights and Update `latest.md`**:85    -   Generate a comprehensive "Highlights" section, following the guidelines86        in the "Guidelines for `latest.md` and `preview.md` Highlights" section87        above.88    -   Take the content from89        `.gemini/skills/docs-changelog/references/latest_template.md`.90    -   Populate the template with the `version`, `release_date`, generated91        `highlights`, and the processed content from the temporary file.92    -   **Completely replace** the contents of `docs/changelogs/latest.md` with93        the populated template.94 95### A.2: Preview Release (e.g., `v0.29.0-preview.0`)96 971.  **Update `preview.md`**:98    -   Generate a comprehensive "Highlights" section, following the highlight99        guidelines.100    -   Take the content from101        `.gemini/skills/docs-changelog/references/preview_template.md`.102    -   Populate the template with the `version`, `release_date`, generated103        `highlights`, and the processed content from the temporary file.104    -   **Completely replace** the contents of `docs/changelogs/preview.md`105        with the populated template.106 107---108 109## Path B: Patch Version110 111*Use this path if the version number does **not** end in `.0`.*112 113**Important:** Based on the version, you must choose to follow either section114B.1 for stable patches or B.2 for preview patches. Do not follow the115instructions for the other section.116 117### B.1: Stable Patch (e.g., `v0.28.1`)118 119- **Target File**: `docs/changelogs/latest.md`120- Perform the following edits on the target file:121    1.  Update the version in the main header. The line should read,122        `# Latest stable release: {{version}}`123    2.  Update the rease date. The line should read,124        `Released: {{release_date_month_dd_yyyy}}`125    3.  Determine if a "What's Changed" section exists in the temporary file126        If so, continue to step 4. Otherwise, skip to step 5.127    4.  **Prepend** the processed "What's Changed" list from the temporary file128        to the existing "What's Changed" list in `latest.md`. Do not change or129        replace the existing list, **only add** to the beginning of it.130    5.  In the "Full Changelog", edit **only** the end of the URL. Identify the131        last part of the URL that looks like `...{previous_version}` and update132        it to be `...{version}`.133 134        Example: assume the patch version is `v0.29.1`. Change135        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0`136        to137        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.1`138 139### B.2: Preview Patch (e.g., `v0.29.0-preview.3`)140 141- **Target File**: `docs/changelogs/preview.md`142- Perform the following edits on the target file:143    1.  Update the version in the main header. The line should read,144        `# Preview release: {{version}}`145    2.  Update the rease date. The line should read,146        `Released: {{release_date_month_dd_yyyy}}`147    3.  Determine if a "What's Changed" section exists in the temporary file148        If so, continue to step 4. Otherwise, skip to step 5.149    4.  **Prepend** the processed "What's Changed" list from the temporary file150        to the existing "What's Changed" list in `preview.md`. Do not change or151        replace the existing list, **only add** to the beginning of it.152    5.  In the "Full Changelog", edit **only** the end of the URL. Identify the153        last part of the URL that looks like `...{previous_version}` and update154        it to be `...{version}`.155 156        Example: assume the patch version is `v0.29.0-preview.1`. Change157        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0-preview.0`158        to159        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0-preview.1`160 161---162 163## Finalize164 165- After making changes, if `npm run format` fails, it may be necessary to run166  `npm install` first to ensure all formatting dependencies are available.167  Then, run `npm run format` to ensure consistency.168- Delete any temporary files created during the process.