Proposal guide

[senthalan]

Thunder Design Proposal Flow

This document describes the complete journey from idea to approved design in Thunder when creating new features or making significant architectural changes.

Visual Flow Diagram

                    ┌─────────────────────┐
                    │   💡 Someone Has    │
                    │   an Idea/Problem   │
                    └──────────┬──────────┘
                               │
                ┌──────────────┴──────────────┐
                │                             │
                ▼                             ▼
    ┌────────────────────┐        ┌────────────────────┐
    │  OPTIONAL PATH     │        │   DIRECT PATH      │
    │                    │        │                    │
    │ 1a. Create Ideas   │        │ 1b. Skip to        │
    │     Discussion     │        │     Feature Issue  │
    │                    │        │                    │
    │ • Problem unclear  │        │ • Problem is clear │
    │ • Need refinement  │        │ • Answers known    │
    │ • Explore solution │        │                    │
    └──────────┬─────────┘        └──────────┬─────────┘
               │                             │
               ▼                             │
    ┌────────────────────┐                   │
    │ Community Refines  │                   │
    │ the Idea           │                   │
    │                    │                   │
    │ Discussion evolves │                   │
    │ to clarify:        │                   │
    │ • The problem      │                   │
    │ • Who it impacts   │                   │
    │ • Why solve now    │                   │
    └──────────┬─────────┘                   │
               │                             │
        ┌──────┴──────┐                      │
        │             │                      │
        ▼             ▼                      │
    ┌────────┐   ┌────────┐                  │
    │Invalid │   │Valid   │                  │
    │        │   │Idea    │                  │
    │ Close  │   └───┬────┘                  │
    │ & Doc  │       │                       │
    └────────┘       │                       │
                     │                       │
           ┌─────────┴────────┐              │
           │                  │              │
           ▼                  ▼              │
    ┌─────────────┐      ┌──────────────┐    │
    │ Improvement │      |  2. Feature  │    │
    │   /Bug      │      │     Issue    │    │
    │   Issue     │      |     #123     │◄───┘
    │             │      |              |
    │             │      │   Needs:     │         
    │ Standard    │      │   • Problem  │
    │ workflow    │      │   • Why now  │
    └─────────────┘      |   • Who for  │
                         └────┬─────────┘
                              │
                              │
                              ▼
                     ┌────────────────────┐
                     │ 3. Project Mgt     │
                     │     Phase          │
                     │                    │
                     │ • Prioritize       │
                     │ • Assign milestone │
                     │ • Resource plan    │
                     └──────────┬─────────┘
                                │
                                ▼
                     ┌────────────────────┐
                     │ 4. Assignment      │
                     │    Mechanism       │
                     │                    │
                     │ Someone claims:    │
                     │ • Core team member │
                     │ • Original author  │
                     │ • External         │
                     │   volunteer        │
                     │                    │
                     │ Maintainer assigns │
                     │ & approves work    │
                     └──────────┬─────────┘
                                │
                                ▼
                     ┌────────────────────┐
                     │ 5. Create          │
                     │    "Design         │
                     │    Proposals"      │
                     │    Discussion      │
                     │                    │
                     │ MANDATORY:         │
                     │ • Link Feature     │
                     │   Issue #123       │
                     │ • Assigned person  │
                     │   starts design    │
                     └──────────┬─────────┘
                                │
                                ▼
                     ┌────────────────────┐
                     │ 6. Community       │
                     │    Refines Design  │
                     │                    │
                     │ Discuss:           │
                     │ • High-level       │
                     │   architecture     │
                     │ • Technical design │
                     │ • Security model   │
                     │ • Performance      │
                     │ • Compatibility    │
                     │ • Alternatives     │
                     └──────────┬─────────┘
                                │
                        ┌───────┴─────┐
                        │             │
                        ▼             ▼
                     ┌─────────┐   ┌─────────┐
                     │No       │   │Design   │
                     │Consensus│   │Consensus│
                     │         │   │Reached  │
                     │ Close   │   └───┬─────┘
                     │ Feature │       │
                     │ Issue   │       │
                     └─────────┘       │
                                       ▼
                           ┌────────────────────┐
                           │ 7. Write           │
                           │    Design          │
                           │    Proposal Doc    │
                           │                    │
                           │ File:              │
                           │ 0123-feature.md    │
                           │                    │
                           │ Status: Accepted   │
                           │ (default)          │
                           └──────────┬─────────┘
                                      │
                                      ▼
                           ┌────────────────────┐
                           │ 8. Submit PR       │
                           │                    │
                           │ • Link Feature     │
                           │   Issue #123       │
                           │ • Link Design      │
                           │   Discussion       │
                           │ • Request reviews: │
                           │   - Maintainers    │
                           │   - Security team  │
                           └──────────┬─────────┘
                                      │
                           ┌──────────┴──────────┐
                           │ Reviewers Evaluate: │
                           │                     │
                           │ ✓ Technical design  │
                           │ ✓ Security model    │
                           │ ✓ Feasibility       │
                           │ ✓ Performance       │
                           │ ✓ Compatibility     │
                           │ ✓ Standards         │
                           └──────────┬──────────┘
                                      │
                           ┌──────────┴──────────┐
                           │                     │
                           ▼                     ▼
                     ┌─────────┐             ┌─────────┐
                     │REJECTED │             │APPROVED │
                     │         │             │         │
                     │Security │             │Design   │
                     │or Tech  │             │Sound    │
                     │Issues   │             │         │
                     └────┬────┘             └────┬────┘
                          │                       │
                          │                       │
                          ▼                       ▼
                     ┌─────────────┐         ┌─────────────┐
                     │Update to    │         │Merge PR     │
                     │Rejected     │         │             │
                     │             │         │Status:      │
                     │Add detailed │         │Accepted     │
                     │reasoning    │         │             │
                     │             │         │Update Issue:│
                     │Merge PR     │         │• Label:     │
                     │             │         │  approved   │
                     │Close Feature│         │• Keep open  │
                     │Issue        │         │             │
                     │             │         │Ready for    │
                     │Archive for  │         │Development! │
                     │reference    │         └─────────────┘
                     └─────────────┘

