| name | forward-port |
| description | Manually forward-ports merged dev (v0) changes to the v1 branch, adapting code to v1's package layout and changeset names. Use when a dev PR is merged and needs v1 parity, when triaging "(v1)" reconciliation issues, or when the user mentions forward-porting, dual-tracking, or dev-to-v1 porting. |
| metadata | {"internal":true} |
Forward-port (dev → v1)
ArkEnv runs dual-tracking: non-breaking work lands on dev (v0) first, then is manually adapted onto v1. Never merge dev into v1 wholesale - structural differences cause severe tree conflicts.
See REFERENCE.md for the full path/package map, changeset rename table, and real port examples.
When to forward-port
Forward-port after a merged dev PR that fixes a bug, adds a non-breaking feature, or updates shared integrations.
Skip forward-porting when work is (v1)-only, introduces dev-only structure, or should be implemented natively on v1.
Quick start
gh pr view <number> --json title,mergeCommit,files
git fetch origin v1 && git checkout -b forward-port/<name> origin/v1
pnpm run typecheck && pnpm run test
gh pr create --base v1 --title "fix: Forward-port <summary> from dev"
Workflow
0. Pick what to port (if not specified)
If the user did not name a PR, issue, or commit, stop and ask before writing code.
- Discover candidates - recently merged dev PRs that touch published packages and likely need v1 parity (see REFERENCE.md - discovery commands).
- Filter out PRs already forward-ported (v1 PR title/body mentions the dev PR, or commit message contains
Forward-port).
- Present multiple choice via
AskQuestion with up to 4 candidates. Label each option as #1234 - short title (packages touched).
- Always include "Other - I'll specify" as the last option so the user can paste a PR/issue number.
- If no candidates remain, say so and ask whether to port a specific PR/issue the user has in mind.
Do not guess or auto-pick when multiple candidates exist.
1. Gather source context
Read the merged dev PR: files, tests, changeset, linked issue. Note behavior - re-implement, don't blind cherry-pick. Map each touched package using REFERENCE.md.
2. Adapt the implementation
Key path map:
| dev | v1 |
|---|
packages/cli/src/** | packages/arkenv/src/** |
packages/arkenv/src/** (core) | packages/core/src/** |
nextjs, nuxt, build, … | Same paths - verify imports |
Checklist:
3. Port the changeset
Rename frontmatter keys: "@arkenv/cli" → "arkenv", "arkenv" (core) → "@arkenv/core". Follow the changeset skill.
4. Verify and open PR
Run pnpm run typecheck, pnpm run test, and package-scoped tests if localized. Open PR targeting v1, link the dev PR and tracking issue.
Acceptance checklist
Common mistakes
| Mistake | Fix |
|---|
git merge dev into v1 | Feature-driven manual port |
| Blind cherry-pick | Re-implement at v1 paths |
"cli" in v1 changeset | Rename to "arkenv" |
Core change in packages/arkenv/ on v1 | Core is packages/core/ |
Related
