Ling0925
/
buster
mirror of https://github.com/buster-so/buster.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

updates to prds documentation

This commit is contained in:
dal 2025-03-20 08:18:21 -06:00
parent a4e76db49c
commit a7d0f0d206
No known key found for this signature in database
GPG Key ID: 16F4B0E1E9F61122
3 changed files with 528 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
api/documentation/prds.mdc
View File

@ -16,29 +16,107 @@ All PRDs should be stored in the `/prds` directory with the following structure:
/prds /prds
├── template.md # The master template for all PRDs ├── template.md # The master template for all PRDs
├── active/ # Active/In-progress PRDs ├── active/ # Active/In-progress PRDs
│ ├── feature_auth.md │ ├── project_feature_name.md # Project-level PRD
│ └── api_deployment.md │ ├── 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 ├── completed/ # Completed PRDs that have been shipped
│ ├── feature_user_auth.md │ ├── project_completed_feature.md
│ └── api_deployment.md │ └── api_completed_component.md
└── archived/ # Archived/Deprecated PRDs └── archived/ # Archived/Deprecated PRDs
``` ```
### Naming Convention ### Naming Convention
- Use snake_case for file names - Use snake_case for file names
- Include a prefix for the type of change: - Include a prefix for the type of change:
- `project_` for project-level PRDs that contain multiple sub-PRDs
- `feature_` for new features - `feature_` for new features
- `enhancement_` for improvements - `enhancement_` for improvements
- `fix_` for bug fixes - `fix_` for bug fixes
- `refactor_` for code refactoring - `refactor_` for code refactoring
- `api_` for API changes - `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 ## Using the Template
### Getting Started ### Getting Started
1. Copy [template.md](mdc:prds/template.md) to create a new PRD 1. For a new project with multiple components:
2. Place it in the `/prds/active` directory - Create a project-level PRD using [project_template.md](mdc:prds/project_template.md)
3. Fill out each section following the template's comments and guidelines - 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 ### Key Sections to Focus On
The template [template.md](mdc:prds/template.md) provides comprehensive sections. Pay special attention to: 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 - Include clear success criteria
- List dependencies between phases - List dependencies between phases
- Provide testing strategy for each phase - Provide testing strategy for each phase
- For project PRDs, reference all sub-PRDs with their status
4. **Testing Strategy** 4. **Testing Strategy**
- Unit test requirements - Unit test requirements
@ -66,6 +145,26 @@ The template [template.md](mdc:prds/template.md) provides comprehensive sections
## Best Practices ## 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 ### Documentation
1. Use clear, concise language 1. Use clear, concise language
2. Include code examples where relevant 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` - Deprecated PRDs → `/prds/archived`
2. Update status section regularly: 2. Update status section regularly:
- ✅ Completed items - Completed items
- ⏳ In Progress items - In Progress items
- 🔜 Upcoming items - Upcoming items
- ❌ Known Issues - Known Issues
### Review Process ### Review Process
1. Technical review 1. Technical review
@ -106,17 +205,26 @@ The template [template.md](mdc:prds/template.md) provides comprehensive sections
5. No rollback plan 5. No rollback plan
6. Missing security considerations 6. Missing security considerations
7. Undefined monitoring metrics 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 ## Example PRDs
Reference these example PRDs for guidance: 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 ## Checklist Before Submission
- [ ] All template sections completed - [ ] All template sections completed
- [ ] Technical design is detailed and complete - [ ] Technical design is detailed and complete
- [ ] File changes are documented - [ ] 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 - [ ] Testing strategy is defined
- [ ] Security considerations addressed - [ ] Security considerations addressed
- [ ] Dependencies and Files listed - [ ] Dependencies and Files listed
- [ ] File References included - [ ] File References included
- [ ] For project PRDs: all sub-PRDs are referenced with status
- [ ] For sub-PRDs: parent project PRD is referenced

230
api/prds/project_template.md Normal file
View File

