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
├── 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

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]