| name | proposal |
| description | Write an enhancement proposal for a new ORC feature. Use for significant new features, breaking changes, or cross-cutting architectural changes. |
| disable-model-invocation | true |
Write Feature Proposal
Guide for creating a proposal for a new feature or enhancement in ORC.
When to Write an Enhancement
Write an enhancement proposal when you want to:
- Add a significant new feature or capability
- Make breaking changes to existing APIs
- Deprecate or remove functionality
- Make cross-cutting architectural changes
- Change behavior that users depend on
You do not need an enhancement for:
- Bug fixes
- Small improvements or refactoring
- Documentation updates
- Adding support for additional OpenStack resource fields
- Test improvements
When in doubt, suggest opening a GitHub issue first to discuss whether an enhancement proposal is needed.
Enhancement Lifecycle
Enhancements move through the following statuses:
| Status | Description |
|---|
implementable | The enhancement has been approved and is ready for implementation |
implemented | The enhancement has been fully implemented and merged |
withdrawn | The enhancement is no longer being pursued |
Template and File Location
Use the enhancement template at enhancements/TEMPLATE.md.
For full process details, see enhancements/README.md.
Creating the Proposal File
Simple enhancement (single file):
cp enhancements/TEMPLATE.md enhancements/your-feature-name.md
Enhancement with supporting files (images, diagrams):
mkdir enhancements/your-feature-name
cp enhancements/TEMPLATE.md enhancements/your-feature-name/your-feature-name.md
Information to Gather from User
Before writing a proposal, ask the user about:
-
Feature Overview
- What OpenStack resource or capability does this involve?
- What problem does this solve for users?
- Is this a new controller, enhancement to existing controller, or infrastructure change?
-
Use Cases
- Who will use this feature? (end users, operators, other controllers)
- What are the primary use cases?
- Are there edge cases to consider?
-
Dependencies
- Does this depend on other ORC resources?
- Does this require new OpenStack API capabilities?
- Are there upstream dependencies (gophercloud, controller-runtime)?
-
Scope
- Is this a minimal viable feature or full implementation?
- Are there phases or milestones to break this into?
- What's explicitly out of scope?
-
Testing
- How is this going to be tested?
- Are there specific E2E test scenarios required?
- What OpenStack capabilities are needed for testing?
-
Existing Infrastructure (for non-controller enhancements)
- What related functionality already exists in ORC?
- Are there existing endpoints, ports, or configurations to integrate with?
- What frameworks/libraries does ORC already use for this area?
Research Phase
Before writing the proposal, research the relevant area:
- OpenStack API & gophercloud: Read the API docs, check gophercloud support, note async operations
- Existing ORC patterns: Look at similar controllers or infrastructure code for patterns to follow
- Dependencies: Map ORC resource dependencies (required vs optional, deletion guards)
- Current implementation: For infrastructure enhancements, read the actual code to verify technical details (ports, endpoints, framework capabilities)
Filling Out the Template
Read the template at enhancements/TEMPLATE.md and fill in each section:
| Section | What to Include |
|---|
| Metadata table | Status (implementable), author, dates, tracking issue (TBD initially) |
| Summary | 1-2 paragraph overview of the enhancement |
| Motivation | Why this is needed, who benefits, links to issues |
| Goals | Specific, measurable objectives |
| Non-Goals | What's explicitly out of scope |
| Proposal | Detailed solution with API examples |
| Risks and Edge Cases | What could go wrong, mitigations (see risk checklist below) |
| Alternatives Considered | Other approaches and why rejected |
| Implementation History | Timeline of major milestones |
For New Controller Proposals
Note: New controllers following existing patterns typically don't need an enhancement proposal. Only write a proposal if the controller requires new patterns or architectural changes.
If a proposal is needed, in the Proposal section, include:
apiVersion: openstack.k-orc.cloud/v1alpha1
kind: ResourceName
metadata:
name: example
spec:
cloudCredentialsRef:
secretName: openstack-credentials
cloudName: openstack
resource:
import:
filter:
status:
id: "uuid"
conditions: [...]
resource:
Also describe:
- Controller behavior (creation, updates, deletion)
- Dependencies (required vs optional, deletion guards)
- Mutable vs immutable fields
Risk Checklist
Address each of these in the Risks and Edge Cases section:
| Risk Category | Questions to Answer |
|---|
| API compatibility | Will this break existing users? Are metric/label names stable? |
| Security | Are there security implications? (Often N/A for read-only features) |
| Performance | Could this impact controller performance at scale? |
| Error handling | What happens when things fail? |
| Upgrade/downgrade | How does this affect users upgrading or downgrading ORC? |
| OpenStack compatibility | Does this work across different OpenStack versions? (N/A for K8s-only) |
| Interaction with existing features | Could this conflict with existing behavior? |
Before Submitting
Verify internal consistency (anything referenced in one section is defined elsewhere), technical accuracy (check against actual code), and that examples are complete.
Submission Process
- Fill out the template with proposal details
- Open a pull request with title:
Enhancement: Add support for feature X
- Iterate based on feedback - Discussion happens on the PR
- Create a tracking issue once merged - Label with
enhancement and link in metadata
Review Process
- Any community member can propose an enhancement
- Maintainers review proposals and provide feedback on the PR
- Enhancements are approved using lazy consensus (typically one week review period)
- The enhancement author is typically expected to drive implementation
Checklist