@ -0,0 +1,230 @@
---
title: Project Name
author: Your Name
date: YYYY-MM-DD
status: Draft
---
# Project Name
## Problem Statement
<!--
Clearly articulate the high-level problem this project solves. Include:
- Current state
- Pain points
- Impact on users/system
- Why it needs to be solved now
- Any relevant metrics or data
-->
## Goals
<!-- List the high-level goals of this project -->
1.
2.
3.
## Non-Goals
<!-- List what is explicitly out of scope for this project -->
1.
2.
3.
## Technical Design
### Overview
<!--
Provide a high-level overview of the technical approach:
- Main components
- How they interact
- Key technologies used
-->
```mermaid
graph TD
A[Component A] --> B[Component B]
B --> C[Component C]
// Add your architecture diagram
```
### Component Breakdown
<!--
Break down the project into logical components. For each component:
- Describe its purpose
- Reference the sub-PRD that will implement it
- Define interfaces with other components
-->
#### 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
<!-- List all dependencies for this project -->
1.
2.
3.
## Implementation Plan
<!--
Break down the implementation into sub-PRDs and clearly define:
1. The order in which sub-PRDs should be implemented
2. Which sub-PRDs can be developed concurrently
3. Dependencies between sub-PRDs
4. How to avoid conflicts between concurrent development efforts
Track the status of each sub-PRD:
- Complete
- In Progress
- Upcoming
-->
### 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
<!-- Describe the first phase of implementation -->
**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
<!-- Describe the second phase of implementation -->
**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
<!-- Describe the third phase of implementation -->
**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
<!--
Provide a high-level testing strategy for the entire project.
Each sub-PRD will have more detailed testing plans.
-->
### Unit Tests
-
-
-
### Integration Tests
-
-
-
## Security Considerations
<!-- List security considerations for the entire project -->
-
-
-
## Monitoring and Logging
<!-- Describe monitoring and logging requirements -->
-
-
-
## Rollout Plan
<!-- Describe the plan for rolling out this project -->
1.
2.
3.
4.
## Appendix
### Related PRDs
<!-- List all sub-PRDs that are part of this project -->
- [Component 1 Name](link_to_sub_prd1.md)
- [Component 2 Name](link_to_sub_prd2.md)
- [Component 3 Name](link_to_sub_prd3.md)

177
api/prds/sub_prd_template.md Normal file
View File

@ -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
<!--
Clearly articulate the specific problem this component solves within the larger project. Include:
- How this fits into the larger project
- Specific pain points this component addresses
- Why this component is necessary
-->
## Goals
<!-- List the specific goals of this component -->
1.
2.
3.
## Non-Goals
<!-- List what is explicitly out of scope for this component -->
1.
2.
3.
## Technical Design
### Component Overview
<!--
Provide a detailed overview of this component:
- How it fits into the larger system
- Interfaces with other components
- Key technologies used
-->
```mermaid
graph TD
A[This Component] --> B[Other Component]
C[Another Component] --> A
// Add your component diagram
```
### Interfaces
<!--
Define all interfaces this component exposes to or consumes from other components:
- API endpoints
- Function signatures
- Data structures
- Events/messages
-->
#### 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
<!--
Provide detailed implementation information:
- Core algorithms
- Data flow
- Error handling
- Edge cases
-->
#### Core Logic
```rust
// Include actual code for core logic
fn core_function() -> Result<Type, Error> {
// Implementation details
}
```
### File Changes
<!--
List all files that will be:
- Created
- Modified
- Deleted
Include the purpose of each change
-->
#### 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
<!-- Provide a detailed testing strategy for this component -->
### 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
<!-- List security considerations specific to this component -->
-
-
-
## Dependencies on Other Components
<!--
List dependencies on other components in the project:
- Which components must be completed before this one
- Which components can be developed concurrently
- Potential conflict areas with concurrent development
-->
### 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
<!-- Provide a timeline for implementing this component -->
- Task 1: [Estimated time]
- Task 2: [Estimated time]
- Task 3: [Estimated time]
Total estimated time: [Total time]