Skip to content

Feature Proposals

Building a significant feature takes time. Before you invest that effort, we want to make sure we're aligned on direction. We use a design document process for larger contributions to ensure your work has the best chance of being merged.

When to write a design document

Not every contribution needs a design document. Use this process for changes that have broad impact or require significant time investment.

Write a design document for:

  • New major features affecting multiple parts of the SDK
  • Breaking changes to existing APIs
  • Architectural changes requiring design discussion
  • Large contributions (> 1 week of work)
  • Features that introduce new concepts

Skip the design process for:

  • Bug fixes with clear solutions
  • Small improvements and enhancements
  • Documentation updates
  • New extensions in your own repository
  • Performance optimizations

When in doubt, open an issue first. We'll tell you if a design document is needed.

Process

The design document process helps align on requirements, explore alternatives, and identify edge cases before implementation begins.

  1. Check the roadmap — See if your idea aligns with our direction and isn't already planned
  2. Open an issue first — Describe the problem you're trying to solve. We need to validate the problem is worth solving before you invest time in a detailed proposal
  3. Create a design document — Once we agree the problem is worth solving, submit a PR to the designs folder in the docs repository using the template there. Reference the issue in your design document
  4. Gather feedback — We'll review and discuss with you, asking clarifying questions
  5. Get approval — When we merge the design document, that's your go-ahead to implement
  6. Implement — Follow the SDK contribution process
  7. Reference the design — Link to the approved design document in your implementation PR

Design document template

See the full template in the designs folder README.

Tips for effective proposals:

  • Focus on the problem first, solution comes second
  • Include concrete examples showing current pain and proposed improvement
  • Be open to feedback, the best solution might differ from your initial idea
  • Align with our development tenets