create-java-pr

---
name: create-java-pr
description: Create a pull request in sentry-java. Use when asked to "create pr", "prepare pr", "prep pr", "open pr", "ready for pr", "prepare for review", "finalize changes". Handles branch creation, code formatting, API dump, committing, pushing, PR creation, changelog, and stacked PRs.
---

# Create Pull Request (sentry-java)

Prepare local changes and create a pull request for the sentry-java repo.

**For stacked PRs:** read `references/stacked-prs.md` before proceeding. It is the source of truth for
stack structure, title naming, stack list format, and merge strategy.

## Step 0: Determine PR Type From Git Branch Context

Infer PR type from the current branch before asking the user.

1. Get current branch:

```bash
git branch --show-current
```

2. Apply these rules:

- **If branch is `main` or `master`**: default to a **standalone PR**.
  - Do **not** assume stack mode from `main`.
  - Only use stack mode if the user explicitly asks for a stacked PR.
- **If branch is not `main`/`master`**:
  - Check whether that branch already has a PR and what its base is:
    ```bash
    gh pr list --head "$(git branch --show-current)" --json number,baseRefName,title --jq '.[0]'
    ```
  - If that branch PR exists and `baseRefName` is **not** `main`/`master`, treat the work as a **stacked PR context**.
  - If that branch PR exists and `baseRefName` **is** `main`/`master`, also check whether other PRs target the current branch:
    ```bash
    gh pr list --base "$(git branch --show-current)" --json number,headRefName,title
    ```
    - If there are downstream PRs, treat this as **next PR in an existing stack** with the current branch as the stack base (collection branch).
    - If there are no downstream PRs, treat it as **standalone PR context**.
  - If no PR exists for the current branch, check whether other PRs target it:
    ```bash
    gh pr list --base "$(git branch --show-current)" --json number,headRefName,title
    ```
    - If there are downstream PRs, treat this as **next PR in an existing stack** with the current branch as the stack base (collection branch).
    - If there are no downstream PRs either, treat it as **standalone PR context** (fresh feature branch).

3. If signals are mixed or ambiguous, ask one focused question to confirm.

PR types:
- **Standalone PR** — regular PR targeting `main`.
- **First PR of a new stack** — create collection branch from `main`, then first PR off it.
- **Next PR in an existing stack** — target the current stack base branch (usually the previous stack PR branch, or the collection branch if creating the first follow-up PR from the collection branch).

If the user explicitly says "stack", "stacked PR", or provides numbered stack titles (e.g. `[Topic 2]`), honor that even if branch heuristics are inconclusive.

## Step 1: Ensure Feature Branch

```bash
git branch --show-current
```

If on `main` or `master`, create and switch to a new branch:

```bash
git checkout -b <type>/<short-description>
```

Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`, etc. matching the commit type conventions.

**For stacked PRs:** For the first PR in a new stack, first create and push the collection branch (see `references/stacked-prs.md` § "Why a Collection Branch"), then branch the PR off it. For subsequent PRs, branch off the previous stack branch. Give every branch in the stack a shared prefix naming the feature, with a descriptive suffix per PR.

**CRITICAL: Never merge, fast-forward, or push commits into the collection branch.** It stays at its initial position until the user merges stack PRs through GitHub. Updating it will auto-merge and destroy the entire PR stack.

## Step 2: Format Code and Regenerate API Files

```bash
./gradlew spotlessApply apiDump
```

This is **required** before every PR in this repo. It formats all Java/Kotlin code via Spotless and regenerates the `.api` binary compatibility files.

If the command fails, diagnose and fix the issue before continuing.

## Step 3: Commit Changes

Check for uncommitted changes:

```bash
git status --porcelain
```

If there are uncommitted changes, invoke the `sentry-skills:commit` skill to stage and commit them following [Sentry commit message conventions](https://develop.sentry.dev/engineering-practices/commit-messages/):

```
<type>(<scope>): <subject>
```

Allowed types: `feat`, `fix`, `ref`, `chore`, `docs`, `test`, `perf`, `build`, `ci`, `style`, `meta`, `license`

**Important:** When staging, ignore changes that are only relevant for local testing and should not be part of the PR. Common examples:

| Ignore Pattern | Reason |
|---|---|
| Hardcoded booleans flipped for testing | Local debug toggles |
| Sample app config changes (`sentry-samples/`) | Local testing configuration |
| `.env` or credentials files | Secrets |

Restore these files before committing:

```bash
git checkout -- <file-to-restore>
```

## Step 4: Push the Branch

```bash
git push -u origin HEAD
```

If the push fails due to diverged history, ask the user how to proceed rather than force-pushing.

## Step 5: Create PR

Invoke the `sentry-skills:create-pr` skill to create a draft PR.

Read `.github/pull_request_template.md` and use it as the PR body structure — it is the single source
of truth for the sections and checklist, so never reproduce it from memory. Fill in each section based
on the changes being PR'd, drop the HTML comment hints, and check any checklist items that apply.

**PR title format** — same as the commit subject (Step 3):

```
<type>(<scope>): <Subject>
```

Examples:
- `feat(core): Add structured logging support`
- `fix(android): Prevent crash on API 21 when registering receiver`

**For stacked PRs:**

- Pass `--base <previous-stack-branch>` so the PR targets the previous branch (first PR in a stack targets the collection branch).
- Use the stacked PR title format: `<type>(<scope>): [<Topic> <N>] <Subject>` (see `references/stacked-prs.md` § "PR Title Naming").
- Include the stack list at the top of the PR body, before the `## :scroll: Description` section (see `references/stacked-prs.md` § "Stack List in PR Description" for the format).
- Add a merge method reminder at the very end of the PR body (see `references/stacked-prs.md` § "Stack List in PR Description" for the exact text). This only applies to stack PRs, not the collection branch PR.

