272 lines
9.7 KiB
Markdown
272 lines
9.7 KiB
Markdown
---
|
|
description: A Pull Request documentation workflow
|
|
---
|
|
|
|
This workflow guides the creation of a high-quality, comprehensive Pull Request description. A great PR description is the fastest way to get your changes reviewed and merged.
|
|
|
|
**1. Comprehensive Scope Analysis (MANDATORY - Prevent tunnel vision):**
|
|
|
|
**1.1. Branch and Commit Analysis:**
|
|
|
|
- **Determine the Base Branch:** Identify the target branch for the merge (e.g., `main`, `develop`).
|
|
- **Full Commit Analysis:** Run `git log <base_branch>..HEAD --stat --oneline` to get both summary and detailed changes for all commits in this PR.
|
|
- **Commit Categorization:** Group commits by type (feat, fix, docs, refactor, test, chore) to understand the full scope.
|
|
- **Time Range Assessment:** Run `git log <base_branch>..HEAD --format="%h %ad %s" --date=short` to understand the development timeline.
|
|
|
|
**1.2. File System Impact Analysis:**
|
|
|
|
- **Changed Files Overview:** Run `git diff <base_branch>..HEAD --name-status` to see all modified, added, and deleted files.
|
|
- **Functional Area Mapping:** Group changed files by functional area:
|
|
- **API Changes:** `src/groovy/umig/api/`, `src/groovy/umig/repository/`
|
|
- **UI Changes:** `src/groovy/umig/web/js/`, `src/groovy/umig/web/css/`, `src/groovy/umig/macros/`
|
|
- **Documentation:** `docs/`, `README.md`, `CHANGELOG.md`, `*.md` files
|
|
- **Tests:** `src/groovy/umig/tests/`, `local-dev-setup/__tests__/`
|
|
- **Configuration:** `local-dev-setup/liquibase/`, `*.json`, `*.yml`, `*.properties`
|
|
- **Database:** Migration files, schema changes
|
|
- **Cross-Functional Impact:** Identify changes that span multiple functional areas.
|
|
|
|
**1.3. Work Stream Identification:**
|
|
|
|
- **Primary Work Streams:** Based on commits and file changes, identify distinct work streams (e.g., "API implementation", "UI refactoring", "documentation updates").
|
|
- **Secondary Work Streams:** Identify supporting work (e.g., "schema fixes", "test updates", "configuration changes").
|
|
- **Parallel vs Sequential:** Determine which work streams were done in parallel vs. sequence.
|
|
- **Dependencies:** Note how different work streams depend on each other.
|
|
|
|
**2. Multi-Stream Narrative Synthesis (MANDATORY - Address tunnel vision):**
|
|
|
|
A PR is a story that may have multiple parallel themes. You need to explain the "why," the "what," and the "how" for each work stream.
|
|
|
|
**2.1. Context and Motivation Analysis:**
|
|
|
|
- **Development Context:** Review recent dev journal entries, session context, and any associated tickets (e.g., Jira, GitHub Issues).
|
|
- **Problem Statement:** For each work stream, clearly articulate:
|
|
- What problem was being solved or feature being added?
|
|
- What was the state of the application before this change?
|
|
- What will it be after?
|
|
- **Business Impact:** Explain the user-facing or technical benefits of the changes.
|
|
- **Scope Evolution:** If the PR scope expanded during development, explain how and why.
|
|
|
|
**2.2. Technical Implementation Analysis:**
|
|
|
|
- **Architecture Overview:** Describe the overall technical approach and any significant architectural decisions.
|
|
- **Work Stream Details:** For each work stream identified in step 1:
|
|
- **API Changes:** New endpoints, schema modifications, repository patterns
|
|
- **UI Changes:** Component modifications, styling updates, user experience improvements
|
|
- **Documentation:** What docs were updated and why
|
|
- **Database Changes:** Schema migrations, data model updates
|
|
- **Configuration:** Environment or build configuration changes
|
|
- **Tests:** New test coverage, test framework updates
|
|
- **Technical Decisions:** Explain why you chose specific solutions over alternatives.
|
|
- **Patterns and Standards:** Note adherence to or establishment of new project patterns.
|
|
|
|
**2.3. Integration and Dependencies:**
|
|
|
|
- **Cross-Stream Integration:** How different work streams work together.
|
|
- **Breaking Changes:** Any breaking changes and migration path.
|
|
- **Backward Compatibility:** How existing functionality is preserved.
|
|
- **Future Implications:** What this change enables for future development.
|
|
|
|
**3. Comprehensive Review Instructions (MANDATORY - Cover all work streams):**
|
|
|
|
Make it easy for others to review your work across all functional areas.
|
|
|
|
**3.1. Testing Instructions by Work Stream:**
|
|
|
|
- **API Testing:** For each new or modified API endpoint:
|
|
- Provide curl commands or Postman collection references
|
|
- Include expected request/response examples
|
|
- Note any authentication or setup requirements
|
|
- Identify edge cases and error scenarios to test
|
|
- **UI Testing:** For each UI change:
|
|
- Provide step-by-step user interaction flows
|
|
- Include screenshots or GIFs showing before/after states
|
|
- Identify specific user scenarios to test
|
|
- Note any browser-specific considerations
|
|
- **Database Testing:** For schema changes:
|
|
- Provide migration verification steps
|
|
- Include data verification queries
|
|
- Note any rollback procedures
|
|
- **Configuration Testing:** For environment changes:
|
|
- Provide setup or configuration verification steps
|
|
- Include any new environment variables or settings
|
|
- Note any deployment considerations
|
|
|
|
**3.2. Review Focus Areas:**
|
|
|
|
- **Code Quality:** Highlight areas that need particular attention (complex logic, new patterns, potential performance impacts).
|
|
- **Security:** Note any security considerations or authentication changes.
|
|
- **Performance:** Identify any performance-critical changes or optimizations.
|
|
- **Compatibility:** Note any backward compatibility concerns or breaking changes.
|
|
|
|
**3.3. Verification Checklist:**
|
|
|
|
- **Functional Verification:** What specific functionality should reviewers verify works correctly?
|
|
- **Integration Testing:** How should reviewers verify that different components work together?
|
|
- **Edge Case Testing:** What edge cases or error conditions should be tested?
|
|
- **Documentation Review:** What documentation should be reviewed for accuracy and completeness?
|
|
|
|
**4. Enhanced PR Description Template (MANDATORY - Multi-stream aware):**
|
|
|
|
Use a structured template that accommodates multiple work streams and comprehensive coverage.
|
|
|
|
**4.1. Title Construction:**
|
|
|
|
- **Primary Work Stream:** Use the most significant work stream for the title following Conventional Commits standard.
|
|
- **Multi-Stream Indicator:** If multiple significant work streams exist, use a broader scope (e.g., `feat(admin): complete user management system with API and UI`).
|
|
|
|
**4.2. Enhanced Body Template:**
|
|
|
|
```markdown
|
|
## Summary
|
|
|
|
<!-- Brief overview of the PR's purpose and scope. What problem does this solve? -->
|
|
|
|
## Work Streams
|
|
|
|
<!-- List all major work streams in this PR -->
|
|
|
|
### 🚀 [Primary Work Stream Name]
|
|
|
|
- Brief description of changes
|
|
- Key files modified
|
|
- Impact on users/system
|
|
|
|
### 🔧 [Secondary Work Stream Name]
|
|
|
|
- Brief description of changes
|
|
- Key files modified
|
|
- Impact on users/system
|
|
|
|
## Technical Changes
|
|
|
|
<!-- Detailed breakdown by functional area -->
|
|
|
|
### API Changes
|
|
|
|
- New endpoints:
|
|
- Modified endpoints:
|
|
- Schema changes:
|
|
- Repository updates:
|
|
|
|
### UI Changes
|
|
|
|
- New components:
|
|
- Modified components:
|
|
- Styling updates:
|
|
- User experience improvements:
|
|
|
|
### Database Changes
|
|
|
|
- Schema migrations:
|
|
- Data model updates:
|
|
- Migration scripts:
|
|
|
|
### Documentation Updates
|
|
|
|
- API documentation:
|
|
- User documentation:
|
|
- Developer documentation:
|
|
- Configuration documentation:
|
|
|
|
## Testing Instructions
|
|
|
|
<!-- Work stream specific testing -->
|
|
|
|
### API Testing
|
|
|
|
1. [Specific API test steps]
|
|
2. [Expected outcomes]
|
|
3. [Edge cases to verify]
|
|
|
|
### UI Testing
|
|
|
|
1. [Specific UI test steps]
|
|
2. [User flows to verify]
|
|
3. [Browser compatibility checks]
|
|
|
|
### Database Testing
|
|
|
|
1. [Migration verification]
|
|
2. [Data integrity checks]
|
|
3. [Rollback verification]
|
|
|
|
## Screenshots / Recordings
|
|
|
|
<!-- Visual evidence of changes -->
|
|
|
|
### Before
|
|
|
|
[Screenshots/GIFs of old behavior]
|
|
|
|
### After
|
|
|
|
[Screenshots/GIFs of new behavior]
|
|
|
|
## Review Focus Areas
|
|
|
|
<!-- Areas needing particular attention -->
|
|
|
|
- [ ] **Code Quality:** [Specific areas to focus on]
|
|
- [ ] **Security:** [Security considerations]
|
|
- [ ] **Performance:** [Performance impacts]
|
|
- [ ] **Compatibility:** [Breaking changes or compatibility concerns]
|
|
|
|
## Deployment Notes
|
|
|
|
<!-- Any special deployment considerations -->
|
|
|
|
- Environment variables:
|
|
- Configuration changes:
|
|
- Database migrations:
|
|
- Rollback procedures:
|
|
|
|
## Related Issues
|
|
|
|
<!-- Link to any related issues, e.g., "Closes #123" -->
|
|
|
|
## Checklist
|
|
|
|
- [ ] All work streams are documented above
|
|
- [ ] Testing instructions cover all functional areas
|
|
- [ ] Documentation is updated for all changes
|
|
- [ ] Database migrations are tested
|
|
- [ ] API changes are documented
|
|
- [ ] UI changes are demonstrated with screenshots
|
|
- [ ] Code follows project style guidelines
|
|
- [ ] All tests pass
|
|
- [ ] Breaking changes are documented
|
|
- [ ] Deployment considerations are noted
|
|
```
|
|
|
|
**5. Anti-Tunnel Vision Verification (MANDATORY - Use before finalizing):**
|
|
|
|
Before presenting the PR description, verify you have addressed ALL of the following:
|
|
|
|
**Content Coverage:**
|
|
|
|
- [ ] All commits in the PR are explained
|
|
- [ ] All modified files are accounted for
|
|
- [ ] All functional areas touched are documented
|
|
- [ ] All work streams are identified and described
|
|
- [ ] Cross-functional impacts are noted
|
|
|
|
**Technical Completeness:**
|
|
|
|
- [ ] API changes include endpoint details and examples
|
|
- [ ] UI changes include visual evidence and user flows
|
|
- [ ] Database changes include migration details
|
|
- [ ] Configuration changes include deployment notes
|
|
- [ ] Documentation updates are comprehensive
|
|
|
|
**Review Readiness:**
|
|
|
|
- [ ] Testing instructions are clear and complete
|
|
- [ ] Review focus areas are identified
|
|
- [ ] Deployment considerations are documented
|
|
- [ ] Rollback procedures are noted (if applicable)
|
|
- [ ] Breaking changes are clearly highlighted
|
|
|
|
**6. Final Review:**
|
|
|
|
- Present the generated PR title and body to the user for final review and approval before they create the pull request on their Git platform.
|