patch-stack-action

Patch Stack

Manage patch-stack forks powered by DJRHails/patch-stack-action.

When to use

• The repo references DJRHails/patch-stack-action in a workflow
• Commits on main are prefixed with patch-stack:
• The repo has patch/* branches
• The user wants to set up a new patch-stack fork

Concepts

A patch-stack fork maintains a clean separation between upstream code and your changes:

Branch	What it is
base (or configured name)	Read-only mirror of upstream main. Updated automatically by the nightly sync. Never commit to this directly.
patch/*	One branch per logical change. Each is rebased onto base automatically. This is where you do your work.
main	The integration branch. Built automatically: base + all patches squash-merged (prefixed patch-stack:). Never commit to this directly except fork: prefixed commits for fork-specific infra.

Key rule: main is rebuilt from scratch on every sync. Only fork: prefixed commits and patch-stack: squash-merges survive. All real work happens on patch/* branches.

Day-to-day patch editing workflow

Creating a new patch

Every patch needs three things: a patch/* branch from base, a push, and a local PR targeting base.

# 1. Always branch from base, not main
git checkout -b patch/my-feature origin/base

# 2. Make your changes, commit
git add <files>
git commit -m "feat(scope): description"

# 3. Push
git push origin patch/my-feature

# 4. ALWAYS create a PR targeting base (not main)
gh pr create --head patch/my-feature --base base

The PR against base is required. The sync action uses it to track patch state, generate squash commit messages on main, and link to upstream PRs. Without it the patch is invisible to the workflow.

Editing an existing patch

# Check out the patch branch
git checkout patch/my-feature

# Or use a worktree to avoid leaving main
git worktree add .data/worktrees/my-feature patch/my-feature