From f1d567accc5e6dbfb56265de850cb1cac4188cb5 Mon Sep 17 00:00:00 2001 From: sriram veeraghanta Date: Mon, 20 Apr 2026 17:17:54 +0530 Subject: [PATCH] chore: add Claude Code skills for PR descriptions and release notes (#8920) * chore: add Claude Code skills for PR descriptions and release notes * chore(skills): update release-notes branches to canary->master and example version to v1.3.0 * chore(skills): address PR review comments - pr-description: infer base branch from PR metadata, fix Improvement wording, reference template's screenshot placeholder verbatim - release-notes: add `text` language to unlabeled fenced code block --- .claude/skills/pr-description.md | 58 ++++++++++++ .claude/skills/release-notes.md | 147 +++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 .claude/skills/pr-description.md create mode 100644 .claude/skills/release-notes.md diff --git a/.claude/skills/pr-description.md b/.claude/skills/pr-description.md new file mode 100644 index 0000000000..bfbfa78ba9 --- /dev/null +++ b/.claude/skills/pr-description.md @@ -0,0 +1,58 @@ +--- +name: pr-description +description: Generate a PR description following the project's GitHub PR template. Analyzes the current branch's changes against the base branch to produce a complete, filled-out PR description. +user_invocable: true +--- + +# PR Description Generator + +Generate a pull request description based on the project's PR template at `.github/pull_request_template.md`. + +## Steps + +1. **Determine the base branch**: Prefer the PR's actual `baseRefName` (via `gh pr view --json baseRefName`) when a PR exists. Otherwise default by intent — feature PRs target `preview`, release PRs target `master`. If still ambiguous, ask the user. + +2. **Analyze changes**: Run the following to understand what changed: + - `git log ...HEAD --oneline` to see all commits on this branch + - `git diff ...HEAD --stat` to see which files changed + - `git diff ...HEAD` to read the actual diff (use `--no-color`) + - If the diff is very large, focus on the most important files first + +3. **Fill out the PR template** with the following sections: + + ### Description + + Write a clear, concise summary of what the PR does and why. Focus on the "what" and "why", not line-by-line changes. Mention any important implementation decisions. + + ### Type of Change + + Check the appropriate box(es) based on the changes: + - Bug fix (non-breaking change which fixes an issue) + - Feature (non-breaking change which adds functionality) + - Improvement (non-breaking change that improves existing functionality) + - Code refactoring + - Performance improvements + - Documentation update + + ### Screenshots and Media + + Leave this section for the user to fill in, preserving the existing placeholder comment from `.github/pull_request_template.md` verbatim rather than introducing different text. + + ### Test Scenarios + + Based on the code changes, suggest specific test scenarios that should be verified. Be concrete (e.g., "Navigate to project settings and verify the new toggle works") rather than generic. + + ### References + - If commit messages or branch name reference a work item identifier (e.g., `WEB-1234`), include it + - If the user provides a linked issue, include it + - If Sentry issue links or IDs (e.g., `SENTRY-ABC123`, Sentry URLs) were mentioned earlier in the conversation, include them as references + +4. **Output format**: Print the filled-out markdown template so the user can copy it directly. Do NOT wrap it in a code fence — output the raw markdown. + +## Guidelines + +- Keep the description concise but informative +- Use bullet points for multiple changes +- Focus on user-facing impact, not implementation details +- If the branch has a Plane work item ID in its name (e.g., `WEB-1234`), reference it +- Don't fabricate test scenarios that aren't relevant to the actual changes diff --git a/.claude/skills/release-notes.md b/.claude/skills/release-notes.md new file mode 100644 index 0000000000..af8a7680e7 --- /dev/null +++ b/.claude/skills/release-notes.md @@ -0,0 +1,147 @@ +--- +name: release-notes +description: "Generate release notes for a Plane release PR in `makeplane/plane` (semver, e.g. `release: vX.Y.Z`). Reads PR commits, filters out noise, categorizes by conventional-commit type, optionally enriches via Plane MCP, and writes the result as the PR description." +user_invocable: true +--- + +# Release Notes Generator + +Generate structured release notes from a Plane release PR by parsing its commit list, then update the PR description. + +## Versioning + +Plane community uses **semver** (`vX.Y.Z`, major.minor.patch) for releases. + +- PR title format: `release: vX.Y.Z` +- Source branch: `canary` +- Target branch: `master` + +## When to Use + +- User links/mentions a Plane release PR (e.g. `release: v1.3.0`) and asks for release notes +- User asks to "create release notes" / "update PR description" for a release PR in `makeplane/plane` +- The branch is named `canary` or `release/x.y.z` and the base is `master` + +## Steps + +### 1. Fetch commits + +```bash +gh pr view --json title,body,baseRefName,headRefName,commits \ + --jq '.commits[] | .messageHeadline + "\n---BODY---\n" + .messageBody + "\n===END==="' +``` + +For a quick scan first: + +```bash +gh pr view --json commits \ + --jq '.commits[] | {oid: .oid[0:10], message: .messageHeadline}' +``` + +### 2. Filter out noise + +**Always exclude** these commits — mechanical, not user-facing: + +| Pattern | Reason | +| -------------------------------------------- | -------------- | +| `fix: merge conflicts` | Merge artifact | +| `Merge branch '...' of github.com:...` | Merge artifact | +| `Revert "..."` (when immediately re-applied) | Internal churn | + +### 3. Parse work item IDs + +Most meaningful commits begin with a Plane work item identifier in brackets: + +- `[WEB-XXXX]` — web/frontend product items +- `[SILO-XXXX]` — Silo (integrations: Slack, GitHub, GitLab, Jira/Linear) +- `[MOBILE-XXXX]`, `[API-XXXX]`, etc. + +Always preserve these IDs in the release notes — they let readers click through to the source ticket. + +### 4. (Optional) Enrich via Plane MCP + +For larger features where the commit headline is terse, fetch the work item: + +```text +mcp__plane__retrieve_work_item_by_identifier(project_identifier="WEB", issue_identifier=6874) +``` + +Use the returned `name` and `description_stripped` to flesh out the bullet. Skip this for routine fixes — commit body is usually enough. Don't enrich every item (slow + work item descriptions are often empty). + +### 5. Categorize by conventional-commit type + +| Commit prefix | Section | +| -------------------------------- | ------------------- | +| `feat:`, `feat(scope):` | ✨ New Features | +| `fix:`, `fix(scope):` | 🐛 Bug Fixes | +| `refactor:` | 🔧 Refactor & Chore | +| `chore:`, `chore(scope):` | 🔧 Refactor & Chore | +| `chore(deps):`, dependabot bumps | 📦 Dependencies | + +### 6. Format + +```markdown +# Release vX.Y.Z + +## ✨ New Features + +- **** — [WEB-XXXX] (#PR_NUM) + Optional 1–2 sentence elaboration drawn from commit body. + +## 🐛 Bug Fixes + +- **** — [WEB-XXXX] (#PR_NUM) + +## 🔧 Refactor & Chore + +- **** — [WEB-XXXX] (#PR_NUM) + +## 📦 Dependencies + +- Bump `` X.Y.Z → A.B.C (#PR_NUM) +``` + +Rules: + +- Lead with a bold human-readable title (rewrite the commit subject if cryptic) +- Always include the work item ID in brackets and the merge PR number in parens +- Add a sub-line elaboration only when the commit body has substance worth surfacing (acceptance criteria, scope notes, gotchas like "behind feature flag", "requires migration", "requires Vercel setting") +- Drop empty sections + +### 7. Update the PR description + +```bash +gh pr edit --body "$(cat <<'EOF' + +EOF +)" +``` + +Always use a HEREDOC with single-quoted `'EOF'` so backticks/dollars in the notes are preserved. + +## Quick Reference: end-to-end + +```bash +PR=2498 +gh pr view $PR --json commits --jq '.commits[] | .messageHeadline + "\n---\n" + .messageBody + "\n==="' > /tmp/commits.txt +# read /tmp/commits.txt, filter, categorize, draft notes +gh pr edit $PR --body "$(cat <<'EOF' +... release notes ... +EOF +)" +``` + +## Common Mistakes + +- **Including `fix: merge conflicts`** — merge artifact, no functional content +- **Dropping the work item ID** — readers rely on `[WEB-XXXX]` to navigate to the ticket +- **Over-enriching with MCP lookups** — work item descriptions are often empty; commit body is usually richer +- **Missing the merge PR number** — always include `(#NNNN)` from the commit subject so reviewers can audit the source PR +- **Using `--body` without HEREDOC** — backticks/dollar signs get shell-interpreted and corrupt the notes +- **Editing the title** — release PR titles are version markers; only edit the body + +## Plane-Specific Conventions + +- Release PRs go from `canary` → `master` +- PR title format: `release: vX.Y.Z` semver (major.minor.patch) +- Commits coming from feature branches always carry a work item ID; commits without one are usually infra/chores