diff --git a/.claude/skills/create-java-pr/SKILL.md b/.claude/skills/create-java-pr/SKILL.md index e2a9b9bc785..cc781ab7de7 100644 --- a/.claude/skills/create-java-pr/SKILL.md +++ b/.claude/skills/create-java-pr/SKILL.md @@ -7,7 +7,10 @@ description: Create a pull request in sentry-java. Use when asked to "create pr" Prepare local changes and create a pull request for the sentry-java repo. -**Required reading:** Before proceeding, read `.cursor/rules/pr.mdc` for the full PR and stacked PR workflow details. That file is the source of truth for PR conventions, stack comment format, branch naming, and merge strategy. +**Required reading:** Read `.cursor/rules/pr.mdc` before proceeding. It is the source of +truth for every convention referenced below — branch naming, commit format, PR body +template, changelog subsections, stack list format, and merge strategy. This skill is the +procedure; `pr.mdc` is the reference. ## Step 0: Determine PR Type From Git Branch Context @@ -54,21 +57,16 @@ If the user explicitly says "stack", "stacked PR", or provides numbered stack ti ## 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 / -``` +If on `main` or `master`, create and switch to a new branch, deriving the name from the +changes being made. See `pr.mdc` § "Step 1: Ensure Feature Branch" for naming. -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, create and push the collection branch +first (`pr.mdc` § "Creating the Collection Branch"), then branch the PR off it. For +subsequent PRs, branch off the previous stack branch. Naming: `pr.mdc` § "Branch Naming". -**For stacked PRs:** For the first PR in a new stack, first create and push the collection branch (see `.cursor/rules/pr.mdc` § "Creating the Collection Branch"), then branch the PR off it. For subsequent PRs, branch off the previous stack branch. Use the naming conventions from `.cursor/rules/pr.mdc` § "Branch Naming". - -**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. +**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 @@ -76,9 +74,7 @@ Derive the branch name from the changes being made. Use `feat/`, `fix/`, `ref/`, ./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. +Required before every PR in this repo. If it fails, diagnose and fix before continuing. ## Step 3: Commit Changes @@ -88,17 +84,11 @@ Check for uncommitted changes: git status --porcelain ``` -If there are uncommitted changes, invoke the `sentry-skills:commit` skill to stage and commit them following Sentry conventions. - -**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 | +If there are uncommitted changes, invoke the `sentry-skills:commit` skill to stage and +commit them following Sentry conventions. -Restore these files before committing: +**Important:** Leave out changes that are only relevant for local testing — hardcoded debug +toggles, sample app config, `.env` or credentials files. Restore them before committing: ```bash git checkout -- @@ -110,61 +100,38 @@ git checkout -- git push -u origin HEAD ``` -If the push fails due to diverged history, ask the user how to proceed rather than force-pushing. +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. When providing the PR body, use the repo's PR template structure from `.github/pull_request_template.md`: - -``` -## :scroll: Description - - -## :bulb: Motivation and Context - - -## :green_heart: How did you test it? - - -## :pencil: Checklist -- [ ] I added GH Issue ID _&_ Linear ID -- [ ] I added tests to verify the changes. -- [ ] No new PII added or SDK only sends newly added PII if `sendDefaultPII` is enabled. -- [ ] I updated the docs if needed. -- [ ] I updated the wizard if needed. -- [ ] Review from the native team if needed. -- [ ] No breaking change or entry added to the changelog. -- [ ] No breaking change for hybrid SDKs or communicated to hybrid SDKs. - -## :crystal_ball: Next steps -``` - -Fill in each section based on the changes being PR'd. Check any checklist items that apply. +Invoke the `sentry-skills:create-pr` skill to create a draft PR. Use the repo's PR template +at `.github/pull_request_template.md` for the body, filling in each section based on the +changes and checking any checklist items that apply. -**For stacked PRs:** +**For stacked PRs**, additionally: -- Pass `--base ` so the PR targets the previous branch (first PR in a stack targets the collection branch). -- Use the stacked PR title format: `(): [ ] ` (see `.cursor/rules/pr.mdc` § "PR Title Naming"). -- Include the stack list at the top of the PR body, before the `## :scroll: Description` section (see `.cursor/rules/pr.mdc` § "Stack List in PR Description" for the format). -- Add a merge method reminder at the very end of the PR body (see `.cursor/rules/pr.mdc` § "Stack List in PR Description" for the exact text). This only applies to stack PRs, not the collection branch PR. +- Pass `--base ` (the collection branch for the first PR in a stack). +- Use the stacked PR title format from `pr.mdc` § "PR Title Naming". +- Add the stack list at the top of the body, before `## :scroll: Description` + (`pr.mdc` § "Stack List in PR Description"). +- Add the merge method reminder at the very end of the body (same section). Stack PRs only, + 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 `.cursor/rules/pr.mdc` § "Stack List in PR Description". +Skip for standalone PRs. -**Important:** When updating PR bodies, never use shell redirects (`>`, `>>`) or pipes (`|`) or compound commands (`&&`). These create compound shell expressions that won't match permission patterns. Instead: -- Use `gh pr view --json body --jq '.body'` to get the body (output returned directly) -- Use the `Write` tool to save it to a temp file -- Use the `Edit` tool to modify the temp file -- Use `gh pr edit --body-file /tmp/pr-body.md` to update +After creating the PR, update the description on **every other PR in the stack — including +the collection branch PR** so they all carry the same up-to-date stack list. Format and +commands: `pr.mdc` § "Stack List in PR Description". ## 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: +First decide whether an entry is needed. **Skip to "No changelog needed"** if the changes +are not user-facing, for example: - Test-only changes (new tests, test refactors, test fixtures) - CI/CD or build configuration changes @@ -177,41 +144,21 @@ 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. - -#### Entry format - -```markdown -- ([#](https://github.com/getsentry/sentry-java/pull/)) -``` - -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. +Add an entry to `CHANGELOG.md` under `## Unreleased`, using the subsection table and entry +format in `pr.mdc` § "Step 6: Update Changelog". Use the PR number returned by +`sentry-skills:create-pr`, and match the style of surrounding entries. -#### Commit and push - -Stage `CHANGELOG.md`, commit with message `changelog`, and push: - -```bash -git add CHANGELOG.md -git commit -m "changelog" -git push -``` +Then stage, commit with the message `changelog`, and push. ### No changelog needed -If no changelog entry is needed, add `#skip-changelog` to the PR description to disable the changelog CI check: +Add `#skip-changelog` to the PR description to disable the changelog CI check: 1. Get the current body: `gh pr view --json body --jq '.body'` 2. Use the `Write` tool to save the output to `/tmp/pr-body.md`, appending `\n#skip-changelog\n` at the end 3. Update: `gh pr edit --body-file /tmp/pr-body.md` + +**Note:** When updating PR bodies, never use shell redirects (`>`, `>>`), pipes (`|`), or +compound commands (`&&`). These form compound shell expressions that won't match permission +patterns. Use `gh pr view --json body --jq '.body'` to read, the `Write`/`Edit` tools to +modify a temp file, and `gh pr edit --body-file` to write back. diff --git a/.cursor/rules/pr.mdc b/.cursor/rules/pr.mdc index 3a37ecc15f8..337b53ab8c0 100644 --- a/.cursor/rules/pr.mdc +++ b/.cursor/rules/pr.mdc @@ -39,7 +39,7 @@ Allowed types: `feat`, `fix`, `ref`, `chore`, `docs`, `test`, `perf`, `build`, ` - Use imperative present tense ("add" not "added") - Capitalize subject, no trailing period -- Keep under 100 characters +- Keep the subject under 70 characters ### Step 4: Push @@ -51,30 +51,9 @@ If push fails due to diverged history, ask the user — do not force-push. ### Step 5: Create PR -Create a draft PR using the repo's PR template: - -```markdown -## :scroll: Description - - -## :bulb: Motivation and Context - - -## :green_heart: How did you test it? - - -## :pencil: Checklist -- [ ] I added GH Issue ID _&_ Linear ID -- [ ] I added tests to verify the changes. -- [ ] No new PII added or SDK only sends newly added PII if `sendDefaultPII` is enabled. -- [ ] I updated the docs if needed. -- [ ] I updated the wizard if needed. -- [ ] Review from the native team if needed. -- [ ] No breaking change or entry added to the changelog. -- [ ] No breaking change for hybrid SDKs or communicated to hybrid SDKs. - -## :crystal_ball: Next steps -``` +Create a draft PR using the repo's PR template at `.github/pull_request_template.md`. Read +that file for the current section structure and checklist, fill in each section, and check +the checklist items that apply. ### Step 6: Update Changelog