Design Guide - Creating Design Proposals
This guide explains how to create design discussions for approved Thunder features. The design discussion serves as your proposal for how to solve the problem.
🎯 When to Use This Guide
Create a design discussion when:
- ✅ You've been assigned to a feature request
- ✅ The feature requires architectural changes or new capabilities
- ✅ Community consensus exists on what to build
- ✅ You need to specify how it will be built
Don't create a design discussion for:
- ❌ Bug reports → Use bug report
- ❌ Minor improvements → Use fast track
- ❌ Unclear ideas or feature requests → Use problem definition guide
- ❌ Features you're not assigned to → Express interest on the feature issue first
Step 1: Create a Design Discussion
Start a design discussion to explore how to solve the problem and gather community feedback on your approach.
Prerequisites
- [ ] Feature issue approved and assigned to you
- [ ] You understand the problem (read the feature issue thoroughly)
- [ ] You've researched existing solutions and standards
Creating the Discussion
- Go to GitHub Discussions
- Select "Design" category
- Fill in all sections
Step 2: Community Collaboration
Once posted, collaborate with the community to refine the design.
Who Participates?
Design Author (you):
- Present the high-level approach
- Respond to questions and feedback
- Update the discussion as design evolves
- Drive toward consensus
Community Members:
- Ask clarifying questions
- Identify edge cases and potential issues
- Share relevant experience
- Suggest alternative approaches
- Validate security considerations
Maintainers:
- Provide architectural guidance
- Flag integration concerns
- Ensure alignment with Thunder's vision
- Guide toward feasible solutions
Building Consensus
Good signs of consensus:
- ✅ No major objections from maintainers
- ✅ Security concerns identified and addressed
- ✅ Integration points clarified
- ✅ Positive feedback from community
- ✅ Open questions resolved
Red flags:
- ❌ Maintainers expressing concerns about approach
- ❌ Multiple people suggesting different alternatives
- ❌ Unresolved security issues
- ❌ Technical feasibility questioned
- ❌ Conflicts with existing architecture
If consensus isn't reached:
- Keep discussing (may take 3-4 weeks)
- Consider a proof-of-concept implementation
- Bring to community call for live discussion
- In some cases, the feature may be declined at this stage
Step 3: Design Review
Maintainers will formally review your design proposal.
Review Outcomes
✅ Approved
What this means: Design is sound, ready for implementation.
Next steps:
- You can begin implementation (or someone else can)
Move to: Implementation Guide
🔄 Needs Revision
What this means: Good direction, but changes needed.
Common revision requests:
- Clarify component interactions
- Add missing security considerations
- Provide more implementation details
- Address backward compatibility concerns
Next steps:
- Address feedback in the design
- Iterate until approved
Timeline: Usually 1-2 revision cycles
❌ Rejected
What this means: Design has fundamental issues that can't be resolved.
Common rejection reasons:
- Technical infeasibility discovered
- Unfixable security vulnerabilities
- Performance concerns that can't be mitigated
- Breaking changes not acceptable
- Conflicts with architectural principles
When rejected:
-
Close feature issue with explanation
-
Update design discussion with outcome
This is okay! Not all designs work out. Better to discover issues during design than during implementation.
🔄 After Your Design is Approved
Implementation Phase
You can:
- Implement it yourself (move to Development Guide)
- Let someone else implement it
- Collaborate with multiple implementers
Track progress:
- Feature issue stays open until implemented
- Implementation PRs reference the design discussion
- You're credited as the design author
Design Evolution
Minor changes during implementation:
- Expected and normal
- Document in implementation PRs
- No need to update design discussion
Major changes during implementation:
- Bring back to design discussion
- Update design discussion if significant
- Get maintainer approval for major pivots
Remember: Good designs take time. A thorough design saves weeks of rework during implementation. Take the time to get it right! 🎯⚡