--- 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 ..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 ..HEAD --format="%h %ad %s" --date=short` to understand the development timeline. **1.2. File System Impact Analysis:** - **Changed Files Overview:** Run `git diff ..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 ## Work Streams ### 🚀 [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 ### 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 ### 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 ### Before [Screenshots/GIFs of old behavior] ### After [Screenshots/GIFs of new behavior] ## Review Focus Areas - [ ] **Code Quality:** [Specific areas to focus on] - [ ] **Security:** [Security considerations] - [ ] **Performance:** [Performance impacts] - [ ] **Compatibility:** [Breaking changes or compatibility concerns] ## Deployment Notes - Environment variables: - Configuration changes: - Database migrations: - Rollback procedures: ## Related Issues ## 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.