318 lines
7.8 KiB
Markdown
318 lines
7.8 KiB
Markdown
# Create Comprehensive Pull Request
|
|
|
|
This task guides the creation of a high-quality, comprehensive Pull Request description that helps reviewers understand all changes and speeds up the review process.
|
|
|
|
## Purpose
|
|
|
|
Create PR descriptions that:
|
|
- Document ALL work streams comprehensively
|
|
- Provide clear testing instructions
|
|
- Help reviewers focus on important areas
|
|
- Prevent tunnel vision through systematic analysis
|
|
- Make code review efficient and thorough
|
|
|
|
## Process
|
|
|
|
### 1. Comprehensive Scope Analysis (MANDATORY)
|
|
|
|
#### 1.1 Branch and Commit Analysis
|
|
|
|
Determine base branch and analyze all changes:
|
|
```bash
|
|
# Identify target branch (e.g., main, develop)
|
|
git branch --show-current
|
|
|
|
# Full commit analysis with details
|
|
git log <base_branch>..HEAD --stat --oneline
|
|
|
|
# Timeline of development
|
|
git log <base_branch>..HEAD --format="%h %ad %s" --date=short
|
|
```
|
|
|
|
Group commits by type:
|
|
- Features (feat)
|
|
- Bug fixes (fix)
|
|
- Documentation (docs)
|
|
- Refactoring (refactor)
|
|
- Tests (test)
|
|
- Maintenance (chore)
|
|
|
|
#### 1.2 File System Impact Analysis
|
|
|
|
```bash
|
|
# All file changes overview
|
|
git diff <base_branch>..HEAD --name-status
|
|
|
|
# Detailed diff statistics
|
|
git diff <base_branch>..HEAD --stat
|
|
```
|
|
|
|
Map changes to functional areas:
|
|
- **API/Backend**: Services, endpoints, business logic
|
|
- **UI/Frontend**: Components, styles, user interfaces
|
|
- **Documentation**: All *.md files, API docs, guides
|
|
- **Tests**: Unit tests, integration tests, E2E tests
|
|
- **Configuration**: Environment configs, build settings
|
|
- **Database**: Migrations, schema changes
|
|
- **Infrastructure**: CI/CD, deployment configs
|
|
|
|
#### 1.3 Work Stream Identification
|
|
|
|
Identify distinct work streams:
|
|
- **Primary**: Main feature or fix
|
|
- **Secondary**: Supporting changes
|
|
- **Cross-cutting**: Changes affecting multiple areas
|
|
- **Dependencies**: How streams relate to each other
|
|
|
|
### 2. Multi-Stream Narrative Synthesis
|
|
|
|
#### 2.1 Context and Motivation
|
|
|
|
For each work stream, establish:
|
|
- Problem being solved
|
|
- Current state vs. desired state
|
|
- Business/technical benefits
|
|
- Related issues or tickets
|
|
|
|
#### 2.2 Technical Implementation
|
|
|
|
Document for each work stream:
|
|
- Overall approach
|
|
- Architectural decisions
|
|
- Design patterns used
|
|
- Alternative solutions considered
|
|
- Technical trade-offs made
|
|
|
|
#### 2.3 Integration Points
|
|
|
|
Identify:
|
|
- How work streams integrate
|
|
- Breaking changes (if any)
|
|
- Backward compatibility measures
|
|
- Future extensibility
|
|
|
|
### 3. Review Instructions (Per Work Stream)
|
|
|
|
#### 3.1 Testing Instructions
|
|
|
|
**API Testing**:
|
|
- Endpoint URLs and methods
|
|
- Sample requests (curl/Postman)
|
|
- Expected responses
|
|
- Error scenarios
|
|
- Authentication requirements
|
|
|
|
**UI Testing**:
|
|
- User flows step-by-step
|
|
- Screenshots/GIFs (before/after)
|
|
- Browser compatibility notes
|
|
- Responsive design checks
|
|
- Accessibility verification
|
|
|
|
**Database Testing**:
|
|
- Migration commands
|
|
- Verification queries
|
|
- Rollback procedures
|
|
- Data integrity checks
|
|
|
|
**Configuration Testing**:
|
|
- Environment setup steps
|
|
- New variables/settings
|
|
- Deployment considerations
|
|
|
|
#### 3.2 Review Focus Areas
|
|
|
|
Highlight:
|
|
- Complex logic needing attention
|
|
- Security-sensitive changes
|
|
- Performance-critical code
|
|
- Breaking changes
|
|
- New patterns introduced
|
|
|
|
### 4. PR Description Template
|
|
|
|
```markdown
|
|
## Summary
|
|
|
|
[2-3 sentences explaining the PR's purpose and main achievement]
|
|
|
|
## Context
|
|
|
|
**Problem**: [What issue does this solve?]
|
|
**Solution**: [High-level approach taken]
|
|
**Impact**: [Who benefits and how?]
|
|
|
|
## Work Streams
|
|
|
|
### 🎯 Primary: [Main Feature/Fix Name]
|
|
- **What**: [Brief description]
|
|
- **Files**: [Key files changed]
|
|
- **Impact**: [User/system impact]
|
|
|
|
### 🔧 Secondary: [Supporting Changes]
|
|
- **What**: [Brief description]
|
|
- **Files**: [Key files changed]
|
|
- **Reason**: [Why needed]
|
|
|
|
## Technical Changes
|
|
|
|
### API Changes
|
|
- **New Endpoints**:
|
|
- `POST /api/v1/resource` - Creates new resource
|
|
- `GET /api/v1/resource/:id` - Retrieves resource
|
|
- **Modified Endpoints**:
|
|
- `PUT /api/v1/existing` - Added field validation
|
|
- **Breaking Changes**: None
|
|
|
|
### UI Changes
|
|
- **New Components**:
|
|
- `ResourceManager` - Main management interface
|
|
- `ResourceForm` - Creation/edit form
|
|
- **Updated Components**:
|
|
- `Dashboard` - Added resource widget
|
|
- **User Experience**:
|
|
- Simplified workflow for resource creation
|
|
- Added inline validation feedback
|
|
|
|
### Database Changes
|
|
- **Migrations**:
|
|
- `001_add_resources_table.sql` - New resource storage
|
|
- `002_add_resource_indexes.sql` - Performance indexes
|
|
- **Model Changes**:
|
|
- Added Resource entity with relations
|
|
|
|
### Tests Added
|
|
- **Unit Tests**: 15 new tests for resource service
|
|
- **Integration Tests**: API endpoint coverage
|
|
- **E2E Tests**: Full user workflow validation
|
|
|
|
## Testing Instructions
|
|
|
|
### API Testing
|
|
|
|
1. Create a new resource:
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/resource \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name": "Test Resource", "type": "example"}'
|
|
```
|
|
Expected: 201 Created with resource ID
|
|
|
|
2. Retrieve the resource:
|
|
```bash
|
|
curl http://localhost:8080/api/v1/resource/{id}
|
|
```
|
|
Expected: 200 OK with resource data
|
|
|
|
### UI Testing
|
|
|
|
1. Navigate to Dashboard
|
|
2. Click "Add Resource" button
|
|
3. Fill form with test data
|
|
4. Submit and verify success message
|
|
5. Check resource appears in list
|
|
|
|
### Database Verification
|
|
|
|
```sql
|
|
-- Verify migration success
|
|
SELECT * FROM schema_version ORDER BY installed_on DESC LIMIT 2;
|
|
|
|
-- Check data integrity
|
|
SELECT COUNT(*) FROM resources;
|
|
```
|
|
|
|
## Screenshots
|
|
|
|
### Before
|
|
[Dashboard without resource management]
|
|
|
|
### After
|
|
[Dashboard with new resource section]
|
|
[Resource creation form]
|
|
[Success state]
|
|
|
|
## Review Checklist
|
|
|
|
### For Reviewers
|
|
- [ ] API contracts match documentation
|
|
- [ ] Error handling is comprehensive
|
|
- [ ] UI follows design system
|
|
- [ ] Tests provide adequate coverage
|
|
- [ ] Performance impact is acceptable
|
|
- [ ] Security best practices followed
|
|
|
|
### Pre-Merge Checklist
|
|
- [ ] All CI checks passing
|
|
- [ ] Documentation updated
|
|
- [ ] CHANGELOG entry added
|
|
- [ ] No console.log or debug code
|
|
- [ ] Breaking changes communicated
|
|
|
|
## Deployment Notes
|
|
|
|
- **Database**: Run migrations before deploying code
|
|
- **Config**: Add `RESOURCE_FEATURE_FLAG=true` to enable
|
|
- **Rollback**: Feature flag can disable without code rollback
|
|
|
|
## Related Issues
|
|
|
|
Closes #123 - Add resource management
|
|
Relates to #100 - Overall admin improvements
|
|
|
|
---
|
|
|
|
**Questions for Reviewers**:
|
|
1. Should we add pagination to the resource list immediately?
|
|
2. Any concerns about the permission model?
|
|
```
|
|
|
|
### 5. Anti-Tunnel Vision Checklist
|
|
|
|
Verify before finalizing:
|
|
|
|
**Content Coverage**:
|
|
- [ ] All commits explained
|
|
- [ ] All files accounted for
|
|
- [ ] All work streams documented
|
|
- [ ] Cross-functional impacts noted
|
|
|
|
**Technical Completeness**:
|
|
- [ ] API changes detailed with examples
|
|
- [ ] UI changes shown visually
|
|
- [ ] Database changes include migrations
|
|
- [ ] Config changes documented
|
|
- [ ] Tests described
|
|
|
|
**Review Readiness**:
|
|
- [ ] Testing steps are reproducible
|
|
- [ ] Focus areas highlighted
|
|
- [ ] Deployment notes included
|
|
- [ ] Breaking changes clear
|
|
- [ ] Questions for reviewers listed
|
|
|
|
### 6. Execution
|
|
|
|
1. Generate PR description using template
|
|
2. Include all evidence gathered
|
|
3. Add screenshots/recordings
|
|
4. Review completeness
|
|
5. Present to user for approval
|
|
6. User creates PR on platform
|
|
|
|
## Key Principles
|
|
|
|
- **Comprehensive Coverage**: Document all changes, not just primary
|
|
- **Reviewer Empathy**: Make review process efficient
|
|
- **Visual Evidence**: Screenshots/GIFs for UI changes
|
|
- **Reproducible Testing**: Clear, step-by-step instructions
|
|
- **Future Reference**: Context for why decisions were made
|
|
|
|
## Memory Bank Integration
|
|
|
|
After PR is merged:
|
|
- Major features: Update `progress.md` with completed features
|
|
- Architecture changes: Update `systemPatterns.md`
|
|
- Tech updates: Update `techContext.md`
|
|
- Breaking changes: Update relevant Memory Bank files
|
|
- Consider comprehensive `update-memory-bank` for significant PRs |