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

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:

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. Ask the user if the newest hash/commit should be taken directly from GitHub (e.g., if the googlesource mirror is lagging behind or the desired change is only on GitHub main).
   • 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 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:

   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):

   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):

   "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:

   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:

   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:

   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:

   git new-branch roll-<YYYYMMDD>
   git commit -a -m "[deps] Roll dart-lang/native"