Docs Changelog

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.

Highlights example 1

• Plan Mode Enhancements: Significant updates to Plan Mode, including new

commands, support for MCP servers, integration of planning artifacts, and improved iteration guidance.

• Core Agent Improvements: Enhancements to the core agent, including better

system prompt rigor, improved subagent definitions, and enhanced tool execution limits.

• CLI UX/UI Updates: Various UI and UX improvements, such as autocomplete in

the input prompt, updated approval mode labels, DevTools integration, and improved header spacing.

• Tooling & Extension Updates: Improvements to existing tools like

ask_user and grep_search, and new features for extension management.

• Bug Fixes: Numerous bug fixes across the CLI and core, addressing issues

with interactive commands, memory leaks, permission checks, and more.

• Context and Tool Output Management: Features for observation masking for

tool outputs, session-linked tool output storage, and persistence for masked tool outputs.

Highlights example 2

• Commands & UX Enhancements: Introduced /prompt-suggest command,

alongside updated undo/redo keybindings and automatic theme switching.

• Expanded IDE Support: Now offering compatibility with Positron IDE,

expanding integration options for developers.

• Enhanced Security & Authentication: Implemented interactive and

non-interactive OAuth consent, improving both security and diagnostic capabilities for bug reports.

• Advanced Planning & Agent Tools: Integrated a generic Checklist component

for structured task management and evolved subagent capabilities with dynamic policy registration.

• Improved Core Stability & Reliability: Resolved critical environment

loading, authentication, and session management issues, ensuring a more robust experience.

• Background Shell Commands: Enabled the execution of shell commands in the

background for increased workflow efficiency.

Highlights example 3

• Event-Driven Architecture: The CLI now uses an event-driven scheduler for

tool execution, improving performance and responsiveness. This includes migrating non-interactive flows and sub-agents to the new scheduler.

• Enhanced User Experience: This release introduces several UI/UX

improvements, including queued tool confirmations and the ability to expand and collapse large pasted text blocks. The Settings dialog has been improved to reduce jitter and preserve focus.

• Agent and Skill Improvements: Agent Skills have been promoted to a stable

feature. Sub-agents now use a JSON schema for input and are tracked by an AgentRegistry.

• New `/rewind` Command: A new /rewind command has been implemented to

allow users to go back in their session history.

• Improved Shell and File Handling: The shell tool's output format has been

optimized, and the CLI now gracefully handles disk-full errors during chat recording. A bug in detecting already added paths has been fixed.

• Linux Clipboard Support: Image pasting capabilities for Wayland and X11 on

Linux have been added.

Highlights example 4

• Improved Hooks Management: Hooks enable/disable functionality now aligns

with skills and offers improved completion.

• Custom Themes for Extensions: Extensions can now support custom themes,

allowing for greater personalization.

• User Identity Display: User identity information (auth, email, tier) is

now displayed on startup and in the stats command.

• Plan Mode Enhancements: Plan mode has been improved with a generic

Checklist component and refactored Todo.

• Background Shell Commands: Implementation of background shell commands.

Announcements: {{version}} - {{release_date_yyyy_mm_dd}}

{{announcement_content}}

<!-- Example entry, multiple entries per highlights

• Highlighted Feature: We've added a new highlighted feature to help

you generate prompt suggestions (#nnnnn by @author). -->

Latest stable release: {{version}}

Released: {{release_date_month_dd_yyyy}}

For most users, our latest stable release is the recommended release. Install the latest stable version with:

npm install -g @google/gemini-cli

Highlights

{{highlights_content}}

What's Changed

{{changelog_list}}

Full Changelog: {{full_changelog_link}}

Preview release: {{version}}

Released: {{release_date_month_dd_yyyy}}

Our preview release includes the latest, new, and experimental features. This release may not be as stable as our latest weekly release.

To install the preview release:

npm install -g @google/gemini-cli@preview

Highlights

{{highlights_content}}

What's Changed

{{changelog_list}}

Full Changelog: {{full_changelog_link}}