|
| 1 | +# Incoming Integration Plans |
| 2 | + |
| 3 | +This directory contains evaluation folders for upstream commits that require detailed analysis before integration into Spec Kit Spark. |
| 4 | + |
| 5 | +## Purpose |
| 6 | + |
| 7 | +When syncing with upstream `github/spec-kit`, some commits: |
| 8 | +- Are good ideas but need adaptation for Spec Kit Spark |
| 9 | +- Require architectural discussion before integration |
| 10 | +- Need testing in isolation before merging |
| 11 | +- May conflict with Spark-specific enhancements |
| 12 | + |
| 13 | +Rather than cherry-picking immediately or deferring indefinitely, the **Plan** option creates a dedicated evaluation folder here. |
| 14 | + |
| 15 | +## Structure |
| 16 | + |
| 17 | +Each commit gets its own folder named by commit hash: |
| 18 | + |
| 19 | +``` |
| 20 | +incoming/ |
| 21 | +├── README.md (this file) |
| 22 | +└── <commit-hash>/ |
| 23 | + └── integration-plan.md |
| 24 | +``` |
| 25 | + |
| 26 | +## Integration Plan Template |
| 27 | + |
| 28 | +Each `integration-plan.md` includes: |
| 29 | + |
| 30 | +1. **Commit Metadata**: Full upstream commit details, author, dates, PR links |
| 31 | +2. **Files Changed**: Complete list of modified files with diff stats |
| 32 | +3. **Integration Analysis**: |
| 33 | + - What does this change do? |
| 34 | + - Relevance to Spec Kit Spark |
| 35 | + - Conflicts & dependencies |
| 36 | + - Adaptation strategy |
| 37 | + - Testing & validation plan |
| 38 | + - Impact assessment |
| 39 | +4. **Decision & Next Steps**: Approval, modification, rejection, or deferral |
| 40 | +5. **Full Diff**: Complete code changes for reference |
| 41 | + |
| 42 | +## Workflow |
| 43 | + |
| 44 | +### Creating Plans |
| 45 | + |
| 46 | +Use interactive sync mode: |
| 47 | +```powershell |
| 48 | +.\scripts\powershell\sync-upstream.ps1 -Mode interactive |
| 49 | +``` |
| 50 | + |
| 51 | +When prompted for a commit action: |
| 52 | +- **[A]** Apply - Cherry-pick immediately |
| 53 | +- **[S]** Skip - Ignore this commit |
| 54 | +- **[P]** Plan - Create integration evaluation folder ⬅️ |
| 55 | +- **[D]** Defer - Add to deferred list |
| 56 | +- **[V]** View - Show full diff |
| 57 | +- **[Q]** Quit |
| 58 | + |
| 59 | +### Evaluating Plans |
| 60 | + |
| 61 | +1. Open `incoming/<commit-hash>/integration-plan.md` |
| 62 | +2. Fill out the analysis sections |
| 63 | +3. Make your decision: Approve/Modify/Reject/Defer |
| 64 | +4. Add action items and timeline |
| 65 | +5. Execute when ready |
| 66 | + |
| 67 | +### After Integration |
| 68 | + |
| 69 | +Once a plan is executed: |
| 70 | +- Delete the commit's folder: `rm -r incoming/<commit-hash>` |
| 71 | +- Or keep for reference if helpful |
| 72 | +- Plans are gitignored automatically |
| 73 | + |
| 74 | +## Tips |
| 75 | + |
| 76 | +- **Fill out the checklist**: Use the checkboxes to track progress |
| 77 | +- **Document reasoning**: Future maintainers will thank you |
| 78 | +- **Test in isolation**: Create a test branch before applying |
| 79 | +- **Update FORK_DIVERGENCE.md**: Record integration decisions |
| 80 | +- **Share decisions**: Discuss complex integrations with team |
| 81 | + |
| 82 | +## Example Workflow |
| 83 | + |
| 84 | +```powershell |
| 85 | +# 1. Sync and create plan |
| 86 | +.\scripts\powershell\sync-upstream.ps1 -Mode interactive |
| 87 | +# Choose [P] Plan for commit abc123 |
| 88 | +
|
| 89 | +# 2. Evaluate |
| 90 | +code incoming/abc123/integration-plan.md |
| 91 | +# Fill out analysis sections |
| 92 | +
|
| 93 | +# 3. Test (if approved) |
| 94 | +git checkout -b test-abc123-integration |
| 95 | +git cherry-pick abc123 |
| 96 | +# Run tests, verify changes |
| 97 | +
|
| 98 | +# 4. Integrate (if successful) |
| 99 | +git checkout main |
| 100 | +git merge test-abc123-integration |
| 101 | +
|
| 102 | +# 5. Cleanup |
| 103 | +rm -r incoming/abc123 |
| 104 | +``` |
| 105 | + |
| 106 | +## Notes |
| 107 | + |
| 108 | +- All folders in `incoming/*/` are gitignored (except this README) |
| 109 | +- Plans are local to your workspace |
| 110 | +- Safe to delete folders after integration |
| 111 | +- Useful for tracking "good ideas that need work" |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +**Generated by**: `sync-upstream.ps1` |
| 116 | +**Part of**: Spec Kit Spark Fork Maintenance |
| 117 | +**Related**: [FORK_DIVERGENCE.md](../FORK_DIVERGENCE.md), [sync-upstream.ps1](../scripts/powershell/sync-upstream.ps1) |
0 commit comments