docs-changelog

---
name: docs-changelog
description: >-
license: Apache-2.0
---

# Procedure: Updating Changelog for New Releases

## Objective

To standardize the process of updating changelog files (`latest.md`,
`preview.md`, `index.md`) based on automated release information.

## Inputs

- **version**: The release version string (e.g., `v0.28.0`,
  `v0.29.0-preview.2`).
- **TIME**: The release timestamp (e.g., `2026-02-12T20:33:15Z`).
- **BODY**: The raw markdown release notes, containing a "What's Changed"
  section and a "Full Changelog" link.

## Guidelines for `latest.md` and `preview.md` Highlights

- Aim for **3-5 key highlight points**.
- Each highlight point must start with a bold-typed title that summarizes the
  change (e.g., `**New Feature:** A brief description...`).
- **Prioritize** summarizing new features over other changes like bug fixes or
  chores.
- **Avoid** mentioning features that are "experimental" or "in preview" in
  Stable Releases.
- **DO NOT** include PR numbers, links, or author names in these highlights.
- Refer to `.gemini/skills/docs-changelog/references/highlights_examples.md`
  for the correct style and tone.

## Initial Processing

1.  **Analyze Version**: Determine the release path based on the `version`
    string.
    - If `version` contains "nightly", **STOP**. No changes are made.
    - If `version` ends in `.0`, follow the **Path A: New Minor Version**
      procedure.
    - If `version` does not end in `.0`, follow the **Path B: Patch Version**
      procedure.
2.  **Process Time**: Convert the `TIME` input into two formats for later use:
    `yyyy-mm-dd` and `Month dd, yyyy`.
3.  **Process Body**:
    - Save the incoming `BODY` content to a temporary file for processing.
    - In the "What's Changed" section of the temporary file, reformat all pull
      request URLs to be markdown links with the PR number as the text (e.g.,
      `[#12345](URL)`).
    - If a "New Contributors" section exists, delete it.
    - Preserve the "**Full Changelog**" link. The processed content of this
      temporary file will be used in subsequent steps.

---

## Path A: New Minor Version

*Use this path if the version number ends in `.0`.*

**Important:** Based on the version, you must choose to follow either section
A.1 for stable releases or A.2 for preview releases. Do not follow the
instructions for the other section.

### A.1: Stable Release (e.g., `v0.28.0`)

For a stable release, you will generate two distinct summaries from the
changelog: a concise **announcement** for the main changelog page, and a more
detailed **highlights** section for the release-specific page.

1.  **Create the Announcement for `index.md`**:
    -   Generate a concise announcement summarizing the most important changes.
        Each announcement entry must start with a bold-typed title that
        summarizes the change.
    -   **Important**: The format for this announcement is unique. You **must**
        use the existing announcements in `docs/changelogs/index.md` and the
        example within
        `.gemini/skills/docs-changelog/references/index_template.md` as your
        guide. This format includes PR links and authors. Stick to 1 or 2 PR
        links and authors.
    -   Add this new announcement to the top of `docs/changelogs/index.md`.

2.  **Create Highlights and Update `latest.md`**:
    -   Generate a comprehensive "Highlights" section, following the guidelines
        in the "Guidelines for `latest.md` and `preview.md` Highlights" section
        above.
    -   Take the content from
        `.gemini/skills/docs-changelog/references/latest_template.md`.
    -   Populate the template with the `version`, `release_date`, generated
        `highlights`, and the processed content from the temporary file.
    -   **Completely replace** the contents of `docs/changelogs/latest.md` with
        the populated template.

### A.2: Preview Release (e.g., `v0.29.0-preview.0`)

1.  **Update `preview.md`**:
    -   Generate a comprehensive "Highlights" section, following the highlight
        guidelines.
    -   Take the content from
        `.gemini/skills/docs-changelog/references/preview_template.md`.
    -   Populate the template with the `version`, `release_date`, generated
        `highlights`, and the processed content from the temporary file.
    -   **Completely replace** the contents of `docs/changelogs/preview.md`
        with the populated template.

---

## Path B: Patch Version

*Use this path if the version number does **not** end in `.0`.*

**Important:** Based on the version, you must choose to follow either section
B.1 for stable patches or B.2 for preview patches. Do not follow the
instructions for the other section.

### B.1: Stable Patch (e.g., `v0.28.1`)

- **Target File**: `docs/changelogs/latest.md`
- Perform the following edits on the target file:
    1.  Update the version in the main header. The line should read,
        `# Latest stable release: {{version}}`
    2.  Update the rease date. The line should read,
        `Released: {{release_date_month_dd_yyyy}}`
    3.  Determine if a "What's Changed" section exists in the temporary file
        If so, continue to step 4. Otherwise, skip to step 5.
    4.  **Prepend** the processed "What's Changed" list from the temporary file
        to the existing "What's Changed" list in `latest.md`. Do not change or
        replace the existing list, **only add** to the beginning of it.
    5.  In the "Full Changelog", edit **only** the end of the URL. Identify the
        last part of the URL that looks like `...{previous_version}` and update
        it to be `...{version}`.

        Example: assume the patch version is `v0.29.1`. Change
        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0`
        to
        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.1`

### B.2: Preview Patch (e.g., `v0.29.0-preview.3`)

- **Target File**: `docs/changelogs/preview.md`
- Perform the following edits on the target file:
    1.  Update the version in the main header. The line should read,
        `# Preview release: {{version}}`
    2.  Update the rease date. The line should read,
        `Released: {{release_date_month_dd_yyyy}}`
    3.  Determine if a "What's Changed" section exists in the temporary file
        If so, continue to step 4. Otherwise, skip to step 5.
    4.  **Prepend** the processed "What's Changed" list from the temporary file
        to the existing "What's Changed" list in `preview.md`. Do not change or
        replace the existing list, **only add** to the beginning of it.
    5.  In the "Full Changelog", edit **only** the end of the URL. Identify the
        last part of the URL that looks like `...{previous_version}` and update
        it to be `...{version}`.

        Example: assume the patch version is `v0.29.0-preview.1`. Change
        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0-preview.0`
        to
        `Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0-preview.1`

---

## Finalize

- After making changes, if `npm run format` fails, it may be necessary to run
  `npm install` first to ensure all formatting dependencies are available.
  Then, run `npm run format` to ensure consistency.
- Delete any temporary files created during the process.