# Prompt: Write PR Description

Use this prompt to generate comprehensive PR descriptions.

---

## Prompt Template

```
I need to write a PR description for the following changes:

**PR Title:**
[Your semantic PR title, e.g., "feat: add user authentication"]

**Changes Made:**
[List the specific changes in bullet points]
- Change 1
- Change 2
- Change 3

**Motivation:**
[Why were these changes necessary? What problem do they solve?]

**Technical Approach:**
[For complex changes, explain the approach taken]
[Mention any design decisions or alternatives considered]

**Related Issues:**
[List issue numbers this PR addresses]
- Fixes #123
- Relates to #456

**Breaking Changes:**
[Yes/No - if yes, describe what breaks and migration path]

**Testing Performed:**
[List test commands run and results]
[Describe manual testing if applicable]

**Documentation Updates:**
[List what documentation was updated]
- [ ] README.md - Added X section
- [ ] docs/api.md - Documented Y endpoint
- [ ] Docstrings - Added to all new functions
- [ ] Comments - Explained complex logic in Z

**Target Audience:** [Reviewers / Team members]

Please generate a comprehensive PR description following the repository's
PR template format.
```

---

## Example Usage

**Example 1: New Feature**

```
I need to write a PR description for the following changes:

**PR Title:**
feat: add JWT authentication to API

**Changes Made:**
- Implemented JWTAuth class with login, logout, refresh methods
- Added /auth/login, /auth/logout, /auth/refresh endpoints
- Created authentication middleware for protected routes
- Updated API to require authentication on protected endpoints
- Added comprehensive test suite for auth flows

**Motivation:**
Users needed secure access to protected resources. Previous system had
no authentication, allowing anyone to access all data. This creates
security vulnerability and prevents implementing user-specific features.

JWT provides stateless authentication without server-side sessions,
improving scalability.

**Technical Approach:**
- Use pyjwt library for token generation/validation
- Access tokens expire after 1 hour
- Refresh tokens valid for 7 days
- Passwords hashed with bcrypt (12 rounds)
- Middleware validates token on each protected request
- Rate limiting on login endpoint (5 attempts/minute)

Considered session-based auth but chose JWT for:
- Stateless operation (no shared session store needed)
- Better scalability across multiple servers
- Standard approach with good library support

**Related Issues:**
- Fixes #123 (Add authentication)
- Fixes #124 (Secure API endpoints)
- Relates to #125 (Will enable role-based access control)

**Breaking Changes:**
Yes - Protected endpoints now require authentication header.

Migration: Clients must authenticate and include token in requests:
```python
# Before (no auth required)
response = requests.get("https://api.example.com/data")

# After (auth required)
token = authenticate(username, password)
response = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {token}"}
)
```

**Testing Performed:**
- pytest tests/ -v ✅ (all 127 tests pass, added 23 new tests)
- pytest tests/ --cov=src ✅ (91% coverage, up from 85%)

Manual testing:
- Login with valid credentials → Success
- Login with invalid credentials → 401 error
- Access protected endpoint without token → 401 error
- Access protected endpoint with valid token → Success
- Token refresh flow → Success
- Rate limiting → Blocks after 5 failed attempts

**Documentation Updates:**
- [x] README.md - Added "Authentication" section with setup guide
- [x] docs/api.md - Documented auth endpoints with examples
- [x] docs/architecture.md - Explained JWT design decisions
- [x] All new functions have Google-style docstrings
- [x] Added comments explaining token validation logic

**Target Audience:** Team members reviewing the PR

Please generate a comprehensive PR description following the repository's
PR template format.
```

**Example 2: Bug Fix**

```
I need to write a PR description for the following changes:

**PR Title:**
fix: resolve memory leak in DataProcessor

**Changes Made:**
- Added mutex lock to DataProcessor.process_batch() to prevent race conditions
- Fixed circular reference by using weak references
- Added explicit cleanup in __del__ method
- Updated docstring to document thread-safety guarantees
- Added integration test for concurrent processing

**Motivation:**
In production, multiple workers process batches concurrently. Without proper
synchronization, two workers could modify same batch state simultaneously,
causing data corruption. Manifested as ~1% of batches having invalid checksums.

Additionally, circular references between DataProcessor and internal components
caused Python garbage collector to never free memory, leading to memory leaks
in long-running processes.

**Technical Approach:**
- Acquire batch_lock before reading/modifying batch state
- Use weakref for internal component references to break circular refs
- Ensure lock released in finally block
- Lock is per-batch so different batches can process concurrently

Root cause: When multi-worker support added in v2.0, we didn't add proper
synchronization. Circular refs were introduced when caching was added.

**Related Issues:**
- Fixes #456 (Data corruption in concurrent processing)
- Fixes #457 (Memory leak in long-running processes)

**Breaking Changes:**
No - Same API, just fixed behavior.

**Testing Performed:**
- pytest tests/ -v ✅
- pytest tests/test_concurrent_processing.py -v ✅ (new test, 100 iterations)

Manual stress test:
- 50 concurrent workers for 1 hour
- Processed 10,000 batches
- 0 checksum failures (before fix: ~100 failures)
- Memory usage stable (before: grew continuously)

**Documentation Updates:**
- [x] Updated DataProcessor docstring to document thread-safety
- [x] Added comments explaining locking strategy
- [x] No README/API changes needed (internal fix)

**Target Audience:** Team members

Please generate a PR description.
```

---

## Tips for Using This Prompt

### Provide Complete Information
- List all changes, not just major ones
- Explain both "what" and "why"
- Include test results
- Note all documentation updates

### Be Specific About Impact
- Who is affected by changes?
- What breaks (if anything)?
- How should users migrate?

### Include Technical Details
- Design decisions made
- Alternatives considered
- Performance implications
- Security considerations

### Show Your Work
- Test commands run
- Coverage numbers
- Manual testing performed
- Edge cases verified

---

## What to Expect

The AI should generate:
- ✅ Well-structured PR description
- ✅ Clear "What Changed" section
- ✅ Compelling "Why" explanation
- ✅ Technical details in "How" section
- ✅ Complete testing summary
- ✅ Proper documentation checklist
- ✅ Professional, clear writing

Review and edit:
- Verify accuracy of generated content
- Add any missing details
- Ensure tone matches your team culture
- Check that examples work

---

## PR Description Quality Checklist

Good PR description should have:
- [ ] Clear summary of changes
- [ ] Explanation of motivation ("why")
- [ ] Technical approach for complex changes
- [ ] All related issues linked
- [ ] Breaking changes documented
- [ ] Migration guide (if breaking)
- [ ] Test results included
- [ ] Documentation checklist complete
- [ ] Appropriate level of detail

---

## Related Prompts

- [PR Title Guidelines](../../.claude/knowledge/git/pr-titles-and-descriptions.md)
- [Update README](update-readme.md)
- [Update API Documentation](update-api-docs.md)

---

**Status**: Prompt template for PR descriptions. Updated: 2026-01-07