Then continue to Step 5.5 (stacked PRs only) or Step 6.

## Step 5.5: Update Stack List on All PRs (stacked PRs only)

Skip this step for standalone PRs.

After creating the PR, update the PR description on **every other PR in the stack — including the collection branch PR** — so all PRs have the same up-to-date stack list. Follow the format and commands in `references/stacked-prs.md` § "Stack List in PR Description".

Edit each body using the procedure in § "Editing PR Descriptions" below.

## Step 6: Update Changelog

First, determine whether a changelog entry is needed. **Skip this step** (and go straight to "No changelog needed" below) if the changes are not user-facing, for example:

- Test-only changes (new tests, test refactors, test fixtures)
- CI/CD or build configuration changes
- Documentation-only changes
- Code comments or formatting-only changes
- Internal refactors with no behavior change visible to SDK users
- Sample app changes

If unsure, ask the user.

### If changelog is needed

Add an entry to `CHANGELOG.md` under the `## Unreleased` section.

#### Determine the subsection

| Change Type | Subsection |
|---|---|
| New feature | `### Features` |
| Bug fix | `### Fixes` |
| Refactoring, internal cleanup | `### Internal` |
| Dependency update | `### Dependencies` |

Create the subsection under `## Unreleased` if it does not already exist.

**When rebasing:** A rebase onto `main` can land your branch after a release was cut, where the `## Unreleased` heading your entry lived under has since been renamed to that version number. If that happens, move your new entry into an `## Unreleased` section at the top of `CHANGELOG.md` (create the section if it no longer exists) so it is not left under an already-released version.

#### Entry format

```markdown
- <Short description of the change> ([#<PR_NUMBER>](https://github.com/getsentry/sentry-java/pull/<PR_NUMBER>))
```

Use the PR number returned by `sentry-skills:create-pr`. Match the style of existing entries — sentence case, ending with the PR link, no trailing period.

#### Commit and push

Stage `CHANGELOG.md`, commit with message `changelog`, and push:

```bash
git add CHANGELOG.md
git commit -m "changelog"
git push
```

### No changelog needed

If no changelog entry is needed, append `#skip-changelog` to the end of the PR description to disable
the changelog CI check, using the procedure in § "Editing PR Descriptions" below.

## Editing PR Descriptions

Do not use shell redirects (`>`, `>>`), pipes (`|`), or compound commands (`&&`, `||`). These create
compound shell expressions that won't match permission patterns. Instead:

1. Read the body with `gh pr view <PR_NUMBER> --json body --jq '.body'` (output is returned directly)
2. Use the `Write` tool to save it to `/tmp/pr-body.md`, and the `Edit` tool to modify it
3. Update with `gh pr edit <PR_NUMBER> --body-file /tmp/pr-body.md`