Skip to content

Commit 547331d

Browse files
author
Sunil Thaha
committed
docs: add enhancement proposal template
Add structured template for enhancement proposals to improve documentation consistency and provide clear guidelines for contributors proposing new features or significant changes. Signed-off-by: Sunil Thaha <[email protected]>
1 parent 8191ca8 commit 547331d

File tree

3 files changed

+279
-0
lines changed

3 files changed

+279
-0
lines changed

‎docs/developer/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ This section contains documentation for developers working on Kepler.
66

77
- [Power Attribution Guide](power-attribution-guide.md) - Comprehensive guide on how Kepler measures and attributes power consumption to processes, containers, VMs, and pods
88

9+
## Enhancement Proposals
10+
11+
- [Enhancement Proposals](proposal/) - Technical proposals for major features and changes to Kepler
12+
913
## Development Workflow
1014

1115
- [Pre-commit Setup](pre-commit.md) - Setting up pre-commit hooks for code quality

‎docs/developer/proposal/EP_TEMPLATE.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
# EP-XXX: [Enhancement Title]
2+
3+
**Status**: Draft
4+
**Author**: [Your Name]
5+
**Created**: YYYY-MM-DD
6+
**Last Updated**: YYYY-MM-DD
7+
8+
## Summary
9+
10+
[Provide a concise, one-paragraph summary of the proposed enhancement. Explain what it is and why it's needed. This should be understandable by a general audience.]
11+
12+
## Problem Statement
13+
14+
[Describe the problem this enhancement aims to solve. What are the pain points or limitations in the current system? Why is this change necessary?]
15+
16+
### Current Limitations
17+
18+
[List the specific limitations of the current implementation that this proposal addresses.]
19+
20+
1. Limitation 1...
21+
2. Limitation 2...
22+
3. ...
23+
24+
## Goals
25+
26+
[List the primary objectives of this proposal. What should be achieved by implementing this enhancement?]
27+
28+
- **Primary Goal**: ...
29+
- **Secondary Goal**: ...
30+
- ...
31+
32+
## Non-Goals
33+
34+
[List what is explicitly out of scope for this proposal. This helps to focus the discussion and set clear boundaries.]
35+
36+
- ...
37+
- ...
38+
39+
## Requirements
40+
41+
### Functional Requirements
42+
43+
[List the specific functional requirements. These should be testable and describe what the system must do.]
44+
45+
- Requirement 1...
46+
- Requirement 2...
47+
- ...
48+
49+
### Non-Functional Requirements
50+
51+
[List the non-functional requirements, such as performance, reliability, security, maintainability, and testability.]
52+
53+
- **Performance**: ...
54+
- **Reliability**: ...
55+
- **Security**: ...
56+
- **Maintainability**: ...
57+
- **Testability**: ...
58+
59+
## Proposed Solution
60+
61+
### High-Level Architecture
62+
63+
[Provide a high-level overview of the proposed solution. Use diagrams, text, or both to illustrate the new architecture and how it fits into the existing system.]
64+
65+
```text
66+
[ASCII diagram or high-level description]
67+
```
68+
69+
### Key Design Choices
70+
71+
[Explain any significant design decisions made in the proposed solution. For example, choice of libraries, algorithms, or patterns.]
72+
73+
## Detailed Design
74+
75+
### Package Structure
76+
77+
[Show the proposed changes to the project's directory and package structure.]
78+
79+
```text
80+
internal/
81+
├── new-package/
82+
│ ├── component.go
83+
│ └── component_test.go
84+
└── existing-package/
85+
└── modified_file.go
86+
```
87+
88+
### API/Interface Changes
89+
90+
[Describe any changes to public APIs, service interfaces, or data structures. Show code snippets for new or modified interfaces.]
91+
92+
## Configuration
93+
94+
[Describe how the new feature will be configured. Include details on new configuration files, CLI flags, and environment variables.]
95+
96+
### Main Configuration Changes
97+
98+
[Show the proposed changes to the main configuration file (e.g., `config.go` or `config.yaml`).]
99+
100+
```go
101+
// Example config struct change
102+
type NewFeatureConfig struct {
103+
Enabled *bool `yaml:"enabled"`
104+
SomeValue string `yaml:"someValue"`
105+
}
106+
```
107+
108+
### New Configuration File (if applicable)
109+
110+
[If a new configuration file is needed, describe its format and provide an example.]
111+
112+
```yaml
113+
# Example: /etc/kepler/new-feature.yaml
114+
feature:
115+
key: value
116+
```
117+
118+
### Security Considerations
119+
120+
[Detail the security implications of this enhancement. How are secrets managed? What are the authentication/authorization requirements?]
121+
122+
## Deployment Examples
123+
124+
[Provide examples of how to deploy and use this feature in different environments (e.g., Kubernetes, standalone).]
125+
126+
### Kubernetes Environment
127+
128+
[Show a sample Kubernetes manifest (e.g., DaemonSet, Deployment) with the new configuration.]
129+
130+
### Standalone Deployment
131+
132+
[Provide command-line examples for running the application with the new feature enabled.]
133+
134+
## Testing Strategy
135+
136+
### Test Coverage
137+
138+
[Describe the testing plan. What types of tests will be added (unit, integration, end-to-end)? What is the target code coverage?]
139+
140+
- **Unit Tests**: ...
141+
- **Integration Tests**: ...
142+
- **End-to-End Tests**: ...
143+
144+
### Test Infrastructure
145+
146+
[Describe any new infrastructure or tools required for testing (e.g., simulators, mock servers).]
147+
148+
## Migration and Compatibility
149+
150+
### Backward Compatibility
151+
152+
[Explain how this change affects backward compatibility. Are there any breaking changes? How will they be managed?]
153+
154+
### Migration Path
155+
156+
[Provide a step-by-step guide for users to migrate from the old system to the new one.]
157+
158+
1. **Phase 1**: ...
159+
2. **Phase 2**: ...
160+
3. ...
161+
162+
### Rollback Strategy
163+
164+
[Describe the process for rolling back the change if issues are discovered after deployment.]
165+
166+
## Metrics Output
167+
168+
[List any new or modified Prometheus metrics that will be exposed by this feature.]
169+
170+
```prometheus
171+
# Description of new metric
172+
new_metric_name{label="value"} 123
173+
```
174+
175+
## Implementation Plan
176+
177+
[Break down the implementation into a series of phases or milestones.]
178+
179+
### Phase 1: Foundation
180+
181+
- Task 1...
182+
- Task 2...
183+
184+
### Phase 2: Core Functionality
185+
186+
- Task 1...
187+
- Task 2...
188+
189+
### Phase 3: Testing and Documentation
190+
191+
- Task 1...
192+
- Task 2...
193+
194+
## Risks and Mitigations
195+
196+
[Identify potential risks (technical, operational) and propose mitigation strategies for each.]
197+
198+
### Technical Risks
199+
200+
- **Risk**: ...
201+
- **Mitigation**: ...
202+
203+
### Operational Risks
204+
205+
- **Risk**: ...
206+
- **Mitigation**: ...
207+
208+
## Alternatives Considered
209+
210+
[Describe any alternative solutions that were considered and explain why they were rejected.]
211+
212+
### Alternative 1: [Name of Alternative]
213+
214+
- **Description**: ...
215+
- **Reason for Rejection**: ...
216+
217+
### Alternative 2: [Name of Alternative]
218+
219+
- **Description**: ...
220+
- **Reason for Rejection**: ...
221+
222+
## Success Metrics
223+
224+
[Define the metrics that will be used to measure the success of this enhancement.]
225+
226+
- **Functional Metric**: ...
227+
- **Performance Metric**: ...
228+
- **Adoption Metric**: ...
229+
230+
## Open Questions
231+
232+
[List any open questions or unresolved issues that need to be addressed during implementation.]
233+
234+
1. ...
235+
2. ...

‎docs/developer/proposal/index.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Enhancement Proposals
2+
3+
This directory contains Enhancement Proposals (EPs) for major features and changes to Kepler.
4+
5+
## Active Proposals
6+
7+
| ID | Title | Status | Author | Created |
8+
|----|-------|--------|--------|---------|
9+
| [EP-000](EP_TEMPLATE.md) | Enhancement Proposal Template | Accepted |Sunil Thaha | 2025-01-18 |
10+
11+
## Proposal Status
12+
13+
- **Draft**: Initial proposal under discussion
14+
- **Accepted**: Proposal approved for implementation
15+
- **Implemented**: Feature has been implemented and merged
16+
- **Rejected**: Proposal was not accepted
17+
- **Superseded**: Proposal replaced by a newer one
18+
19+
## Creating a New Proposal
20+
21+
To create a new enhancement proposal:
22+
23+
1. Copy the [EP_TEMPLATE.md](EP_TEMPLATE.md) template
24+
2. Name your file `EP_XXX-short-title.md` where XXX is the next available number
25+
3. Fill out all sections of the template
26+
4. Update this index with your proposal
27+
5. Submit a pull request for review
28+
29+
## Proposal Template
30+
31+
Use the [EP_TEMPLATE.md](EP_TEMPLATE.md) file as your starting point. The template includes comprehensive sections for:
32+
33+
- **Summary and Problem Statement**: Clear description of the enhancement and motivation
34+
- **Goals and Non-Goals**: Scope definition and boundaries
35+
- **Requirements**: Functional and non-functional requirements
36+
- **Architecture**: Technical design and implementation details
37+
- **Configuration**: New configuration options and deployment examples
38+
- **Testing Strategy**: Comprehensive testing approach
39+
- **Migration**: Backward compatibility and upgrade path
40+
- **Implementation Plan**: Phased development approach with risk mitigation

0 commit comments

Comments
 (0)