juanjosegongi/creating-bitbucket-prs

Create PRs on Bitbucket using the bkt CLI. If the repo ships its own templates (templates/git/pr.md) or CI conventions (docs/engineering/ci-pipeline.md, git-commits.md, code-review.md), follow them — they encode local rules that override the generic flow below.

Step 1 — Gather context

git log $(git merge-base HEAD master)..HEAD --oneline
git diff master...HEAD --stat

Identify: what changed, why, behavior changes, dependency PRs.

Step 2 — Run local checks

Run the local pipeline before pushing. Fix any failures first.

If the repo has a scripts/ directory mirroring CI (e.g. scripts/check_commits.sh, scripts/check_complexity.sh, scripts/check_security.sh), run those. Otherwise, run the project's standard test/lint commands.

Do not push if local checks are failing.

Step 3 — Push and verify remote pipeline

git push -u origin HEAD

Poll the pipeline until it completes:

PIPELINE_UUID=$(bkt pipeline list --json \
  --jq '[.[] | select(.target.ref_name == "'"$(git branch --show-current)"'")][0].uuid')
bkt pipeline view "$PIPELINE_UUID" --json --jq '.state.name'

Wait for state COMPLETED with SUCCESSFUL result. Do not create the PR if the pipeline is failing.

Some repos disable feature-branch pipelines (CI only fires post-merge or via PR). If bkt pipeline list returns nothing for your branch, that's fine — rely on local checks instead.

Step 4 — Build description

If the repo has templates/git/pr.md, read it and fill every field. Replace placeholders with real values — do not remove fields.

Common conventions:

• Non-bug-fix PRs: Is this a bug fix? NO, leave severity/link/duration blank.
• Proposal: link to formal proposal doc, or N/A.
• Dependencies: full PR URLs (e.g. https://bitbucket.org/<workspace>/<repo>/pull-requests/123), never Jira ticket links.
• No UI change → N/A in the screenshot section.

Answer with the value only. Every field takes a value, not an essay. No suffixes, no parenthetical caveats, no justification in the yes/no answers. If context matters, put it in This pull request is important because — never in short-answer fields.

A bug fix is a production bug. Bug Tracking only applies when the bug ran in production and affected real traffic. Test-only, CI-only, build-only, or otherwise pre-production corrections are NOT bug fixes — mark Is this a bug fix? NO, leave every Bug Tracking field blank, and explain the change in This pull request is important because.

Bug-tracking fields (only when Is this a bug fix? YES):

• Bug severity: a single digit 1-5. Nothing else.
• Link to PR that introduced the bug: a Bitbucket PR URL. Never a commit hash. Find it via git log --merges --ancestry-path <bug-commit>..HEAD or by reading the bug commit's merge-commit message (Merged in … (pull request #N)).
• How long did the bug live in production: a duration (e.g. 5 months). If this would be 0 or N/A, the PR is not a bug fix — flip Is this a bug fix? to NO instead.
• Explain the bug: one or two sentences — what broke, where, and the symptom.
• What can we do to prevent this bug in the future: one sentence — the concrete prevention (a check, a test, a cron).

Ask the user for anything vague or missing — proposal link, staging/production test coverage, doc updates. Do not guess, do not leave placeholders.

Step 5 — Create PR

Capture the PR id on creation so downstream steps don't need manual substitution:

PR_ID=$(bkt pr create \
  --json --jq '.id' \
  --title "<title>" \
  --source "<branch>" \
  --target "master" \
  --description "$(cat <<'EOF'
<description>
EOF
)")
echo "Created PR #$PR_ID"

Persist $PR_ID in the shell session — bitbucket-receiving-code-review reuses it and derives $REPO_PATH itself.

• Title format: TICKET-ID Short description (e.g. AL-596 Add PR creation skill). Under 70 chars, imperative mood.
• If the repo uses a bot that owns the title (betico-style), never edit the title manually after creation.
• Target: usually master or main. Never chain PRs onto other feature branches.

Bitbucket CLI gotchas:

• bkt api -d is the data flag (not --data).
• bkt api --jq requires --json.
• bkt api -d @file does NOT work (it parses @ literally as JSON). Use -d "$(cat file)" instead.
• bkt pr create uses --source / --target (not --destination).

Step 6 — Ready-gate handoff

If the repo has a bot ready-gate (betico-style), you signal readiness with a top-level comment:

• Post bot: ready when ALL of these are true:
  • Every dependency PR listed in the Dependencies field has merged. Unmerged dependency → bot: not ready, no exceptions.
  • Every review thread is resolved via the resolve-comment API.
  • The latest pipeline run is COMPLETED + SUCCESSFUL.
  • Self-review pass found nothing new.
• Post bot: not ready when any of the above is false.

REMOTE_URL=$(git remote get-url origin)
REPO_PATH=$(echo "$REMOTE_URL" | sed -E 's#.*/([^/]+/[^/]+?)(\.git)?$#\1#')

bkt api "/repositories/${REPO_PATH}/pullrequests/${PR_ID}/comments" \
  --method POST \
  --input '{"content": {"raw": "bot: ready"}}'

Detailed comment-resolve and ready-gate procedure lives in bitbucket-receiving-code-review.

Step 7 — Monitor

After the PR is created, start the review loop. Invoke bitbucket-receiving-code-review and keep it running on an hourly cadence during working hours on weekdays. It polls for comments, responds, drives threads to resolution, and posts the bot: ready / bot: not ready signal.

Splitting large changes

PRs must be small and easy to review. If a branch covers too much, split:

1. Identify logical units that can stand alone (models, logic, UI, tests).
2. One branch + one PR per unit.
3. All PRs target master (or main) — never chain PRs onto other feature branches.
4. If PR B depends on PR A, list PR A's full URL in B's Dependencies field.

Rules

• Small PRs: keep each one focused. Split when in doubt.
• Target: always master (or repo default).
• Dependencies: full PR URLs, never Jira ticket links.
• Ready-gate: bot: ready requires every dependency PR to be merged. Unmerged dependency → bot: not ready.
• Title: imperative, under 70 chars, TICKET-ID Short description.
• Title after creation: bot-owned if the repo uses one. Do not edit manually.
• Behavior changes: called out specifically in the PR description.
• No UI change: N/A in the screenshot section.
• Answer fields: values only — no suffixes, no caveats, no justification. Context goes in This pull request is important because.
• A bug fix is a production bug. Test-only, CI-only, or build-only fixes are Is this a bug fix? NO with the rest of the Bug Tracking section left blank.
• Bug severity: a digit 1-5. Nothing else.
• Bug introduction link: Bitbucket PR URL. Never a commit hash.