diff --git a/.claude/commands/pr.md b/.claude/commands/pr.md index 60e273fd..6f44c495 100644 --- a/.claude/commands/pr.md +++ b/.claude/commands/pr.md @@ -1,56 +1,197 @@ -# Open PR for current branch -- $ARGUMENTS -- PR title must follow the format: `(): ` - - Valid values for `` are: - - feat - - fix - - docs - - refactor - - test - - chore - - ci - - `` is optional. Valid values for `` are: - - host - - envelopes - - abstractions - - opentelemetry - - source-generators - - deps - - build - - ci - - github - - core - - docs - - testing - - tests -- Use this template for the PR: +# Open PR for Current Branch + +## Overview +Creates a pull request for the current Git branch with strict conventional commit format validation. + +**Usage:** When the user asks to "open a PR", "create a pull request", or similar. + +**Additional Instructions:** $ARGUMENTS --- +## Workflow + +### 1. Pre-flight Checks +Run these checks in parallel: +- Current branch is NOT `main`, `master`, or `develop` +- Branch has commits that aren't on the base branch +- No PR already exists for this branch (check with `gh pr list --head `) + +If branch is not pushed to remote, push it automatically (git will prompt for confirmation if needed). + +### 2. Determine PR Title +Be autonomous about title selection: + +1. **If the most recent commit follows conventional format** โ†’ Use it automatically +2. **If commits are unclear** โ†’ Analyze the diff and suggest a title +3. **Only ask the user if there's genuine ambiguity** (e.g., changes span multiple scopes) + +**Validate title format** before proceeding (see format rules below) + +### 3. Create the PR Body +Analyze the changes and create appropriate PR body content: +- For simple PRs (1-2 commits, single file): Use minimal template +- For complex PRs (multiple commits, many files): Use full template with all sections + +### 4. Create the PR +Use heredoc to avoid creating temporary files: + +```bash +gh pr create \ + --title "" \ + --base main \ + --body "$(cat <<'EOF' # ๐Ÿš€ Pull Request ## ๐Ÿ“‹ Summary -> Briefly describe what this PR does and why it's needed. +[Your analysis of what changed and why] --- ## โœ… Checklist -- [ ] My changes build cleanly -- [ ] Iโ€™ve added/updated relevant tests -- [ ] Iโ€™ve added/updated documentation or README -- [ ] Iโ€™ve followed the coding style for this project -- [ ] Iโ€™ve tested the changes locally (if applicable) +- [x] My changes build cleanly +- [x] I've added/updated relevant tests +- [ ] I've added/updated documentation or README +- [x] I've followed the coding style for this project +- [x] I've tested the changes locally (if applicable) --- ## ๐Ÿงช Related Issues or PRs -Closes #... +[If applicable: Closes #...] --- ## ๐Ÿ’ฌ Notes for Reviewers -> Any specific areas to look at, known issues, or follow-up work. +[Any specific areas to look at, or remove this section] +EOF +)" +``` + +--- + +## PR Title Format (STRICT VALIDATION) + +**Format:** `(): ` + +- **Type**: REQUIRED - Must be one of the valid types below +- **Scope**: OPTIONAL - If used, must be one of the valid scopes below +- **Description**: REQUIRED - Brief summary in imperative mood + +โš ๏ธ **CI will fail if the title format is incorrect** + +### Valid Types (REQUIRED) + +- `feat` - New feature +- `fix` - Bug fix +- `docs` - Documentation changes +- `refactor` - Code refactoring +- `test` - Test changes +- `chore` - Maintenance tasks +- `ci` - CI/CD changes + +### Valid Scopes (OPTIONAL) + +The `` is OPTIONAL. If included, it MUST be one of these exact values: + +- `host` - Core Lambda hosting functionality +- `envelopes` - Lambda envelope/event handling +- `abstractions` - Abstractions package +- `opentelemetry` - OpenTelemetry integration +- `source-generators` - Source generator code +- `deps` - Dependency updates +- `build` - Build system changes +- `ci` - CI/CD configuration +- `github` - GitHub-specific files +- `core` - Core library changes +- `docs` - Documentation changes +- `testing` - Test infrastructure +- `tests` - Test files + +### Scope Rules (CRITICAL) + +โŒ **DO NOT** use: +- Class names as scopes (e.g., `test(DefaultLambdaCancellationFactory)`) +- Method names as scopes (e.g., `fix(CreateHandler)`) +- Arbitrary text as scopes (e.g., `feat(new-thing)`) +- File names as scopes (e.g., `fix(Program.cs)`) + +โœ… **DO** use: +- One of the predefined scopes above (e.g., `test(testing)`) +- No scope at all if none fit (e.g., `test: add failing test`) + +### Title Examples + +**Valid:** +- `feat(host): add new Lambda handler support` +- `fix(abstractions): resolve dependency issue` +- `test(testing): add intentionally failing test` +- `docs: update README with examples` โ† no scope is fine +- `refactor: improve code organization` โ† no scope is fine +- `chore(deps): update NuGet packages` +- `ci: add build caching` + +**Invalid (will fail CI):** +- `test(DefaultLambdaCancellationFactory): add test` โ† class name not allowed +- `fix(SomeMethod): fix bug` โ† method name not allowed +- `feat(cool-feature): add feature` โ† arbitrary scope not allowed +- `Add new feature` โ† missing type +- `feat(core) add handler` โ† missing colon +- `FEAT(core): add handler` โ† type must be lowercase + +### Handling Type/Scope Overlap + +When a type and scope have the same name (e.g., `docs`, `ci`): +- `docs: update README` โ† Use when it's ONLY documentation changes +- `feat(docs): add documentation generator` โ† Use when it's a feature that affects docs +- `ci: update GitHub Actions workflow` โ† Use when it's ONLY CI changes +- `fix(ci): correct build script path` โ† Use when fixing something in the CI scope + +--- + +## Additional Template Sections (for complex PRs) + +For complex PRs with many changes, add these optional sections: + +```markdown +## ๐Ÿ”„ Changes + +- Change 1 +- Change 2 +- Change 3 + +--- + +## ๐Ÿง‘โ€๐Ÿ’ป Testing + +Describe how the changes were tested, specific test cases run, or manual testing performed. +``` + +Add these sections AFTER the Summary but BEFORE the Checklist when appropriate. + +--- + +## Title Validation Process + +Before creating the PR, validate the title: + +1. **Check format**: Must match `(): ` or `: ` +2. **Validate type**: Must be one of: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci` +3. **Validate scope** (if present): Must be one of the predefined scopes listed above +4. **Check description**: Must be present and not empty + +If validation fails, explain the error and ask for a corrected title. + +--- + +## Tips + +- **Auto-suggest titles**: If the most recent commit message follows conventional format, use it automatically +- **Infer scope**: Based on which files were changed, suggest an appropriate scope +- **Draft PRs**: Add `--draft` flag if the user mentions the PR is work-in-progress +- **Reviewers**: Add `--reviewer ` if the user specifies reviewers +- **Labels**: Add `--label