From 877901a36d25070210b77317b3e0328c6afca202 Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Tue, 11 Aug 2026 11:53:21 +0200 Subject: [PATCH] docs(agents): Make create-java-pr defer to pr.mdc for conventions The skill declared pr.mdc the source of truth and then restated most of it anyway: branch naming, commit conventions, the full PR template, the changelog subsection table, entry format, and the stack list warnings all existed in both files. Two copies of the same conventions drift apart. Keep the procedure in the skill (ordered steps and the branch-type detection heuristic, which pr.mdc does not cover) and point at pr.mdc for each convention. Also drop the inlined PR template from pr.mdc in favor of .github/pull_request_template.md, so the template lives in one place, and correct the commit subject limit from 100 to 70 characters to match Sentry's commit message conventions. --- .claude/skills/create-java-pr/SKILL.md | 143 ++++++++----------------- .cursor/rules/pr.mdc | 29 +---- 2 files changed, 49 insertions(+), 123 deletions(-) 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