diff --git a/.agents/skills/OWNERS b/.agents/skills/OWNERS new file mode 100644 index 00000000000..e0ebb8a5531 --- /dev/null +++ b/.agents/skills/OWNERS @@ -0,0 +1,2 @@ +# Allow all committers to review documentation CLs. +file:/tools/OWNERS_ENG diff --git a/.agents/skills/update_dependency/SKILL.md b/.agents/skills/update_dependency/SKILL.md new file mode 100644 index 00000000000..bbd5f3dfa9d --- /dev/null +++ b/.agents/skills/update_dependency/SKILL.md @@ -0,0 +1,68 @@ +--- +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 \ + [--branch ] [--target ] +``` + +### Arguments + +1. `` (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/`. + - **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": ""`. 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/`, + 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 ` (optional): The name of the branch to create for + this update. Defaults to `bump_`. +3. `--target ` (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 - nothing to do"**: The dependency is already at the + latest version or the specified target. +- **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.