update-native-rev

---
name: update-native-rev
description: Updates the native_rev dependency in the DEPS file with all correct verification, sync, and testing procedures
---

<!-- Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
     for details. All rights reserved. Use of this source code is governed by a
     BSD-style license that can be found in the LICENSE file. -->

# Instructions

Use this skill when you are requested to roll or update the `native_rev` variable (the hash of `third_party/pkg/native` repository) in the `DEPS` file.

## 0. Initial Synchronization

Before beginning the roll, **ask the user** if the SDK git repository should be switched to the `main` branch and synchronized.
If they confirm, run:
```bash
git checkout main && git pull && gclient sync -D -f
```

## 1. Commit Selection Rules

> [!IMPORTANT]
> **CRITICAL RULE**: NEVER EVER pick a local commit or a commit from a custom branch/PR branch. You MUST only pick remote commits that have already landed on the remote `main` branch.

To select the correct commit SHA:
1. If the `dart.googlesource.com/native.git` mirror is lagging behind GitHub:
   * **For Googlers**: Trigger an immediate mirror sync instead of modifying `DEPS`:
     ```bash
     gob-ctl repos update-mirror-config github/dart-lang/native \
       --fetch_frequency 5m \
       --uri https://github.com/dart-lang/native.git
     ```
     Wait ~10 seconds, verify with `git ls-remote https://dart.googlesource.com/native.git refs/heads/main`, and proceed with the default mirrored googlesource setup below.
   * **Otherwise, ask the user** if the newest hash/commit should be taken directly from **GitHub**:
     * **If the user says YES**:
       1. First, temporarily change the repository URL and host permissions in the `DEPS` file by following the instructions in the **[Troubleshooting Sync Failures](#troubleshooting-sync-failures)** section (changing `third_party/pkg/native` under `deps` to use `"https://github.com/dart-lang/native.git"` and adding `'github.com'` to `allowed_hosts` in `DEPS`).
       2. Run `gclient sync` from the SDK root to update the checkout mapping to GitHub.
       3. Navigate to the `native` package subdirectory: `third_party/pkg/native`.
       4. Run `git fetch origin` to fetch the latest commits from the GitHub remote (origin will now point to GitHub).
       5. After checking commits, **immediately set the repository URL and host permissions in `DEPS` back to googlesource** (reverting the changes made in sub-step 1), so that subsequent steps and the final commit only roll the commit hash without permanently keeping GitHub host settings.
     * **If the user says NO / default**:
       1. Proceed with the default mirrored googlesource setup.
       2. Navigate to the `native` package subdirectory: `third_party/pkg/native`.
       3. Run `git fetch origin` to fetch the latest commits from the mirror.
2. Inspect the commits on remote `origin/main` of the `native` repository:
   ```bash
   git log origin/main -n 10 --oneline
   ```
3. Obtain the full SHA of the newest commit on remote `origin/main` (or the specific one that contains the required change):
   ```bash
   git rev-parse origin/main
   ```
4. **Revert Host to GoogleSource**:
   * **IMPORTANT**: If the host was set to GitHub, you **MUST** now revert the repository URL and allowed hosts changes in the `DEPS` file back to the mirrored googlesource URL, removing `github.com` from `allowed_hosts`. Do this before updating `native_rev` so that the final committed change only rolls the commit hash, not checkout hosts.

## 2. Updating DEPS and Synchronizing

1. Locate `native_rev` in the `DEPS` file (typically under `vars`):
   ```python
   "native_rev": "<old_sha>",
```
2. Replace the hash with the chosen remote `origin/main` commit SHA.
3. If not already done in step 4 above, ensure the `DEPS` host and URL configuration are reverted to the googlesource mirror, leaving only the updated `native_rev` hash.
4. Run `gclient sync -f` from the SDK root directory to update the checkout of the dependencies and regenerate the package configuration using the mirror.

### Troubleshooting Sync Failures
If the synchronization fails because of host restrictions:
1. Temporarily modify the repository configuration under `deps` in `DEPS` to use:
   `https://github.com/dart-lang/native.git` as the git repo.
2. Temporarily add `'github.com'` to the `allowed_hosts` list in `DEPS`.
3. Re-run `gclient sync -f` to complete the update.
4. **IMPORTANT**: Immediately after successful syncing, revert the host and URL changes in the `DEPS` file, removing `github.com` from `allowed_hosts` and returning to the mirrored googlesource URL, but keep the newly synced native commit hash.

## 3. Mandatory Testing and Verification

Before completing the update, you must run the following tests:

### Native Assets Package Tests
Build the target SDK and run the primary native asset tests:
```bash
RBE_exec_strategy=racing tools/build.py -mrelease create_sdk runtime ffi_test_functions runtime_precompiled && tools/test.py -n unittest-asserts-release-mac-arm64 pkg/dartdev/test/native_assets/
```

### Record Use Optimization Tests
Since `record_use` integrates closely with `native_rev` updates, these tests must be validated for both backends (Wasm and VM). **Note**: `record_use` is now 1.0, so breaking changes are not allowed and expectations should NOT need updating.

1. Build the required target backends and run all record use tests:
   ```bash
   RBE_exec_strategy=racing tools/build.py -mrelease create_sdk dart2wasm runtime ffi_test_functions runtime_precompiled && xcodebuild/ReleaseARM64/dart-sdk/bin/dart pkg/compiler/test/record_use/record_use_test.dart && xcodebuild/ReleaseARM64/dart-sdk/bin/dart pkg/dart2wasm/test/record_use_test.dart && xcodebuild/ReleaseARM64/dart-sdk/bin/dart pkg/vm/test/transformations/record_use_test.dart
   ```
2. **Test Failure Policy**:
   > [!IMPORTANT]
   > Since `record_use` is 1.0, any test failure here indicates an illegal breaking change rather than a need for expectation updates. Do not update expectations; report any failure immediately.
3. **Running Individual Tests**:
   To debug or verify a single test:
   ```bash
   python3 tools/test.py -n wasm-unittest-asserts-mac pkg/dart2wasm/test/record_use_test.dart
   ```

## 4. Pre-Completion Protocol

Follow these final validation steps before announcing completion:

1. **Format touched files**: Run `dart format` on all modified Dart files.
2. **Analyze touched files**: Run `dart analyze` to ensure there are no lint or static analysis issues.
3. **Presubmit checks**: Run `git cl presubmit` to ensure build/format sanity.
4. **Update Coverage (Front-End changes only)**:
   If any related changes were also introduced in the `front_end` directory, regenerate test coverage:
   ```bash
   dart --enable-asserts pkg/front_end/test/coverage_suite.dart --tasks=5 --add-and-remove-comments
   ```
   * *Critical*: Revert the coverage comment changes in any files that you did not otherwise modify.

## 5. Branching and Committing

After all tests pass and formatting/analysis is clean:
1. **Ask the user** if they want to create a roll branch and commit the changes.
2. If confirmed, get the current date in `YYYYMMDD` format (e.g., `20260630`) and run:
   ```bash
   git new-branch roll-<YYYYMMDD>
   git commit -a -m "[deps] Roll dart-lang/native"
   ```

More agent context in dart-lang/sdk

4 other files this repository gives its agents.