merge-pr

Prompt file imported from jimchurches/myebirdstuff (.cursor/commands/merge-pr.md). Copyright stays with the author.

Merge Pull Request (myebirdstuff)

You are merging the current completed feature/bug branch into its target integration branch for myebirdstuff.

Default workflow

• Default target branch: beta-next
• Use another target when the issue, PR, or user specifies it (e.g. merge into feat/social-cards for Social Cards issue branches) — see base branch resolution
• After merge, switch to the updated target branch
• Label finalised linked issues pending-merge after a clean merge (context-aware; see Step 8)
• Delete the merged feature branch only if the merge succeeds cleanly

Step 1 — Confirm merge intent

Before doing anything:

1. Confirm the current branch name
2. Confirm the target branch — default beta-next; resolve from linked issue / open PR / user when not standard (see base-branch-resolution.md)
3. Confirm there are no uncommitted changes on the current branch
   • if there are, stop and ask what to do

Do not proceed if the branch is not ready.

Step 2 — Update local state

From the repo root:

1. Fetch latest remote state
2. Switch to the target branch
3. Pull latest target branch from origin
4. Switch back to the feature branch
5. Confirm feature branch is up to date enough to merge safely

If there are problems at this stage, stop and report them.

Step 3 — Run quality gate before merge

If Python code is involved, run:

python3 -m ruff check explorer/ python3 -m pytest tests/ -q

If checks fail:

• stop
• report the failures clearly
• do not merge

Do not continue with a known failing branch unless explicitly instructed.

Step 4 — Perform a non-fast-forward merge

Merge the current branch into the target branch using a merge commit.

Use this sequence:

1. Switch to the target branch
2. Run:

git merge --no-ff

If there is a merge conflict or any merge problem:

• stop immediately
• do not try to resolve automatically
• do not continue
• report the conflict clearly

Only continue if the merge succeeds cleanly.

Step 5 — Create merge commit message

Use a clean merge commit message based on the branch, commits, and linked issues.

Format:

: (#)

Refs: #

Rules:

• keep the first line short and meaningful
• use one of:
  • feat:
  • fix:
  • refactor:
  • ui:
  • data:
• do not dump the whole PR description into the commit message
• if PR number is not known, omit it
• if no issue numbers are known, omit the Refs line

Example:

ui: improve hybrid basemap marker visibility

Refs: #138, #141

If Git requires a merge message editor, replace the default generated merge text with the standard format above.

Step 6 — Validate merged target branch

After the merge succeeds, run:

python3 -m ruff check explorer/ python3 -m pytest tests/ -q

If these fail after merge:

• stop
• report clearly
• do not delete the feature branch
• do not push until the user decides what to do

Step 7 — Push merged target branch

If everything succeeds, push the updated target branch:

git push origin

Ask for network permission if required.

If push fails:

• stop
• report clearly
• do not delete the feature branch

Step 8 — Label finalised issues as pending-merge

After a successful merge and push, add the pending-merge label to each linked issue that this merge finalises.

Meaning of the label: the issue's work is complete and merged, and is awaiting production release on main. Use pending-merge for every finalising merge — whether the target is beta-next or a long-lived feature branch (e.g. feat/social-cards). The label does not mean "pending merge to beta-next"; it means done in development, pending release to production. The issue is fully closed only when the change reaches main, not here.

Label hygiene: use pending-merge only. Do not create or use pending-next — that was an obsolete mistaken label (confused with beta-next). If you see pending-next on an issue, remove it and use pending-merge when appropriate.

Decide which issues to label

1. Identify linked issues from the branch name (e.g. 310-... → #310), the merge commit Refs: line, and the PR body / commits.
2. Default: apply the label to issues this PR finalises — typically those referenced with Fixes #, Closes #, or Resolves #, or otherwise described as completed by this work.
3. Skip (context-aware) when:
   • the user said the issue is not finalised / still has follow-up work
   • the work is a sub-issue or only partially addresses a parent issue (often referenced as Refs # rather than Fixes #)
   • the PR does not close or finalise any issue (pure chore / engineering tweak)
4. If it is unclear whether an issue is finalised, ask before labelling rather than guessing.

Apply the label

For each issue to label (network required; ask for permission if needed):

gh issue edit <issue-number> --add-label "pending-merge"

If the label does not exist yet, create it once, then retry:

gh label create "pending-merge" --description "Work complete and merged; awaiting production release on main" --color FBCA04

Labelling is non-fatal: if it fails (e.g. permissions or a missing label that cannot be created), report it clearly but keep the successful merge. Do not undo the merge over a label problem.

If the label description is empty or outdated on GitHub, update it once: gh label edit pending-merge --description "Work complete and merged; awaiting production release on main"

Step 9 — Delete merged feature branch

Only if all of the following are true:

• merge succeeded cleanly
• post-merge checks passed
• push succeeded

Then:

1. Delete local feature branch: git branch -d

2. If appropriate and safe, delete remote feature branch: git push origin --delete

If branch deletion fails, report it but keep the successful merge.

Step 10 — Final state

When complete:

1. Ensure the checked-out branch is the updated target branch
2. Summarise:
   • merged branch
   • target branch
   • merge commit message
   • which issues were labelled pending-merge (or why labelling was skipped)
   • whether local branch was deleted
   • whether remote branch was deleted
   • whether anything needs manual follow-up

Do not

• Do not merge with conflicts
• Do not auto-resolve conflicts
• Do not force push
• Do not rewrite history
• Do not delete the branch if merge, tests, or push failed
• Do not label an issue pending-merge when it is not finalised (follow-up remains, sub-issue, or only Refs #) — ask if unsure
• Do not fully close issues here; pending-merge tracks them until the change reaches main
• Do not continue past any uncertainty without asking

Preferred behaviour

Be conservative.

If anything is unclear or risky:

• stop
• explain the issue
• ask before continuing