update-dependency

---
name: update-dependency
description: Updates third party dependencies in the Dart SDK
---

# Instructions

Use this skill to update dependencies in the Dart SDK's `DEPS` file to their
latest (or a specific) version. This tool automates the process of updating
the version, syncing dependencies, updating package configurations, and
creating a CL.

## Prerequisites

Before running the tool, ensure your environment is prepared correctly:

1.  **Clean Git State**: Your git checkout MUST be clean. No uncommitted
    changes should be present.
2.  **On Main Branch**: You MUST be on the `main` branch. The tool creates a
    new branch from your current HEAD, so being on `main` ensures the bump
    starts from a clean baseline.

## Tool Usage

Run the `tools/manage_deps.dart` script with the `bump` command from the root
of the SDK.

### Command Syntax

```bash
dart tools/manage_deps.dart bump <path/to/dependency> \
  [--branch <branch_name>] [--target <ref>]
```

### Arguments

1.  `<path/to/dependency>` (required): The path to the dependency directory
    relative to the SDK root. Dependencies are entire repositories and not
    packages, so the path will usually be `third_party/pkg/<repo>`.
    - **CRITICAL**: DO NOT include a trailing slash in the path.
    - If unsure of the repository, you can look at the
      `.dart_tool/package_config.json` file relative to the SDK root, and search
      for `"name": "<package-name>"`. Next to that you should see a "rootUri"
      key which will give you the path to the dependency. Do not use the full
      path though, just the top level directory under `third_party/pkg/<repo>`,
      since entire repos are always rolled at once.
    - If the `.dart_tool/package_config.json` file does not exist, it can be
      generated by running `gclient sync`.
2.  `--branch <branch_name>` (optional): The name of the branch to create for
    this update. Defaults to `bump_<dependency_name>`.
3.  `--target <ref>` (optional): The specific git ref (SHA, tag, branch) to
    update to. Defaults to the latest version on the remote's default branch.

## Example

To bump the `unified_analytics` dependency, which is a part of the `tools` repo:

```bash
dart tools/manage_deps.dart bump third_party/pkg/tools
```

## Troubleshooting

- **"Already at <target> - nothing to do" (or missing recent GitHub commit)**:
  The dependency is already at the latest version on the mirror, or the
  `dart.googlesource.com` mirror has not yet synced a recently merged GitHub
  commit.
  - **For Googlers**: If a commit recently landed on GitHub (check with
    `git ls-remote https://github.com/<org>/<repo>.git refs/heads/main`, where
    `<org>` is typically `dart-lang`) but is not yet on
    `https://dart.googlesource.com/<repo>.git`, trigger an immediate mirror
    fetch:
    ```bash
    gob-ctl repos update-mirror-config github/<org>/<repo> \
      --fetch_frequency 5m \
      --uri https://github.com/<org>/<repo>.git
    ```
    Wait ~10 seconds, verify with
    `git ls-remote https://dart.googlesource.com/<repo>.git refs/heads/main`,
    and rerun `tools/manage_deps.dart`.
- **Branch already exists**: If the tool says a branch with the target name
  already exists, you will be prompted to delete it. Usually, it is safe to say
  "y" if you want a fresh bump.
- **"CorpSSO login required. To log in, run glogin or gcert"**: This indicates a
  Google-internal SSO authentication failure during fetching/syncing
  dependencies. This error and the suggested fix (`gcert` / `glogin`) are only
  applicable for Googlers. Since this requires interactive authentication, you
  must ask the user to run `gcert` (or `glogin`) in their terminal to
  authenticate, and then retry.

More agent context in dart-lang/sdk

4 other files this repository gives its agents.