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.