Create Pull Request with Release-Please Guidelines

This skill automates the process of committing changes, pushing to GitHub, and creating a Pull Request with a comprehensive description following Google release-please guidelines.

Conventional Commit Types

• feat: New feature (triggers minor version bump)
• fix: Bug fix (triggers patch version bump)
• feat! or fix!: Breaking change (triggers major version bump)
• chore: Maintenance tasks (no version bump)
• docs: Documentation changes (no version bump)
• refactor: Code refactoring (no version bump)
• test: Test changes (no version bump)
• perf: Performance improvements (triggers patch version bump)

Release-Please Guidelines

PR descriptions should include:

1. Clear title: Following conventional commits format
2. Summary: What changed and why
3. Breaking Changes: Clearly marked with BREAKING CHANGE: footer
4. Related Issues: Link to issues using Fixes or Closes keywords
5. Test Plan: How to verify the changes
6. Release Notes: User-facing description of changes

Instructions for Claude

When this skill is invoked:

1. Check git status and diff:

   git status
   git diff --staged
   git diff

2. Group changes into logical commits by analyzing:

   • By feature/functionality: Group files that implement the same feature together
   • By layer: Keep related files together (e.g., API handler + its test file)
   • By change type: Separate refactoring from new features from bug fixes
   • By scope: Group changes affecting the same module/package

   Common grouping patterns:

   • handler.go + handler_test.go → one commit
   • api.yaml + generated openapi/*.gen.go → one commit
   • Multiple files for same feature → one commit
   • Unrelated fixes → separate commits
   • Test additions → can be separate or with implementation
3. Determine commit type for each group:
   • New features → feat
   • Bug fixes → fix
   • Breaking changes → Add ! suffix or BREAKING CHANGE: footer
   • Other changes → chore, refactor, docs, test, etc.
4. Identify the scope for each commit (optional but recommended):
   • Examples: api, config, workflow, provider, auth, etc.
5. Check current branch:

   git branch --show-current

6. If on main/master, create a new feature branch:

   git checkout -b <type>/<scope>-<short-description>

   Examples: feat/api-appointment-slots, fix/auth-token-validation

7. Create commits for each logical group (repeat for each group):

   # Stage only files for this commit group
   git add <file1> <file2> ...
   
   # Create the commit
   git commit -m "<type>(<scope>): <description>
   
   <body with detailed explanation>
   
   BREAKING CHANGE: <description if applicable>
   
   Fixes #<issue-number> (if applicable)"

   Commit order: Order commits so that reading them oldest-first explains the change, usually setup, then implementation, then tests and docs. Tests may share a commit with the code they cover.

8. Push to remote:

   git push -u origin <branch-name>

9. Create PR with comprehensive description:

   gh pr create --title "<primary-change-title>" --body "$(cat <<'EOF'
   ## Summary
   <1-3 sentence summary of what changed and why>
   
   ## Commits
   - `<short-sha>` <commit title>
   
   ## Changes
   - <bullet point list of key changes>
   - <each change should be clear and specific>
   
   ## Breaking Changes
   <If applicable, list breaking changes with migration guide>
   <If not applicable, write "None">
   
   ## Test Plan
   - [ ] <How to test the changes>
   - [ ] <Include specific curl commands or test steps>
   - [ ] <Verify no regressions>
   
   ## Related Issues
   Fixes #<issue-number> (if applicable)
   Closes #<issue-number> (if applicable)
   
   ## Release Notes
   <User-facing description for changelog>
   <Written from user perspective>
   <Highlight value and impact>
   
   ## Screenshots/Logs
   <If applicable, include relevant screenshots or log outputs>
   
   ## Checklist
   - [ ] Tests pass locally (project test command)
   - [ ] Linting passes (project lint command)
   - [ ] Documentation updated (if needed)
   - [ ] Breaking changes documented
   - [ ] Conventional commit format followed
   EOF
   )"

   PR Title: Use the primary/most significant change as the PR title. If all commits are of equal importance, use a summary title that encompasses the changes.

10. Display PR URL and confirm successful creation

Important Notes

• Create multiple logical commits instead of one massive commit
• Each commit should be atomic: It should represent one logical change that could stand alone
• Always follow Conventional Commits format for commit messages
• Use imperative mood in commit descriptions (e.g., "add feature" not "added feature")
• Keep commit title under 72 characters
• Breaking changes must include BREAKING CHANGE: in commit footer or ! after type/scope
• PR title should reflect the primary change or summarize multiple changes
• Verify all services are properly tested before creating PR
• Link related issues using GitHub keywords (Fixes, Closes, Resolves)
• Commit order should tell a story: Reading commits chronologically should explain the progression of changes

Example: Multiple Commits for a Feature

Given changes to implement appointment slot filtering, create separate commits:

Commit 1 - API spec update:

docs(api): add provider_type parameter to slots endpoint

Update OpenAPI spec with new query parameter for filtering
appointment slots by provider type.

Commit 2 - Core implementation:

feat(api): add appointment slot filtering by provider

Implement endpoint to filter available appointment slots based on
provider type and location preferences. This improves user experience
by showing only relevant appointment options.

- Add provider filter to slots endpoint
- Implement timezone conversion for slot times

Fixes #123

Commit 3 - Tests:

test(api): add tests for appointment slot filtering

Add unit tests covering filter logic, timezone conversion,
and edge cases for the new provider filtering feature.

Example PR Description (Multiple Commits)

## Summary
Adds appointment slot filtering by provider type to improve user experience when booking appointments.

## Commits
- `a1b2c3d` docs(api): add provider_type parameter to slots endpoint
- `e4f5g6h` feat(api): add appointment slot filtering by provider
- `i7j8k9l` test(api): add tests for appointment slot filtering

## Changes
- Added `provider_type` query parameter to `/v1/appointments/slots` endpoint
- Implemented timezone conversion for accurate slot display across regions
- Updated OpenAPI spec with new filtering parameters
- Added unit tests for filter logic and edge cases

## Breaking Changes
None

## Test Plan
- [ ] Run the test suite to verify all tests pass
- [ ] Test filtering with curl:
  ```bash
  curl -X GET "http://localhost:8080/v1/appointments/slots?start_date=2025-11-01&end_date=2025-11-15&provider_type=primary_care" \
    -H "Authorization: Bearer valid-jwt"

• Verify timezone handling for different user locations
• Test backward compatibility (endpoint works without filter)

Related Issues

Fixes #123

Release Notes

Users can now filter appointment slots by provider type, making it easier to find appointments with their preferred healthcare provider.

Checklist

• Tests pass locally (project test command)
• Linting passes (project lint command)
• Documentation updated
• Conventional commit format followed

## When to Use Single vs Multiple Commits

**Use multiple commits when:**
- Changes span different concerns (API, tests, docs)
- Changes affect different modules/packages
- You have both bug fixes and new features
- Changes can be logically separated for easier review
- Implementation + tests can be split

**Use a single commit when:**
- All changes are tightly coupled and inseparable
- Very small change (few lines across 1-2 files)
- Single atomic change that makes no sense to split

## Usage

Invoke this skill with `/create-pr` and Claude will:
1. Analyze your uncommitted changes
2. Group changes into logical commit units
3. Create multiple commits in logical progression order
4. Push all commits to the feature branch
5. Generate a comprehensive PR with release-please compatible formatting
6. Open the PR on GitHub