clone/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-02-01 22:48:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated ToC on docs intro; updated title casing to match Google style (#13717)

Browse Source
This commit is contained in:
David Huntsperger
2025-12-01 11:38:48 -08:00
committed by GitHub
parent bde8b78a88
commit 26f050ff10
58 changed files with 660 additions and 642 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/releases.md
View File

@@ -1,4 +1,4 @@
# Gemini CLI Releases
# Gemini CLI releases
## `dev` vs `prod` environment
@@ -22,7 +22,7 @@ More information can be found about these systems in the
| Core | @google/gemini-cli-core | @google-gemini/gemini-cli-core A2A Server |
| A2A Server | @google/gemini-cli-a2a-server | @google-gemini/gemini-cli-a2a-server |
## Release Cadence and Tags
## Release cadence and tags
We will follow https://semver.org/ as closely as possible but will call out when
or if we have to deviate from it. Our weekly releases will be minor version
@@ -66,24 +66,24 @@ npm install -g @google/gemini-cli@latest
npm install -g @google/gemini-cli@nightly
```
## Weekly Release Promotion
## Weekly release promotion
Each Tuesday, the on-call engineer will trigger the "Promote Release" workflow.
This single action automates the entire weekly release process:
1. **Promotes Preview to Stable:** The workflow identifies the latest `preview`
1. **Promotes preview to stable:** The workflow identifies the latest `preview`
release and promotes it to `stable`. This becomes the new `latest` version
on npm.
2. **Promotes Nightly to Preview:** The latest `nightly` release is then
2. **Promotes nightly to preview:** The latest `nightly` release is then
promoted to become the new `preview` version.
3. **Prepares for next Nightly:** A pull request is automatically created and
3. **Prepares for next nightly:** A pull request is automatically created and
merged to bump the version in `main` in preparation for the next nightly
release.
This process ensures a consistent and reliable release cadence with minimal
manual intervention.
### Source of Truth for Versioning
### Source of truth for versioning
To ensure the highest reliability, the release promotion process uses the **NPM
registry as the single source of truth** for determining the current version of
@@ -92,16 +92,16 @@ each release channel (`stable`, `preview`, and `nightly`).
1. **Fetch from NPM:** The workflow begins by querying NPM's `dist-tags`
(`latest`, `preview`, `nightly`) to get the exact version strings for the
packages currently available to users.
2. **Cross-Check for Integrity:** For each version retrieved from NPM, the
2. **Cross-check for integrity:** For each version retrieved from NPM, the
workflow performs a critical integrity check:
- It verifies that a corresponding **git tag** exists in the repository.
- It verifies that a corresponding **GitHub Release** has been created.
3. **Halt on Discrepancy:** If either the git tag or the GitHub Release is
- It verifies that a corresponding **GitHub release** has been created.
3. **Halt on discrepancy:** If either the git tag or the GitHub Release is
missing for a version listed on NPM, the workflow will immediately fail.
This strict check prevents promotions from a broken or incomplete previous
release and alerts the on-call engineer to a release state inconsistency
that must be manually resolved.
4. **Calculate Next Version:** Only after these checks pass does the workflow
4. **Calculate next version:** Only after these checks pass does the workflow
proceed to calculate the next semantic version based on the trusted version
numbers retrieved from NPM.
@@ -109,14 +109,14 @@ This NPM-first approach, backed by integrity checks, makes the release process
highly robust and prevents the kinds of versioning discrepancies that can arise
from relying solely on git history or API outputs.
## Manual Releases
## Manual releases
For situations requiring a release outside of the regular nightly and weekly
promotion schedule, and NOT already covered by patching process, you can use the
`Release: Manual` workflow. This workflow provides a direct way to publish a
specific version from any branch, tag, or commit SHA.
### How to Create a Manual Release
### How to create a manual release
1. Navigate to the **Actions** tab of the repository.
2. Select the **Release: Manual** workflow from the list.
@@ -144,7 +144,7 @@ The workflow will then proceed to test (if not skipped), build, and publish the
release. If the workflow fails during a non-dry run, it will automatically
create a GitHub issue with the failure details.
## Rollback/Rollforward
## Rollback/rollforward
In the event that a release has a critical regression, you can quickly roll back
to a previous stable version or roll forward to a new patch by changing the npm
@@ -154,7 +154,7 @@ way to do this.
This is the preferred method for both rollbacks and rollforwards, as it does not
require a full release cycle.
### How to Change a Release Tag
### How to change a release tag
1. Navigate to the **Actions** tab of the repository.
2. Select the **Release: Change Tags** workflow from the list.
@@ -181,13 +181,13 @@ channel to the specified version.
If a critical bug that is already fixed on `main` needs to be patched on a
`stable` or `preview` release, the process is now highly automated.
### How to Patch
### How to patch
#### 1. Create the Patch Pull Request
#### 1. Create the patch pull request
There are two ways to create a patch pull request:
**Option A: From a GitHub Comment (Recommended)**
**Option A: From a GitHub comment (recommended)**
After a pull request containing the fix has been merged, a maintainer can add a
comment on that same PR with the following format:
@@ -212,7 +212,7 @@ The `Release: Patch from Comment` workflow will automatically find the merge
commit SHA and trigger the `Release: Patch (1) Create PR` workflow. If the PR is
not yet merged, it will post a comment indicating the failure.
**Option B: Manually Triggering the Workflow**
**Option B: Manually triggering the workflow**
Navigate to the **Actions** tab and run the **Release: Patch (1) Create PR**
workflow.
@@ -229,17 +229,17 @@ This workflow will automatically:
4. Cherry-pick your specified commit into the hotfix branch.
5. Create a pull request from the hotfix branch back to the release branch.
#### 2. Review and Merge
#### 2. Review and merge
Review the automatically created pull request(s) to ensure the cherry-pick was
successful and the changes are correct. Once approved, merge the pull request.
**Security Note:** The `release/*` branches are protected by branch protection
**Security note:** The `release/*` branches are protected by branch protection
rules. A pull request to one of these branches requires at least one review from
a code owner before it can be merged. This ensures that no unauthorized code is
released.
#### 2.5. Adding Multiple Commits to a Hotfix (Advanced)
#### 2.5. Adding multiple commits to a hotfix (advanced)
If you need to include multiple fixes in a single patch release, you can add
additional commits to the hotfix branch after the initial patch PR has been
@@ -280,7 +280,7 @@ This approach allows you to group related fixes into a single patch release
while maintaining full control over what gets included and how conflicts are
resolved.
#### 3. Automatic Release
#### 3. Automatic release
Upon merging the pull request, the `Release: Patch (2) Trigger` workflow is
automatically triggered. It will then start the `Release: Patch (3) Release`
@@ -293,21 +293,21 @@ workflow, which will:
This fully automated process ensures that patches are created and released
consistently and reliably.
#### Troubleshooting: Older Branch Workflows
#### Troubleshooting: Older branch workflows
**Issue**: If the patch trigger workflow fails with errors like "Resource not
accessible by integration" or references to non-existent workflow files (e.g.,
`patch-release.yml`), this indicates the hotfix branch contains an outdated
version of the workflow files.
**Root Cause**: When a PR is merged, GitHub Actions runs the workflow definition
**Root cause**: When a PR is merged, GitHub Actions runs the workflow definition
from the **source branch** (the hotfix branch), not from the target branch (the
release branch). If the hotfix branch was created from an older release branch
that predates workflow improvements, it will use the old workflow logic.
**Solutions**:
**Option 1: Manual Trigger (Quick Fix)** Manually trigger the updated workflow
**Option 1: Manual trigger (quick fix)** Manually trigger the updated workflow
from the branch with the latest workflow code:
```bash
@@ -337,7 +337,7 @@ gh workflow run release-patch-2-trigger.yml --ref main \
the latest workflow improvements (usually `main`, but could be a feature branch
if testing updates).
**Option 2: Update the Hotfix Branch** Merge the latest main branch into your
**Option 2: Update the hotfix branch** Merge the latest main branch into your
hotfix branch to get the updated workflows:
```bash
@@ -348,7 +348,7 @@ git push
Then close and reopen the PR to retrigger the workflow with the updated version.
**Option 3: Direct Release Trigger** Skip the trigger workflow entirely and
**Option 3: Direct release trigger** Skip the trigger workflow entirely and
directly run the release workflow:
```bash
@@ -367,7 +367,7 @@ We also run a Google cloud build called
docker to match your release. This will also be moved to GH and combined with
the main release file once service account permissions are sorted out.
## Release Validation
## Release validation
After pushing a new release smoke testing should be performed to ensure that the
packages are working as expected. This can be done by installing the packages
@@ -384,7 +384,7 @@ correctly.
is recommended to ensure that the packages are working as expected. We'll
codify this more in the future.
## Local Testing and Validation: Changes to the Packaging and Publishing Process
## Local testing and validation: Changes to the packaging and publishing process
If you need to test the release process without actually publishing to NPM or
creating a public GitHub release, you can trigger the workflow manually from the
@@ -428,7 +428,7 @@ tarballs will be created in the root of each package's directory (e.g.,
By performing a dry run, you can be confident that your changes to the packaging
process are correct and that the packages will be published successfully.
## Release Deep Dive
## Release deep dive
The release process creates two distinct types of artifacts for different
distribution channels: standard packages for the NPM registry and a single,
@@ -436,14 +436,14 @@ self-contained executable for GitHub Releases.
Here are the key stages:
**Stage 1: Pre-Release Sanity Checks and Versioning**
**Stage 1: Pre-release sanity checks and versioning**
- **What happens:** Before any files are moved, the process ensures the project
is in a good state. This involves running tests, linting, and type-checking
(`npm run preflight`). The version number in the root `package.json` and
`packages/cli/package.json` is updated to the new release version.
**Stage 2: Building the Source Code for NPM**
**Stage 2: Building the source code for NPM**
- **What happens:** The TypeScript source code in `packages/core/src` and
`packages/cli/src` is compiled into standard JavaScript.
@@ -454,7 +454,7 @@ Here are the key stages:
into plain JavaScript that can be run by Node.js. The `core` package is built
first as the `cli` package depends on it.
**Stage 3: Publishing Standard Packages to NPM**
**Stage 3: Publishing standard packages to NPM**
- **What happens:** The `npm publish` command is run for the
`@google/gemini-cli-core` and `@google/gemini-cli` packages.
@@ -463,12 +463,12 @@ Here are the key stages:
`npm` will handle installing the `@google/gemini-cli-core` dependency
automatically. The code in these packages is not bundled into a single file.
**Stage 4: Assembling and Creating the GitHub Release Asset**
**Stage 4: Assembling and creating the GitHub release asset**
This stage happens _after_ the NPM publish and creates the single-file
executable that enables `npx` usage directly from the GitHub repository.
1. **The JavaScript Bundle is Created:**
1. **The JavaScript bundle is created:**
- **What happens:** The built JavaScript from both `packages/core/dist` and
`packages/cli/dist`, along with all third-party JavaScript dependencies,
are bundled by `esbuild` into a single, executable JavaScript file (e.g.,
@@ -479,7 +479,7 @@ executable that enables `npx` usage directly from the GitHub repository.
run the CLI without a full `npm install`, as all dependencies (including
the `core` package) are included directly.
2. **The `bundle` Directory is Assembled:**
2. **The `bundle` directory is assembled:**
- **What happens:** A temporary `bundle` folder is created at the project
root. The single `gemini.js` executable is placed inside it, along with
other essential files.
@@ -491,7 +491,7 @@ executable that enables `npx` usage directly from the GitHub repository.
- **Why:** This creates a clean, self-contained directory with everything
needed to run the CLI and understand its license and usage.
3. **The GitHub Release is Created:**
3. **The GitHub release is created:**
- **What happens:** The contents of the `bundle` directory, including the
`gemini.js` executable, are attached as assets to a new GitHub Release.
- **Why:** This makes the single-file version of the CLI available for
@@ -499,12 +499,12 @@ executable that enables `npx` usage directly from the GitHub repository.
`npx https://github.com/google-gemini/gemini-cli` command, which downloads
and runs this specific bundled asset.
**Summary of Artifacts**
**Summary of artifacts**
- **NPM:** Publishes standard, un-bundled Node.js packages. The primary artifact
is the code in `packages/cli/dist`, which depends on
`@google/gemini-cli-core`.
- **GitHub Release:** Publishes a single, bundled `gemini.js` file that contains
- **GitHub release:** Publishes a single, bundled `gemini.js` file that contains
all dependencies, for easy execution via `npx`.
This dual-artifact process ensures that both traditional `npm` users and those