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.
- Verify the source PR or commit is merged to
main:gh pr view <SOURCE_PR> --json state,mergedAt,baseRefName,mergeCommit - 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 exactDART <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> - 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 - Cherry-pick with provenance:
git cherry-pick -x <COMMIT_HASH>. - Resolve conflicts minimally; stop and ask if conflicts are broad or change behavior.
- Run
/dart-changelog decideor$dart-changelog decideagainst 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 addedchangelog.d/fragments, delete them and letdart-changelogwrite the entry into the release branch'sCHANGELOG.md. - Run
pixi run lintand the smallest relevant release-branch checks. - 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 finalizeor$dart-changelog finalizeand push the follow-up only after explicit approval.
Output
- Backport PR URL
- Source PR/commit
- Conflicts resolved, if any
- Changelog decision and any deferred finalize follow-up
- Checks run and CI status