---

KEY DECISION POINTS:

1. Entry Point:
   • Unclear problem → Start with Ideas discussion
   • Clear problem → Go directly to Feature issue

2. After Ideas Discussion:
   • Invalid → Close and document
   • Bug → Create bug issue (standard workflow)
   • Improvement → Create improvement issue (may need lightweight proposal)
   • Feature → Create feature issue (continue to design proposal)

3. Assignment:
   • Maintainer assigns/approves contributor
   • Prevents duplicate work and ensures ownership

4. After Design Review:
   • Rejected → Update status, merge with reasoning, close feature issue
   • Revise → Iterate on design proposal
   • Approved → Merge, ready for implementation

---

TRACEABILITY CHAIN:

Ideas Discussion (#D1) → Feature Issue (#123) → Design Discussion (#D2) → Design Proposal (0123-feature.md)
      (optional)              (required)            (required)              (required)
         ↓                        ↓                      ↓                         ↓
    Refine problem          Define scope          Design solution          Document & approve

---

ASSIGNMENT WORKFLOW:

┌─────────────────────────────────────────────────────────────────┐
│ Feature Issue #123 is triaged.                                │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│ Someone expresses interest (comment on issue):                  │
│                                                                 │
│ "I'd like to work on this. Here's my proposed timeline:         │
│  - Design discussion: 2 weeks                                   │
│  - Implementation: 4 weeks                                      │
│  I have experience with OAuth flows from [previous work]."      │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────────────────┐
│ Maintainer evaluates:                                          │
│ • Does contributor have relevant experience?                   │
│ • Is timeline realistic?                                       │
│ • Can we support/mentor this contributor?                      │
│ • Is anyone else already working on this?                      │
└──────────────────────┬─────────────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
    ┌────────┐   ┌────────┐   ┌────────┐
    │APPROVED│   │NEEDS   │   │ASSIGN  │
    │        │   │MORE    │   │TO CORE │
    │Assign  │   │INFO    │   │TEAM    │
    │issue   │   │        │   │        │
    └────┬───┘   └────────┘   └────────┘
         │
         ▼
    ┌─────────────────────────────────┐
    │ Maintainer assigns issue:       │
    │                                 │
    │ "Assigned to @contributor       │
    │  Please create design proposal  │
    │  discussion when ready.         │
    │  Let us know if you need        │
    │  guidance."                     │
    └─────────────────────────────────┘

---

FINAL STATUSES:

• Accepted → Design approved and ready for implementation
• Rejected → Design not approved (merged with detailed reasoning)
• Implemented → Design was accepted and development is complete

Simplified Overview

Two Entry Paths

Path A: Complex/Unclear Problem

Ideas Discussion → Feature Issue → Assignment → Design Discussion → Proposal PR → Approved
     💭               🎯              👤                 💬           📄             ✅

Path B: Clear Problem

Feature Issue → Assignment → Design Discussion → Proposal PR → Approved
     🎯            👤                💬             📄             ✅

[darshanasbg]

IMO, if somebody have a high level idea, they should be discuss about it without needing to create a proposal issue..

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.69%. Comparing base (0820020) to head (899781c).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #477   +/-   ##
=======================================
  Coverage   60.69%   60.69%           
=======================================
  Files         149      149           
  Lines       19071    19071           
=======================================
  Hits        11575    11575           
  Misses       6171     6171           
  Partials     1325     1325           

Flag	Coverage Δ
backend-combined-postgres	52.18% <ø> (ø)
backend-combined-sqlite	52.18% <ø> (ø)
backend-integration-postgres	52.18% <ø> (ø)
backend-integration-sqlite	52.18% <ø> (ø)
backend-unit	18.44% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.