StackAnvil keeps one ordered patch series per upstream project. The source checkout under .worktrees/<project> is a disposable Git repository; the .patch files and series.json in this repository are the saved work. This design comes from Paper's patch workflow, adapted for normal upstream Git repositories and a single upstream PR at a time.
Paper's current contribution guide separates patches into sources, resources, and features. Source and resource patches change individual Minecraft files. Feature patches are larger commits that can span files. Contributors run ./gradlew applyPatches, edit the generated checkout, then run ./gradlew rebuildPatches. To edit an older feature, they amend or autosquash into its commit, replay later commits, and rebuild the patch files. Paper asks for patch notes in commit bodies when a future maintainer will need the reasoning.
In paperweight's feature apply task, Git starts from a generated base commit and applies feature patches with three-way merge support. A failed apply leaves Git's recovery state in place and reports how to finish. Its rebuild task exports commits with git format-patch. It also avoids showing patch-file changes that only reflect generated header differences.
The PaperSpigot 1.8.8 apply script reset generated API and server repositories to their upstream branches, then ran git am --3way over numbered patch files. On conflict, it left the apply unfinished and told the contributor to repair it and rebuild. The matching rebuild script ran git format-patch from the upstream base, staged the patch directory, and filtered header-only changes. The 1.12.2 scripts added whitespace-tolerant apply, a Windows command-length workaround, and a partial save path during an unfinished apply. The 1.12.2 contribution guide described interactive rebase and fixup commits for editing a patch in the middle of a series.
| Paper idea | StackAnvil behavior |
|---|---|
| Generated checkout with one commit per patch | bun run stack sync <project> applies the ordered series into .worktrees/<project>. |
| Rebuild patches from commits | bun run stack rebuild <project> exports every series commit to its existing filename. |
| Edit an earlier patch and replay later ones | bun run stack edit <project> <patch-file> saves a backup ref and resets to that commit. stack rebuild amends it and cherry-picks later commits. |
| Keep generated headers out of review noise | stack rebuild leaves a patch file alone when only its generated commit ID or Git version footer changed. |
| Keep failed apply state for repair | stack sync saves an apply session. Resolve and stage a conflict, then run stack continue. Run stack abort to discard the failed apply. |
| Patch notes in commit messages | Put the purpose and maintenance details in the commit body. They remain in the exported patch and become the PR change summary. stack add requires a body, and stack rebuild keeps the series title aligned with the commit subject. |
| Independently test a feature | bun run pr check <project> applies only the first feature to clean upstream. CI checks that path for projects with a north-star patch. |
StackAnvil keeps branding, features, and custom separate in series.json. Full builds apply all three groups. The PR checkout applies the first feature directly to the pinned upstream base, so a branding or downstream-only change cannot leak into the upstream PR. The exact patch filenames and order come from series.json; rebuilding does not renumber them.
Paper's per-file source and resource patches solve the problem of editing decompiled Minecraft code. Our four targets are existing Git repositories, so they do not need that layer. We also apply patches one at a time instead of building a large git am argument list. This keeps conflict recovery tied to one explicit series.json entry and avoids the older Windows command-length issue. We do not add Paper-specific source markers to upstream code.
bun run stack sync viabedrock
bun run stack edit viabedrock 0001-cache-converted-resource-packs.patch
# Edit and stage files in .worktrees/viabedrock.
bun run stack rebuild viabedrock
bun run pr check viabedrock
bun run build viabedrockWhen the first feature is ready for upstream, add a non-empty features/<patch-name>.pr.md beside its .patch file. Use it for PR context, review guidance, and testing steps that do not belong in the commit message. Inspect the combined text with bun run pr body <project>. A maintainer uses bun run pr sync <project> to update the fork's north-star branch and its draft PR. The command checks the commit description and PR extra body before pushing. Later feature patches stay in the full stack until earlier changes land upstream.
targets.json sets the default assignees for each upstream PR. bun run pr sync <project> adds missing assignees when it creates or updates the north-star PR. Run bun run pr assign <project> to update an existing PR without pushing its branch. The tool keeps assignees that someone added manually.
| Project | Default assignees |
|---|---|
| ViaBedrock | RaphiMC (RK_01), Exterminate5573 |
| viafabricplus-bedrock | RaphiMC, Exterminate5573, florianreuth |
| ViaFabricPlus | florianreuth |
| CubeConverter | oryxel1 |
These are PR assignees, not review requests. Draft PRs can carry them. GitHub requires upstream assignment access. If your account lacks that access, the command reports the missing assignment and leaves the PR in place. Ask an upstream maintainer to add the listed people. This applies to the ViaFabricPlus and CubeConverter upstream repositories with the current account permissions.
During stack sync, Git may stop in the middle of git am. Inspect git status in .worktrees/<project>, resolve the files, stage them, and run bun run stack continue <project>. The tool finishes the stopped patch, then applies the remaining entries. For a PR-only checkout, use bun run stack continue <project> --pr. If the attempt should be discarded, use stack abort with the same project and optional --pr, then run stack sync again. Do not delete the apply session by hand.
During stack rebuild, a later commit can conflict with an edited earlier patch. Resolve and stage it in the full checkout, then rerun bun run stack rebuild <project>. The edit session tracks how many later commits have replayed. Its backup ref keeps the pre-edit stack reachable until the rebuild succeeds.