docs: add Epic & Sub-Issue core workflow documentation #69
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds comprehensive workflow guide and quick reference for managing multi-PR features using GitHub's native Epic & Sub-Issue pattern. Problem Solved: - Multi-PR features (like Issue 50) lose GitHub Projects automation - Status tracking breaks when parent issue has multiple PRs - No granular progress visibility for large features Solution: - Epic template for parent feature tracking - Sub-Issue template for individual tasks - Uses GitHub tasklists for native automation - Each sub-issue = 1 PR for clean tracking This PR includes: - EPIC_WORKFLOW.md: Complete step-by-step workflow guide - EPIC_IMPLEMENTATION_SUMMARY.md: Quick reference guide Related: - Organization templates: SecPal/.github PR #157 - Case study: Follow-up PR (ISSUE50_RETROSPECTIVE.md) - DEVELOPMENT.md integration: Follow-up PR See Also: EPIC_WORKFLOW.md for complete usage guide
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR introduces comprehensive documentation for managing large, multi-PR features using GitHub's native sub-issue and tasklist features. The documentation addresses problems encountered with Issue #50, which spanned 7 PRs and suffered from premature issue closure and inconsistent project board tracking.
Key changes:
- Establishes a Sub-Issue Pattern workflow where epics remain open until all sub-issues are complete
- Provides detailed guidance on creating epics, sub-issues, and linking PRs correctly
- Documents the Issue #50 experience as a case study for the new workflow
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/EPIC_WORKFLOW.md | Complete workflow documentation with step-by-step instructions, best practices, FAQ, and real-world examples for implementing the epic/sub-issue pattern |
| docs/EPIC_IMPLEMENTATION_SUMMARY.md | Quick reference guide summarizing the problem, solution, benefits, and implementation details of the epic workflow |
kevalyq
added a commit
that referenced
this pull request
Nov 2, 2025
Adds detailed case study documenting Issue 50 as a real-world example of multi-PR epic challenges and how the new Epic & Sub-Issue workflow would have improved the process. Learning Points: - Issue 50 had 7 main PRs split across 6 sub-features - GitHub Projects automation broke (premature closure, status inconsistency) - Sub-Issue pattern would provide granular tracking per PR - Each sub-issue maintains independent status automation This PR includes: - ISSUE50_RETROSPECTIVE.md: Complete timeline, problems, ideal structure Related: - Core workflow: SecPal/api #69 - Organization templates: SecPal/.github #157 - DEVELOPMENT.md integration: Follow-up PR See Also: ISSUE50_RETROSPECTIVE.md for detailed analysis
kevalyq
added a commit
that referenced
this pull request
Nov 2, 2025
Adds 'Working with Epics & Multi-PR Features' section to DEVELOPMENT.md to provide quick access to the Epic & Sub-Issue workflow. Integration Benefits: - Developers discover workflow during onboarding - Quick start guide with practical examples - Links to comprehensive documentation - Benefits breakdown for decision-making This PR includes: - DEVELOPMENT.md: New 'Working with Epics' section with quick start, benefits summary, template locations, and documentation links Related: - Core workflow: SecPal/api #69 - Case study: SecPal/api #70 - Organization templates: SecPal/.github #157 See Also: DEVELOPMENT.md 'Working with Epics' section
6 tasks
kevalyq
added a commit
that referenced
this pull request
Nov 2, 2025
Adds detailed case study documenting Issue 50 as a real-world example of multi-PR epic challenges and how the new Epic & Sub-Issue workflow would have improved the process. Learning Points: - Issue 50 had 7 main PRs split across 6 sub-features - GitHub Projects automation broke (premature closure, status inconsistency) - Sub-Issue pattern would provide granular tracking per PR - Each sub-issue maintains independent status automation This PR includes: - ISSUE50_RETROSPECTIVE.md: Complete timeline, problems, ideal structure Related: - Core workflow: SecPal/api #69 - Organization templates: SecPal/.github #157 - DEVELOPMENT.md integration: Follow-up PR See Also: ISSUE50_RETROSPECTIVE.md for detailed analysis
kevalyq
added a commit
that referenced
this pull request
Nov 2, 2025
Adds 'Working with Epics & Multi-PR Features' section to DEVELOPMENT.md to provide quick access to the Epic & Sub-Issue workflow. Integration Benefits: - Developers discover workflow during onboarding - Quick start guide with practical examples - Links to comprehensive documentation - Benefits breakdown for decision-making This PR includes: - DEVELOPMENT.md: New 'Working with Epics' section with quick start, benefits summary, template locations, and documentation links Related: - Core workflow: SecPal/api #69 - Case study: SecPal/api #70 - Organization templates: SecPal/.github #157 See Also: DEVELOPMENT.md 'Working with Epics' section
28 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
Adds comprehensive workflow guide and quick reference for managing multi-PR features using GitHub's native Epic & Sub-Issue pattern.
Problem Solved
Solution
This PR Includes
EPIC_WORKFLOW.md: Complete step-by-step workflow guide with examplesEPIC_IMPLEMENTATION_SUMMARY.md: Quick reference guideRelated PRs
Testing
See
EPIC_WORKFLOW.mdfor complete usage guide.