From a7d0f0d2064755733e2764d87f66909199ecfc7a Mon Sep 17 00:00:00 2001 From: dal Date: Thu, 20 Mar 2025 08:18:21 -0600 Subject: [PATCH] updates to prds documentation --- api/documentation/prds.mdc | 134 ++++++++++++++++++-- api/prds/project_template.md | 230 +++++++++++++++++++++++++++++++++++ api/prds/sub_prd_template.md | 177 +++++++++++++++++++++++++++ 3 files changed, 528 insertions(+), 13 deletions(-) create mode 100644 api/prds/project_template.md create mode 100644 api/prds/sub_prd_template.md diff --git a/api/documentation/prds.mdc b/api/documentation/prds.mdc index 836790de4..5b7b28fc7 100644 --- a/api/documentation/prds.mdc +++ b/api/documentation/prds.mdc @@ -16,29 +16,107 @@ All PRDs should be stored in the `/prds` directory with the following structure: /prds ├── template.md # The master template for all PRDs ├── active/ # Active/In-progress PRDs -│ ├── feature_auth.md -│ └── api_deployment.md +│ ├── project_feature_name.md # Project-level PRD +│ ├── api_feature_component1.md # Sub-PRD for component 1 +│ └── api_feature_component2.md # Sub-PRD for component 2 ├── completed/ # Completed PRDs that have been shipped -│ ├── feature_user_auth.md -│ └── api_deployment.md +│ ├── project_completed_feature.md +│ └── api_completed_component.md └── archived/ # Archived/Deprecated PRDs ``` ### Naming Convention - Use snake_case for file names - Include a prefix for the type of change: + - `project_` for project-level PRDs that contain multiple sub-PRDs - `feature_` for new features - `enhancement_` for improvements - `fix_` for bug fixes - `refactor_` for code refactoring - `api_` for API changes +## Project PRDs and Sub-PRDs + +### Project PRD Structure +Project PRDs serve as the main document for large features that require multiple components or endpoints. They should: + +1. Provide a high-level overview of the entire feature +2. Break down the implementation into logical components +3. Reference individual sub-PRDs for each component +4. Track the status of each sub-PRD +5. Define dependencies between sub-PRDs + +Example project PRD sections: +```markdown +## Implementation Plan + +The implementation will be broken down into six separate PRDs, each focusing on a specific endpoint: + +1. [Add Dashboard to Collections REST Endpoint](api_add_dashboards_to_collection.md) +2. [Remove Dashboard from Collections REST Endpoint](api_remove_dashboards_from_collection.md) +3. [Add Metric to Collections REST Endpoint](api_add_metrics_to_collection.md) +4. [Remove Metric from Collections REST Endpoint](api_remove_metrics_from_collection.md) +5. [Add Assets to Collection REST Endpoint](api_add_assets_to_collection.md) +6. [Remove Assets from Collection REST Endpoint](api_remove_assets_from_collection.md) +``` + +### Sub-PRD Structure +Sub-PRDs focus on specific components of the larger project. They should: + +1. Reference the parent project PRD +2. Focus on detailed implementation of a specific component +3. Include all technical details required for implementation +4. Be independently implementable (when possible) +5. Follow the standard PRD template + +### Enabling Concurrent Development + +The project PRD and sub-PRD structure is designed to enable efficient concurrent development by: + +1. **Clear Component Boundaries**: Each sub-PRD should have well-defined boundaries that minimize overlap with other components. + +2. **Explicit Dependencies**: The project PRD should clearly state which sub-PRDs depend on others, allowing teams to plan their work accordingly. + +3. **Interface Definitions**: Each sub-PRD should define clear interfaces for how other components interact with it, reducing the risk of integration issues. + +4. **Conflict Identification**: The project PRD should identify potential areas of conflict between concurrently developed components and provide strategies to mitigate them. + +5. **Integration Strategy**: The project PRD should define how and when components will be integrated, including any feature flag strategies to allow incomplete features to be merged without affecting production. + +### Example Workflow + +1. **Project Planning**: + - Create the project PRD with a clear breakdown of components + - Define dependencies and development order + - Identify which components can be developed concurrently + +2. **Development Kickoff**: + - Begin work on foundation components that others depend on + - Once foundation is complete, start concurrent development of independent components + - Regularly update the project PRD with status changes + +3. **Integration**: + - Follow the integration strategy defined in the project PRD + - Address any conflicts that arise during integration + - Update the project PRD with lessons learned + +4. **Completion**: + - Move completed PRDs to the `/prds/completed` directory + - Update the project PRD to reflect completion + - Document any deviations from the original plan + ## Using the Template ### Getting Started -1. Copy [template.md](mdc:prds/template.md) to create a new PRD -2. Place it in the `/prds/active` directory -3. Fill out each section following the template's comments and guidelines +1. For a new project with multiple components: + - Create a project-level PRD using [project_template.md](mdc:prds/project_template.md) + - Place it in the `/prds/active` directory with prefix `project_` + - Create sub-PRDs for each component using [sub_prd_template.md](mdc:prds/sub_prd_template.md) with appropriate prefixes + +2. For a standalone feature: + - Copy [template.md](mdc:prds/template.md) to create a new PRD + - Place it in the `/prds/active` directory + - Fill out each section following the template's guidelines ### Key Sections to Focus On The template [template.md](mdc:prds/template.md) provides comprehensive sections. Pay special attention to: @@ -59,6 +137,7 @@ The template [template.md](mdc:prds/template.md) provides comprehensive sections - Include clear success criteria - List dependencies between phases - Provide testing strategy for each phase + - For project PRDs, reference all sub-PRDs with their status 4. **Testing Strategy** - Unit test requirements @@ -66,6 +145,26 @@ The template [template.md](mdc:prds/template.md) provides comprehensive sections ## Best Practices +### Project PRD Best Practices +1. Keep the project PRD focused on high-level architecture and component relationships +2. Clearly define the scope of each sub-PRD +3. Maintain a status indicator for each sub-PRD ( Complete, ⏳ In Progress, Upcoming) +4. Update the project PRD when sub-PRDs are completed +5. Include a visual representation of component relationships when possible +6. Define clear interfaces between components +7. **Explicitly define the order in which sub-PRDs should be implemented** +8. **Identify which sub-PRDs can be developed concurrently without conflicts** +9. **Document dependencies between sub-PRDs to prevent blocking issues** +10. **Provide strategies for avoiding conflicts during concurrent development** +11. **Establish clear integration points for components developed in parallel** + +### Sub-PRD Best Practices +1. Always reference the parent project PRD +2. Focus on detailed implementation of a specific component +3. Include all technical details required for implementation +4. Ensure consistency with other sub-PRDs in the same project +5. Follow the standard PRD template structure + ### Documentation 1. Use clear, concise language 2. Include code examples where relevant @@ -80,10 +179,10 @@ The template [template.md](mdc:prds/template.md) provides comprehensive sections - Deprecated PRDs → `/prds/archived` 2. Update status section regularly: - - ✅ Completed items - - ⏳ In Progress items - - 🔜 Upcoming items - - ❌ Known Issues + - Completed items + - In Progress items + - Upcoming items + - Known Issues ### Review Process 1. Technical review @@ -106,17 +205,26 @@ The template [template.md](mdc:prds/template.md) provides comprehensive sections 5. No rollback plan 6. Missing security considerations 7. Undefined monitoring metrics +8. Inconsistencies between project PRD and sub-PRDs +9. Overlapping responsibilities between sub-PRDs +10. Missing dependencies between sub-PRDs ## Example PRDs Reference these example PRDs for guidance: -[template.md](mdc:prds/template.md) +- Project PRD: [Collections REST Endpoints](mdc:prds/active/project_collections_rest_endpoints.md) +- Sub-PRD: [Add Metrics to Collection](mdc:prds/active/api_add_metrics_to_collection.md) +- Project Template: [project_template.md](mdc:prds/project_template.md) +- Sub-PRD Template: [sub_prd_template.md](mdc:prds/sub_prd_template.md) +- Standard Template: [template.md](mdc:prds/template.md) ## Checklist Before Submission - [ ] All template sections completed - [ ] Technical design is detailed and complete - [ ] File changes are documented -- [ ] Implementation phases are clear (can be as many as you need.) +- [ ] Implementation phases are clear (can be as many as you need) - [ ] Testing strategy is defined - [ ] Security considerations addressed - [ ] Dependencies and Files listed - [ ] File References included +- [ ] For project PRDs: all sub-PRDs are referenced with status +- [ ] For sub-PRDs: parent project PRD is referenced diff --git a/api/prds/project_template.md b/api/prds/project_template.md new file mode 100644 index 000000000..b653e12c0 --- /dev/null +++ b/api/prds/project_template.md @@ -0,0 +1,230 @@ +--- +title: Project Name +author: Your Name +date: YYYY-MM-DD +status: Draft +--- + +# Project Name + +## Problem Statement + + + +## Goals + + +1. +2. +3. + +## Non-Goals + + +1. +2. +3. + +## Technical Design + +### Overview + + + +```mermaid +graph TD + A[Component A] --> B[Component B] + B --> C[Component C] + // Add your architecture diagram +``` + +### Component Breakdown + + + +#### Component 1: [Name] +- Purpose: +- Sub-PRD: [Link to sub-PRD] +- Interfaces: + - Input: + - Output: + +#### Component 2: [Name] +- Purpose: +- Sub-PRD: [Link to sub-PRD] +- Interfaces: + - Input: + - Output: + +### Dependencies + + +1. +2. +3. + +## Implementation Plan + + + +### Sub-PRD Implementation Order and Dependencies + +The implementation will be broken down into the following sub-PRDs, with their dependencies and development order clearly defined: + +1. [Foundation Component](link_to_foundation_prd.md) - **Must be completed first** + - This PRD establishes the core functionality needed by all other components + - Dependencies: None + - Required for: All other PRDs + +2. [Component A](link_to_component_a_prd.md) - **Can be developed concurrently with Components B and C** + - Dependencies: Foundation Component + - Required for: Component D + - Potential conflict areas with Component B: [Describe and provide mitigation] + +3. [Component B](link_to_component_b_prd.md) - **Can be developed concurrently with Components A and C** + - Dependencies: Foundation Component + - Required for: Component E + - Potential conflict areas with Component A: [Describe and provide mitigation] + +4. [Component C](link_to_component_c_prd.md) - **Can be developed concurrently with Components A and B** + - Dependencies: Foundation Component + - Required for: None + - No conflicts with other concurrent components + +5. [Component D](link_to_component_d_prd.md) - **Must wait for Component A** + - Dependencies: Foundation Component, Component A + - Required for: None + +6. [Component E](link_to_component_e_prd.md) - **Must wait for Component B** + - Dependencies: Foundation Component, Component B + - Required for: None + +### Concurrent Development Strategy + +To enable efficient concurrent development without conflicts: + +1. **Clear Component Interfaces**: Each sub-PRD must define clear interfaces for how other components interact with it +2. **Separate Database Concerns**: Ensure database schema changes are coordinated to prevent conflicts +3. **Modular Code Structure**: Organize code to minimize overlap between components +4. **Regular Integration**: Plan for regular integration points to catch conflicts early +5. **Feature Flags**: Use feature flags to allow merging incomplete features without affecting production + +### Phase 1: Foundation + + + +**Components:** +- Foundation Component + +**Success Criteria:** +- Core interfaces defined and implemented +- Database schema changes completed +- Unit tests passing at 90%+ coverage +- Integration tests defined + +### Phase 2: Parallel Component Development + + + +**Components:** +- Component A +- Component B +- Component C + +**Success Criteria:** +- All components implemented according to their respective PRDs +- Components successfully integrated with Foundation Component +- No regressions in Foundation Component functionality +- Unit and integration tests passing + +### Phase 3: Dependent Components + + + +**Components:** +- Component D +- Component E + +**Success Criteria:** +- All components implemented according to their respective PRDs +- Full system integration completed +- End-to-end tests passing +- Performance benchmarks met + +## Testing Strategy + + + +### Unit Tests + +- +- +- + +### Integration Tests + +- +- +- + +## Security Considerations + + +- +- +- + +## Monitoring and Logging + + +- +- +- + +## Rollout Plan + + +1. +2. +3. +4. + +## Appendix + +### Related PRDs + + +- [Component 1 Name](link_to_sub_prd1.md) +- [Component 2 Name](link_to_sub_prd2.md) +- [Component 3 Name](link_to_sub_prd3.md) diff --git a/api/prds/sub_prd_template.md b/api/prds/sub_prd_template.md new file mode 100644 index 000000000..9c92e8943 --- /dev/null +++ b/api/prds/sub_prd_template.md @@ -0,0 +1,177 @@ +--- +title: Component Name +author: Your Name +date: YYYY-MM-DD +status: Draft +parent_prd: project_name.md +--- + +# Component Name + +## Parent Project + +This is a sub-PRD of the [Project Name](project_name.md) project. Please refer to the parent PRD for the overall project context, goals, and implementation plan. + +## Problem Statement + + + +## Goals + + +1. +2. +3. + +## Non-Goals + + +1. +2. +3. + +## Technical Design + +### Component Overview + + + +```mermaid +graph TD + A[This Component] --> B[Other Component] + C[Another Component] --> A + // Add your component diagram +``` + +### Interfaces + + + +#### Exposed Interfaces + +```rust +// Include actual code structures/types for interfaces this component exposes +struct ExposedInterface { + // Include fields and their purposes + field1: Type1, // Purpose of field1 + field2: Type2, // Purpose of field2 +} +``` + +#### Consumed Interfaces + +```rust +// Include actual code structures/types for interfaces this component consumes +struct ConsumedInterface { + // Include fields and their purposes + field1: Type1, // Purpose of field1 + field2: Type2, // Purpose of field2 +} +``` + +### Implementation Details + + + +#### Core Logic + +```rust +// Include actual code for core logic +fn core_function() -> Result { + // Implementation details +} +``` + +### File Changes + + + +#### New Files +- `src/new_module/new_file.rs` + - Purpose: [Describe purpose] + - Key components: [List key components] + - Dependencies: [List dependencies] + +#### Modified Files +- `src/existing_module/existing_file.rs` + - Changes: [Describe changes] + - Purpose: [Describe purpose of changes] + +## Testing Strategy + + + +### Unit Tests + +- Test case 1: [Description] + - Input: [Input description] + - Expected output: [Expected output description] + - Edge cases: [List edge cases] + +### Integration Tests + +- Test scenario 1: [Description] + - Components involved: [List components] + - Test steps: [List steps] + - Expected outcome: [Describe expected outcome] + +## Security Considerations + + +- +- +- + +## Dependencies on Other Components + + + +### Required Components +- [Component Name](component_prd.md): [Describe dependency] + +### Concurrent Development +- [Component Name](component_prd.md): [Describe how concurrent development will work] + - Potential conflicts: [Describe potential conflicts] + - Mitigation strategy: [Describe mitigation strategy] + +## Implementation Timeline + + +- Task 1: [Estimated time] +- Task 2: [Estimated time] +- Task 3: [Estimated time] + +Total estimated time: [Total time]