ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad-core/tasks/create-comprehensive-pr.md

7.5 KiB
Raw Blame History

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:

# 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

# 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

## 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

  1. Retrieve the resource: 
    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

-- 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