Skip to content

Commit eeb37af

Browse files
mandremandre
authored
Merge pull request #662 from shiftstack/enhancement-template
Add lightweight enhancement proposal process
2 parents 83b8a0b + 49ad3f2 commit eeb37af

6 files changed

Lines changed: 220 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/feature_request.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ body:
66
attributes:
77
value: |
88
Thanks for taking the time to fill out this feature request!
9+
10+
**Note:** For significant new features or architectural changes, consider writing an
11+
[enhancement proposal](https://github.com/k-orc/openstack-resource-controller/tree/main/enhancements)
12+
instead of or in addition to this issue.
913
- type: textarea
1014
id: request
1115
attributes:

‎.github/labels.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,6 @@
2626
- color: 'C2E0C6'
2727
description: Documentation
2828
name: docs
29+
- color: 'A2EEEF'
30+
description: Enhancement proposal
31+
name: enhancement

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ We welcome contributions of all kinds! Whether you’re fixing bugs, adding new
3434
* Make your changes and test thoroughly.
3535
* Submit a pull request with a clear description of your changes.
3636

37+
For significant new features or architectural changes, please review our
38+
[enhancement proposal process](enhancements/README.md) before starting work.
39+
3740
If you're unsure where to start, check out the [open issues](https://github.com/k-orc/openstack-resource-controller/issues) and feel free to ask
3841
questions or propose ideas!
3942

‎enhancements/README.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# ORC Enhancement Process
2+
3+
This document describes the process for proposing significant changes to ORC.
4+
The process is intentionally lightweight, inspired by the [Kubernetes
5+
Enhancement Proposal (KEP)][kep] process but tailored to ORC's scope and
6+
community size.
7+
8+
[kep]: https://github.com/kubernetes/enhancements/tree/master/keps
9+
10+
## When to Write an Enhancement
11+
12+
Write an enhancement proposal when you want to:
13+
14+
- Add a significant new feature or capability
15+
- Make breaking changes to existing APIs
16+
- Deprecate or remove functionality
17+
- Make cross-cutting architectural changes
18+
- Change behavior that users depend on
19+
20+
You do **not** need an enhancement for:
21+
22+
- Bug fixes
23+
- Small improvements or refactoring
24+
- Documentation updates
25+
- Adding support for additional OpenStack resource fields
26+
- Test improvements
27+
28+
When in doubt, open a GitHub issue first to discuss whether an enhancement
29+
proposal is needed.
30+
31+
## Enhancement Lifecycle
32+
33+
Enhancements move through the following statuses:
34+
35+
| Status | Description |
36+
|--------|-------------|
37+
| `implementable` | The enhancement has been approved and is ready for implementation. |
38+
| `implemented` | The enhancement has been fully implemented and merged. |
39+
| `withdrawn` | The enhancement is no longer being pursued. |
40+
41+
## How to Submit an Enhancement
42+
43+
1. **Copy the template** from [TEMPLATE.md](TEMPLATE.md) to a new file named
44+
after your feature:
45+
```
46+
enhancements/your-feature-name.md
47+
```
48+
49+
If your enhancement requires supporting files (images, diagrams), create a
50+
directory instead:
51+
```
52+
enhancements/your-feature-name/
53+
├── your-feature-name.md
54+
└── diagram.png
55+
```
56+
57+
2. **Fill out the template** with your proposal details.
58+
59+
3. **Open a pull request** with your enhancement proposal. Use a descriptive
60+
title like: `Enhancement: Add support for feature X`
61+
62+
4. **Iterate based on feedback**. Discussion happens on the PR.
63+
64+
5. **Create a tracking issue** once the enhancement is merged. Label the issue
65+
with `enhancement` and link it in your enhancement's metadata table.
66+
67+
## Review Process
68+
69+
- Any community member can propose an enhancement
70+
- Maintainers review proposals and provide feedback on the PR
71+
- Enhancements are approved using lazy consensus: if no maintainer has objected
72+
after a reasonable review period (typically one week), the enhancement can be
73+
merged
74+
- The enhancement author is typically expected to drive implementation, though
75+
others may volunteer
76+
77+
## Directory Structure
78+
79+
```
80+
enhancements/
81+
├── README.md # This document
82+
├── TEMPLATE.md # Template for new enhancements
83+
├── your-feature-name.md # Simple enhancement (single file)
84+
└── complex-feature/ # Enhancement with supporting files
85+
├── complex-feature.md
86+
└── architecture.png
87+
```
88+
89+
## Tips for Writing Good Enhancements
90+
91+
1. **Be concise but complete**. Include enough detail for reviewers to
92+
understand the proposal without unnecessary verbosity.
93+
94+
2. **Focus on the "why"**. Motivation is often more important than
95+
implementation details.
96+
97+
3. **Think about edge cases**. The Risks and Edge Cases section is where you
98+
demonstrate you've thought through the implications.
99+
100+
4. **Consider alternatives**. Showing that you've evaluated other approaches
101+
strengthens your proposal.
102+
103+
5. **Keep it updated**. As implementation progresses, update the Implementation
104+
History section.

‎enhancements/TEMPLATE.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Enhancement: Your Feature Title
2+
3+
<!--
4+
Instructions:
5+
1. Copy this file to: enhancements/your-feature-name.md
6+
(or enhancements/your-feature-name/your-feature-name.md if you need supporting files)
7+
2. Fill in the metadata table below
8+
3. Complete each section (remove the HTML comments when done)
9+
4. Open a PR for review
10+
-->
11+
12+
| Field | Value |
13+
|-------|-------|
14+
| **Status** | implementable |
15+
| **Author(s)** | @your-github-username |
16+
| **Created** | YYYY-MM-DD |
17+
| **Last Updated** | YYYY-MM-DD |
18+
| **Tracking Issue** | TBD |
19+
20+
## Summary
21+
22+
<!--
23+
Provide a 1-2 paragraph overview of your enhancement. This should be
24+
understandable by someone who hasn't read the rest of the document.
25+
What are you proposing and what will it enable?
26+
-->
27+
28+
## Motivation
29+
30+
<!--
31+
Why is this change needed? What problem does it solve? Who is affected?
32+
Include links to issues, discussions, or user feedback that motivated this
33+
proposal if available.
34+
-->
35+
36+
## Goals
37+
38+
<!--
39+
List the specific objectives of this enhancement. What will be true when
40+
this is complete? Be specific and measurable where possible.
41+
42+
- Goal 1
43+
- Goal 2
44+
-->
45+
46+
## Non-Goals
47+
48+
<!--
49+
What is explicitly out of scope for this enhancement? Listing non-goals helps
50+
focus discussion and prevents scope creep.
51+
52+
- Non-goal 1
53+
- Non-goal 2
54+
-->
55+
56+
## Proposal
57+
58+
<!--
59+
Describe your proposed solution in detail. This should include:
60+
61+
- How the feature will work from a user's perspective
62+
- Any new APIs, fields, or resources being introduced
63+
- How it integrates with existing functionality
64+
65+
Include code examples, API snippets, or diagrams where helpful.
66+
-->
67+
68+
## Risks and Edge Cases
69+
70+
<!--
71+
Think critically about what could go wrong or what corner cases exist.
72+
Consider:
73+
74+
- API compatibility: Will this break existing users?
75+
- Security: Are there any security implications?
76+
- Performance: Could this impact controller performance at scale?
77+
- Error handling: What happens when things fail?
78+
- Upgrade/downgrade: How does this affect users upgrading or downgrading ORC?
79+
- OpenStack compatibility: Does this work across different OpenStack versions?
80+
- Interaction with other features: Could this conflict with existing behavior?
81+
82+
For each risk identified, describe how it will be mitigated.
83+
-->
84+
85+
## Alternatives Considered
86+
87+
<!--
88+
What other approaches did you consider? Why were they rejected?
89+
This demonstrates due diligence and helps reviewers understand the design space.
90+
-->
91+
92+
## Implementation History
93+
94+
<!--
95+
Track major milestones here. Keep it lightweight.
96+
97+
- YYYY-MM-DD: Enhancement proposed
98+
- YYYY-MM-DD: Implementation started
99+
- YYYY-MM-DD: Implemented in vX.Y.Z
100+
-->
101+
102+
- YYYY-MM-DD: Enhancement proposed

‎website/docs/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,10 @@ We welcome contributions of all kinds! Whether you're fixing bugs, adding new fe
7676
* Make your changes and test thoroughly.
7777
* Submit a pull request with a clear description of your changes.
7878

79+
For significant new features or architectural changes, please review our
80+
[enhancement proposal process](https://github.com/k-orc/openstack-resource-controller/tree/main/enhancements)
81+
before starting work.
82+
7983
If you're unsure where to start, check out the [open issues](https://github.com/k-orc/openstack-resource-controller/issues) and feel free to ask
8084
questions or propose ideas!
8185

0 commit comments

Comments
 (0)