From 2b0f9dfd4d9ef77d02f6a8470b5a4bd00572ac60 Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Thu, 20 Nov 2025 16:24:17 +0000 Subject: [PATCH] docs: add RFC writing and review guides --- .kiro/steering/rfc-review-guide.md | 185 ++++++++++++++++++++++++++++ .kiro/steering/rfc-writing-guide.md | 159 ++++++++++++++++++++++++ 2 files changed, 344 insertions(+) create mode 100644 .kiro/steering/rfc-review-guide.md create mode 100644 .kiro/steering/rfc-writing-guide.md diff --git a/.kiro/steering/rfc-review-guide.md b/.kiro/steering/rfc-review-guide.md new file mode 100644 index 000000000..66adb3402 --- /dev/null +++ b/.kiro/steering/rfc-review-guide.md @@ -0,0 +1,185 @@ +# RFC Review Guide + +This guide provides criteria and best practices for reviewing AWS CDK RFCs effectively. + +## Quality Indicators for Good RFCs + +### Essential Components + +**Working Backwards**: Comprehensive user experience documentation with concrete examples, README sections, and CHANGELOG entries. This should read like actual product documentation. + +**Technical Depth**: Detailed algorithms, edge cases, implementation specifics, and formal definitions. The RFC should provide enough detail to implement the feature. + +**API Design**: Clear interfaces, proper abstractions, inheritance hierarchies, and complete method signatures. APIs should follow CDK patterns and be extensible. + +**Implementation Planning**: Phased approach with concrete tasks, timelines, and migration strategies. The plan should be realistic and actionable. + +**Alternatives Analysis**: Thorough consideration of different approaches with trade-offs and rationale. Show that multiple solutions were explored. + +### Structure and Documentation + +**Clear Problem Statement**: Well-defined motivation, scope, and customer impact. Why does this feature matter? + +**Comprehensive Examples**: Multiple use cases with complete code samples in all supported languages. Examples should be realistic and runnable. + +**Migration Strategy**: For breaking changes, detailed upgrade paths and compatibility plans. How will existing users adopt this? + +**Security Considerations**: Proper handling of permissions, cross-account scenarios, and IAM policies. Security should not be an afterthought. + +**Extensibility**: Future-proofing, enhancement considerations, and backward compatibility. How will this evolve? + +## Red Flags for Poor RFCs + +**Brevity Without Substance**: Too short for the complexity of the feature (under 5 pages for complex features). Lack of detail indicates insufficient thinking. + +**Missing Working Backwards**: No user experience documentation or README sections. Without this, the RFC is just a technical spec. + +**Incomplete API Design**: Vague interfaces, missing method signatures, or unclear abstractions. APIs should be fully specified. + +**No Implementation Plan**: Lack of concrete next steps or phased approach. How will this actually get built? + +**Missing Alternatives**: No consideration of other approaches or design decisions. Was this the only option explored? + +**Unsigned API Bar Raiser**: Missing required sign-off from designated reviewer. Process compliance matters. + +## Review Checklist + +### Content Quality + +- [ ] Working backwards section with realistic examples and README content +- [ ] Detailed technical implementation approach with algorithms and data structures +- [ ] Comprehensive API documentation with complete type definitions +- [ ] Implementation plan with phases, tasks, and concrete deliverables +- [ ] Analysis of alternatives with clear trade-offs and decision rationale +- [ ] Security, compatibility, and performance considerations addressed + +### Process Compliance + +- [ ] API Bar Raiser assigned and signed off (status/api-approved label) +- [ ] Proper RFC template structure followed with all sections +- [ ] All required sections completed (not just placeholders) +- [ ] Tracking issue properly linked and maintained +- [ ] Appropriate labels applied throughout lifecycle + +### Technical Review + +- [ ] API design follows CDK patterns and conventions +- [ ] Breaking changes properly handled with migration paths +- [ ] Edge cases, error scenarios, and failure modes addressed +- [ ] Performance, scalability, and resource usage considerations +- [ ] Integration with existing CDK features and constructs + +## Review Process + +### Before Reviewing + +1. Check if RFC has API Bar Raiser sign-off requirement +2. Verify RFC follows the template structure +3. Ensure tracking issue is properly linked + +### During Review + +**Completeness Check**: All required sections present, working backwards artifacts included, technical solution documented, implementation plan provided. + +**Quality Assessment**: Technical depth appropriate for complexity, examples are practical and realistic, API design is consistent and extensible, error handling and edge cases considered. + +**Feasibility Review**: Implementation approach is realistic, dependencies and prerequisites identified, timeline and resource requirements reasonable, breaking change impact assessed. + +### Questions to Ask + +1. Does this RFC solve a real customer problem? +2. Is the proposed API intuitive and consistent with CDK patterns? +3. Are the examples realistic and comprehensive? +4. Is the implementation approach feasible and well-planned? +5. Have alternatives been properly considered? +6. Are breaking changes properly justified and documented? +7. Is the technical depth appropriate for the feature complexity? + +## Review Feedback Guidelines + +### Constructive Feedback + +- Ask for specific examples when concepts are unclear or abstract +- Request detailed implementation for complex features and algorithms +- Suggest alternative approaches with clear reasoning and trade-offs +- Point out missing edge cases, error scenarios, or failure modes +- Recommend improvements to API ergonomics and developer experience + +### What to Look For + +**In Working Backwards**: Does it read like real documentation? Are examples complete and realistic? Would a customer understand how to use this? + +**In Technical Design**: Is there enough detail to implement? Are edge cases covered? Are algorithms and data structures specified? + +**In API Design**: Is it consistent with CDK patterns? Is it extensible? Are all methods and properties documented? + +**In Implementation Plan**: Is it realistic? Are phases clearly defined? Are dependencies identified? + +**In Alternatives**: Were multiple approaches considered? Is the rationale clear? Are trade-offs honestly assessed? + +## Approval Criteria + +### Must Have + +- Complete working backwards documentation +- Comprehensive technical solution +- Realistic implementation plan +- API Bar Raiser sign-off (if required) +- Proper consideration of alternatives + +### Should Have + +- Multiple practical examples +- Detailed API documentation +- Error handling strategy +- Migration/compatibility plan +- Performance considerations + +### Nice to Have + +- Formal mathematical definitions +- Comprehensive appendices +- Advanced use case coverage +- Integration with other services + +## Common Issues and Solutions + +**Issue: Incomplete Working Backwards** +Solution: Request comprehensive README with multiple examples and use cases + +**Issue: Insufficient Technical Depth** +Solution: Ask for detailed implementation approach, algorithms, and edge case handling + +**Issue: Poor API Design** +Solution: Review for consistency, extensibility, and CDK patterns compliance + +**Issue: Missing Implementation Plan** +Solution: Require phased approach with concrete tasks and timelines + +**Issue: No Alternative Analysis** +Solution: Request comparison of different approaches with trade-offs + +## Examples to Study + +### Excellent RFCs + +- **RFC 162 (Refactoring Support)**: Exceptional technical depth with formal definitions +- **RFC 49 (Continuous Delivery)**: Comprehensive end-to-end solution with security model +- **RFC 431 (SageMaker L2)**: Excellent API design with clear abstractions +- **RFC 340 (Firehose L2)**: Comprehensive feature coverage with thorough alternatives + +### Poor RFCs to Avoid + +- **RFC 95 (Cognito)**: Extremely brief, no working backwards, missing technical details +- **RFC 359 (Construct Hub Deny List)**: Very short, lacks comprehensive coverage +- **RFC 670/673 (Application Signals)**: Incomplete, not signed off, limited examples + +## Final Recommendations + +1. **Be Thorough**: Don't approve RFCs that lack essential details +2. **Focus on User Experience**: Ensure working backwards truly represents customer value +3. **Demand Quality**: High-impact features require high-quality documentation +4. **Consider Maintainability**: Evaluate long-term support and evolution +5. **Validate Feasibility**: Ensure implementation approach is realistic and well-planned +6. **Check Process**: Verify API Bar Raiser sign-off and proper labels +7. **Think Long-term**: Consider how this will evolve and integrate with future features diff --git a/.kiro/steering/rfc-writing-guide.md b/.kiro/steering/rfc-writing-guide.md new file mode 100644 index 000000000..0bd9a3997 --- /dev/null +++ b/.kiro/steering/rfc-writing-guide.md @@ -0,0 +1,159 @@ +# RFC Writing Guide + +This guide provides best practices for writing high-quality AWS CDK RFCs based on analysis of successful and unsuccessful RFCs. + +## Start with Working Backwards + +The working backwards section is the most important part of your RFC. It should read like documentation for a feature that already exists. + +**Write the README first**: Create comprehensive user documentation as if the feature is already shipped. Include installation instructions, basic usage, advanced scenarios, and API reference. + +**Include CHANGELOG entries**: Write the release notes customers will see. Use conventional commit format: `feat(service): add L2 constructs for ServiceName` + +**Provide complete examples**: Show realistic usage patterns with full, runnable code samples. Cover simple to complex scenarios. + +**Cover all languages**: Include examples for TypeScript, Python, Java, C#, and Go where applicable. + +## Technical Design Requirements + +Provide comprehensive technical depth appropriate to the feature complexity. + +**Deep technical detail**: Include algorithms, data structures, implementation specifics, and architectural patterns. Don't be vague. + +**Edge case analysis**: Consider failure modes, error scenarios, boundary conditions, and how the system behaves under stress. + +**Formal definitions**: Use mathematical notation, pseudocode, or state diagrams where appropriate to clarify complex behavior. + +**Architecture diagrams**: Visual representations of complex systems, component interactions, and data flows. + +## API Design Excellence + +**Complete interfaces**: Define all methods, properties, type signatures, and return types. Show the full contract. + +**Inheritance hierarchies**: Clearly show class relationships, abstractions, and how components compose together. + +**Consistent patterns**: Follow existing CDK conventions, naming schemes, and design patterns. Don't invent new patterns without justification. + +**Extensibility**: Design for future enhancements and backward compatibility. Consider how users will extend your constructs. + +## Implementation Planning + +**Phased approach**: Break large features into manageable, deliverable phases with clear milestones. + +**Concrete tasks**: List specific implementation steps with owners, timelines, and dependencies. + +**Migration strategy**: For breaking changes, provide detailed upgrade paths and compatibility plans. + +**Testing strategy**: Define unit tests, integration tests, and how the feature will be validated. + +## Alternatives and Trade-offs + +**Multiple approaches**: Consider at least 2-3 different design alternatives. Show you've explored the solution space. + +**Clear rationale**: Explain why the chosen approach is superior with specific reasoning. + +**Trade-off analysis**: Document pros and cons of each alternative honestly. + +**Future considerations**: Note what options remain open for later enhancements. + +## Common Pitfalls to Avoid + +### Content Issues + +- **Too brief**: RFCs under 5 pages for complex features lack necessary detail +- **Missing examples**: Abstract descriptions without concrete usage patterns +- **Incomplete APIs**: Vague method signatures or missing type definitions +- **No error handling**: Ignoring failure scenarios and edge cases +- **Vendor-in dependencies**: Copying code instead of proper dependency management + +### Process Issues + +- **Skipping API Bar Raiser**: Not getting required sign-off before implementation +- **Incomplete templates**: Leaving sections as placeholders or "TBD" +- **Missing tracking**: Not linking to GitHub issues or maintaining status +- **Poor formatting**: Inconsistent markdown, broken links, or unclear structure + +### Technical Issues + +- **Breaking CDK patterns**: Inconsistent with existing construct library conventions +- **Security oversights**: Missing IAM considerations or cross-account scenarios +- **Performance blindness**: Not considering scalability or resource usage +- **Integration gaps**: Failing to consider interaction with existing features + +## RFC Structure Template + +### 1. Summary and Motivation + +- Clear problem statement with customer impact +- Scope definition and success criteria +- Background context and current limitations + +### 2. Working Backwards + +- Complete README documentation +- CHANGELOG entries +- User experience walkthrough +- Code examples in multiple languages + +### 3. Technical Design + +- Architecture overview with diagrams +- Detailed implementation approach +- Data structures and algorithms +- Error handling and edge cases + +### 4. API Design + +- Complete interface definitions +- Method signatures and type information +- Usage patterns and examples +- Backward compatibility considerations + +### 5. Implementation Plan + +- Phased delivery approach +- Concrete tasks and milestones +- Testing and validation strategy +- Migration and rollout plan + +### 6. Alternatives Considered + +- Multiple design approaches +- Trade-off analysis +- Rationale for chosen solution +- Future enhancement possibilities + +## Quality Checklist + +Before submitting your RFC: + +- [ ] Working backwards section reads like actual user documentation +- [ ] Technical design includes sufficient detail for implementation +- [ ] API design follows CDK patterns and conventions +- [ ] Implementation plan is concrete and realistic +- [ ] Alternatives analysis shows thorough consideration +- [ ] All code examples are complete and functional +- [ ] Security and performance implications addressed +- [ ] Migration strategy provided for breaking changes +- [ ] API Bar Raiser identified and engaged +- [ ] All template sections completed (no placeholders) + +## Examples of Excellence + +Study these high-quality RFCs for inspiration: + +- **RFC 162 (Refactoring Support)**: Exceptional technical depth with formal definitions and comprehensive appendices +- **RFC 49 (Continuous Delivery)**: Complete end-to-end solution with security model and migration strategy +- **RFC 431 (SageMaker L2)**: Excellent API design with clear abstractions and future extensibility +- **RFC 340 (Firehose L2)**: Comprehensive feature coverage with multiple destinations and thorough alternatives analysis + +## Final Tips + +1. **Start with the User**: Always begin with the working backwards section +2. **Be Comprehensive**: Better to over-document than under-document +3. **Use Real Examples**: Provide practical, runnable code samples +4. **Plan Implementation**: Think through how you'll actually build this +5. **Consider Alternatives**: Show you've thought about different approaches +6. **Get Feedback Early**: Share drafts with colleagues before formal review +7. **Iterate**: Be prepared to revise based on feedback +8. **Focus on Quality**: High-impact features deserve high-quality RFCs