Submitting Stacked PRs with jj-spr

Purpose

Submit and manage stacked GitHub PRs using jj-spr. Integrates with jj-workflow-plugin's commit stacking workflow for sharing curated commits as reviewable PRs.

Integration with jj-workflow

Local curation:

/jj:commit "feat: add login UI"
/jj:split test                    # Separate concerns
/jj:squash                         # Clean up WIP commits

Submit to GitHub:

jj spr submit                      # Create PRs for entire stack

The flow: Curate locally → Submit with jj spr submit → Amend commits → Update with jj spr update

Core Commands

Submit PRs

jj spr submit                      # Submit all commits in stack
jj spr submit -r <change-id>       # Submit from specific commit upward
jj spr submit -r <id> --no-deps    # Submit specific commit only

Update PRs

jj spr update                      # Update all PRs with local changes
jj spr update -r <change-id>       # Update specific PR
jj spr update --force              # Force update (skip checks)

View Status

jj spr info                        # Show PR info for commits
jj spr info -r <change-id>         # Show info for specific commit
gh pr list                         # View PRs
gh pr view <pr-number> --web       # Open PR in browser

Common Workflows

Submit Clean Commits

# 1. Build stack locally
/jj:commit "feat(auth): add login endpoint"
/jj:commit "test(auth): add login tests"
/jj:commit "docs(auth): document auth flow"

# 2. Review and curate
jj log
/jj:split test                     # Split if needed
/jj:squash                         # Squash if needed

# 3. Submit
jj spr submit

Result: Each commit becomes a PR, stacked automatically.

Respond to Review Feedback

# 1. Edit specific commit
jj edit <change-id>

# 2. Make changes
# ... edit files ...

# 3. Update description if needed
jj describe -m "feat(auth): add login endpoint

Addressed review feedback:
- Add input validation
- Improve error messages"

# 4. Return to working copy and update PRs
jj new
jj spr update

Result: PR updated, dependent PRs rebased automatically.

Add to Existing Stack

# Add new commits on top
/jj:commit "feat(auth): add password reset"
/jj:commit "test(auth): add reset tests"

# Submit new commits (existing PRs unchanged)
jj spr submit

Fix Bug in Middle of Stack

# Edit earlier commit
jj edit <change-id>

# Fix bug
# ... make changes ...

# Return and update all affected PRs
jj new @+
jj spr update

Reorder Stack

# Reorder with rebase
jj rebase -r <commit> -d <new-parent>

# Update PRs
jj spr update

Split Commit After Submitting

# Edit commit with mixed changes
jj edit <change-id>

# Split
/jj:split "*settings*"

# Return and update
jj new @+
jj spr update

Result: Original PR split into two new PRs.

When to Use jj-spr

Use when:

• Commits clean and ready for review
• Managing dependent features
• Large feature split into reviewable chunks
• Responding to review feedback

Consider alternatives when:

• Single PR (use jj git push + gh pr create)
• Commits still messy (curate first with /jj:commit, /jj:split, /jj:squash)
• Collaborative feature branch (different workflow needed)

Best Practices

Before Submitting

/jj:split test                     # Split mixed concerns
/jj:squash                         # Squash WIP commits
jj log                             # Verify stack order
nix flake check                    # Run tests

Commit Guidelines

• One logical change per commit: "feat(auth): add JWT validation" ✅ not "add login, logout, and profile" ❌
• Clear messages: First line becomes PR title, body becomes description
• Reviewable size: Keep commits focused and small

Stack Management

• Keep stacks shallow (<5 PRs)
• Merge from bottom up
• Note dependencies in PR descriptions

Handling Feedback

• Amend commits, don't add fixup commits
• Update commit messages to reflect changes
• jj spr update syncs PR descriptions

Quick Reference

Common Patterns

Submit entire stack:

jj spr submit

Update after amending:

jj edit <change-id>
# ... make changes ...
jj new
jj spr update

Check stack status:

jj log -T 'concat(change_id.short(), ": ", description)'
jj spr info

Troubleshooting

Wrong base branch:

gh pr edit <pr-number> --base <correct-base>

Out of order:

jj rebase -r <commit> -d <new-parent>
jj spr update

Conflicts after update:

jj rebase -d main
# ... resolve conflicts ...
jj spr update

WIP commits submitted:

gh pr close <pr-number>
/jj:squash                         # Clean up
jj spr submit                      # Resubmit

When This Skill Activates

Use this Skill when:

• User mentions PRs, pull requests, or GitHub reviews
• User asks about sharing work for review
• Working with stacked or dependent PRs
• Need to update PRs after changes
• Discussing code review workflows
• User mentions amending commits that have PRs