From 9fc7b567933b935aa1dc3821d76df2313b78f71b Mon Sep 17 00:00:00 2001 From: g-samroberts <158088236+g-samroberts@users.noreply.github.com> Date: Fri, 13 Feb 2026 16:40:06 -0800 Subject: [PATCH] Revamp automated changelog skill (#18974) --- .gemini/skills/docs-changelog/SKILL.md | 190 +++++++++--------- .../references/highlights_examples.md | 68 +++++++ .../references/index_template.md | 10 + .../references/latest_template.md | 20 ++ .../references/preview_template.md | 22 ++ .github/workflows/release-notes.yml | 2 +- 6 files changed, 219 insertions(+), 93 deletions(-) create mode 100644 .gemini/skills/docs-changelog/references/highlights_examples.md create mode 100644 .gemini/skills/docs-changelog/references/index_template.md create mode 100644 .gemini/skills/docs-changelog/references/latest_template.md create mode 100644 .gemini/skills/docs-changelog/references/preview_template.md diff --git a/.gemini/skills/docs-changelog/SKILL.md b/.gemini/skills/docs-changelog/SKILL.md index 7a3d0cac4e..eb56bad98e 100644 --- a/.gemini/skills/docs-changelog/SKILL.md +++ b/.gemini/skills/docs-changelog/SKILL.md @@ -1,125 +1,131 @@ --- name: docs-changelog -description: Provides a step-by-step procedure for generating Gemini CLI changelog files based on github release information. +description: >- + Generates and formats changelog files for a new release based on provided + version and raw changelog data. --- # Procedure: Updating Changelog for New Releases -The following instructions are run by Gemini CLI when processing new releases. - ## Objective -To standardize the process of updating the Gemini CLI changelog files for a new -release, ensuring accuracy, consistency, and adherence to project style -guidelines. +To standardize the process of updating changelog files (`latest.md`, +`preview.md`, `index.md`) based on automated release information. -## Release Types +## Inputs -This skill covers two types of releases: +- **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. -* **Standard Releases:** Regular, versioned releases that are announced to all - users. These updates modify `docs/changelogs/latest.md` and - `docs/changelogs/index.md`. -* **Preview Releases:** Pre-release versions for testing and feedback. These - updates only modify `docs/changelogs/preview.md`. +## Guidelines for `latest.md` and `preview.md` Highlights -Ignore all other releases, such as nightly releases. +- Aim for **3-5 key highlight points**. +- **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. -### Expected Inputs +## Initial Processing -Regardless of the type of release, the following information is expected: +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. -* **New version number:** The version number for the new release - (e.g., `v0.27.0`). -* **Release date:** The date of the new release (e.g., `2026-02-03`). -* **Raw changelog data:** A list of all pull requests and changes - included in the release, in the format `description by @author in - #pr_number`. -* **Previous version number:** The version number of the last release can be - calculated by decreasing the minor version number by one and setting the - patch or bug fix version number. +--- -## Procedure +## Path A: New Minor Version -### Initial Setup +*Use this path if the version number ends in `.0`.* -1. Identify the files to be modified: +### A.1: Stable Release (e.g., `v0.28.0`) - For standard releases, update `docs/changelogs/latest.md` and - `docs/changelogs/index.md`. For preview releases, update - `docs/changelogs/preview.md`. +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. -2. Activate the `docs-writer` skill. +1. **Create the Announcement for `index.md`**: + - Generate a concise announcement summarizing the most important changes. + - **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. + - Add this new announcement to the top of `docs/changelogs/index.md`. -### Analyze Raw Changelog Data +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. -1. Review the complete list of changes. If it is a patch or a bug fix with few - changes, skip to the "Update `docs/changelogs/latest.md` or - `docs/changelogs/preview.md`" section. +### A.2: Preview Release (e.g., `v0.29.0-preview.0`) -2. Group related changes into high-level categories such as - important features, "UI/UX Improvements", and "Bug Fixes". Use the existing - announcements in `docs/changelogs/index.md` as an example. +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. -### Create Highlight Summaries +--- -Create two distinct versions of the release highlights. +## Path B: Patch Version -**Important:** Carefully inspect highlights for "experimental" or -"preview" features before public announcement, and do not include them. +*Use this path if the version number does **not** end in `.0`.* -#### Version 1: Comprehensive Highlights (for `latest.md` or `preview.md`) +### B.1: Stable Patch (e.g., `v0.28.1`) -Write a detailed summary for each category focusing on user-facing -impact. +- **Target File**: `docs/changelogs/latest.md` +- Perform the following edits on the target file: + 1. Update the version in the main header. + 2. Update the "Released:" date. + 3. **Prepend** the processed "What's Changed" list from the temporary file + to the existing "What's Changed" list in the file. + 4. In the "Full Changelog" URL, replace only the trailing version with the + new patch version. -#### Version 2: Concise Highlights (for `index.md`) +### B.2: Preview Patch (e.g., `v0.29.0-preview.3`) -Skip this step for preview releases. +- **Target File**: `docs/changelogs/preview.md` +- Perform the following edits on the target file: + 1. Update the version in the main header. + 2. Update the "Released:" date. + 3. **Prepend** the processed "What's Changed" list from the temporary file + to the existing "What's Changed" list in the file. + 4. In the "Full Changelog" URL, replace only the trailing version with the + new patch version. -Write concise summaries including the primary PR and author -(e.g., `([#12345](link) by @author)`). +--- -### Update `docs/changelogs/latest.md` or `docs/changelogs/preview.md` +## Finalize -1. Read current content and use `write_file` to replace it with the new - version number, and date. - - If it is a patch or bug fix with few changes, simply add these - changes to the "What's Changed" list. Otherwise, replace comprehensive - highlights, and the full "What's Changed" list. - -2. For each item in the "What's Changed" list, keep usernames in plaintext, and - add github links for each issue number. Example: - - "- feat: implement /rewind command by @username in - [#12345](https://github.com/google-gemini/gemini-cli/pull/12345)" - -3. Skip entries by @gemini-cli-robot. - -4. Do not add the "New Contributors" section. - -5. Update the "Full changelog:" link by doing one of following: - - If it is a patch or bug fix with few changes, retain the original link - but replace the latter version with the new version. For example, if the - patch is version is "v0.28.1", replace the latter version: - "https://github.com/google-gemini/gemini-cli/compare/v0.27.0...v0.28.0" with - "https://github.com/google-gemini/gemini-cli/compare/v0.27.0...v0.28.1". - - Otherwise, for minor and major version changes, replace the link with the - one included at the end of the changelog data. - -6. Ensure lines are wrapped to 80 characters. - -### Update `docs/changelogs/index.md` - -Skip this step for patches, bug fixes, or preview releases. - -Insert a new "Announcements" section for the new version directly -above the previous version's section. Ensure lines are wrapped to -80 characters. - -### Finalize - -Run `npm run format` to ensure consistency. +- After making changes, run `npm run format` to ensure consistency. +- Delete any temporary files created during the process. diff --git a/.gemini/skills/docs-changelog/references/highlights_examples.md b/.gemini/skills/docs-changelog/references/highlights_examples.md new file mode 100644 index 0000000000..c65e1598d0 --- /dev/null +++ b/.gemini/skills/docs-changelog/references/highlights_examples.md @@ -0,0 +1,68 @@ +## 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. diff --git a/.gemini/skills/docs-changelog/references/index_template.md b/.gemini/skills/docs-changelog/references/index_template.md new file mode 100644 index 0000000000..9750a3406d --- /dev/null +++ b/.gemini/skills/docs-changelog/references/index_template.md @@ -0,0 +1,10 @@ +## Announcements: {{version}} - {{release_date_yyyy_mm_dd}} + +{{announcement_content}} + + diff --git a/.gemini/skills/docs-changelog/references/latest_template.md b/.gemini/skills/docs-changelog/references/latest_template.md new file mode 100644 index 0000000000..d682e33216 --- /dev/null +++ b/.gemini/skills/docs-changelog/references/latest_template.md @@ -0,0 +1,20 @@ +# 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}} diff --git a/.gemini/skills/docs-changelog/references/preview_template.md b/.gemini/skills/docs-changelog/references/preview_template.md new file mode 100644 index 0000000000..641ff704ae --- /dev/null +++ b/.gemini/skills/docs-changelog/references/preview_template.md @@ -0,0 +1,22 @@ +# 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](latest.md). + +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}} diff --git a/.github/workflows/release-notes.yml b/.github/workflows/release-notes.yml index a677fd98d0..2481873854 100644 --- a/.github/workflows/release-notes.yml +++ b/.github/workflows/release-notes.yml @@ -50,7 +50,7 @@ jobs: # Use a heredoc to preserve multiline release body echo 'RAW_CHANGELOG<> "$GITHUB_OUTPUT" - echo "${BODY}" >> "$GITHUB_OUTPUT" + printf "%s\n" "${BODY}" >> "$GITHUB_OUTPUT" echo 'EOF' >> "$GITHUB_OUTPUT" env: GH_TOKEN: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'