dart-backport-pr

dart-backport-pr

Use this skill to run the DART dart-backport-pr workflow. The editable workflow source lives in .claude/commands/; this generated skill is its entrypoint for Codex and Muse.

Invocation

• Claude Code: /dart-backport-pr <arguments>
• Codex: $dart-backport-pr <arguments>
• Muse: /dart-backport-pr <arguments>

Treat the text after the skill name, or the user's request when the skill is loaded on demand, as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Backport PR or commits: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/release-management.md @docs/onboarding/changelog.md

Workflow

New patches land on main. Use this workflow to backport merged PRs to a selected release-* stabilization or maintenance branch. A release branch may be cut from an approved stabilization commit before its first release tag, or from a published release tag.

For a source change involving model/scene structure, physics behavior, or Filament output, use the release branch's dart-verify-sim workflow to preserve the text oracle and assessed visual evidence. Document a visual exception when the release branch cannot render the claim.

1. Verify the source PR or commit is merged to main:

   gh pr view <SOURCE_PR> --json state,mergedAt,baseRefName,mergeCommit
   

2. Resolve the target from the live backport PR base or the selected release branch. Fetch it and read its docs/onboarding/release-management.md § "Release target"; verify the exact DART <Next release> milestone is open on GitHub. Publishing requires explicit maintainer/user approval. Check whether an equivalent change already exists on that branch:

   git fetch origin <RELEASE_BRANCH> main
   git cherry -v --abbrev=40 origin/<RELEASE_BRANCH> origin/main | grep <COMMIT_HASH>
   

3. Create a topic branch from the release target without resetting an existing local branch:

   BRANCH=backport/<SOURCE_PR>-to-<RELEASE_BRANCH>
   if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
     if [ -n "$(git status --short)" ] || [ "$(git rev-parse "$BRANCH")" \
         != "$(git rev-parse "origin/<RELEASE_BRANCH>")" ]; then
       echo "existing $BRANCH is dirty or diverges from the release tip" >&2
       exit 1  # stop and ask before resetting or cherry-picking onto it
     fi
     git switch "$BRANCH"
   else
     git switch --no-track -c "$BRANCH" origin/<RELEASE_BRANCH>
   fi
   

4. Cherry-pick with provenance: git cherry-pick -x <COMMIT_HASH>.
5. Resolve conflicts minimally; stop and ask if conflicts are broad or change behavior.
6. Run /dart-changelog decide or $dart-changelog decide against the backport diff and release target before opening the release PR. If an entry is required but needs the backport PR number, draft the decision and keep the finalize/update follow-up local until explicit approval permits another push. Do not skip the changelog decision just because this is a backport. Release branches take no fragments: if the cherry-pick added changelog.d/ fragments, delete them and let dart-changelog write the entry into the release branch's CHANGELOG.md.
7. Run pixi run lint and the smallest relevant release-branch checks.
8. Ask for explicit maintainer/user approval before pushing or opening the PR. After approval, open it as a draft against the release branch with the resolved next-release milestone and the PR template, then follow docs/onboarding/ai-tools.md § "PR Lifecycle". If the changelog decision was deferred for the PR number, run /dart-changelog finalize or $dart-changelog finalize and push the follow-up only after explicit approval.