From 627d2e56dcbab0a9126cd74c22e4a4bc9c04f1b3 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 2 Feb 2024 15:46:13 -0500 Subject: [PATCH 1/7] add step about filling in the metadata section at the top of the file --- guidelines/enhancement_template.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index 2f3e406029..a02c721331 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -24,6 +24,8 @@ To get started with this template: 1. **Pick a domain.** Find the appropriate domain to discuss your enhancement. 1. **Make a copy of this template.** Copy this template into the directory for the domain. +1. **Fill out the metadata at the top.** The embedded YAML document is + checked by the linter. 1. **Fill out the "overview" sections.** This includes the Summary and Motivation sections. These should be easy and explain why the community should desire this enhancement. From f1794ddadc6523ecfeab69be57524fa785be5420 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 2 Feb 2024 15:47:09 -0500 Subject: [PATCH 2/7] be more explicit about looking for details for our different product topologies --- guidelines/enhancement_template.md | 40 ++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index a02c721331..b984e22d3b 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -172,13 +172,6 @@ deploying an application in a cluster. applications, and gives the application administrator their credentials. -#### Variation and form factor considerations [optional] - -How does this proposal intersect with Standalone OCP, Microshift and Hypershift? - -If the cluster creator uses a standing desk, in step 1 above they can -stand instead of sitting down. - See https://github.com/openshift/enhancements/blob/master/enhancements/workload-partitioning/management-workload-partitioning.md#high-level-end-to-end-workflow and https://github.com/openshift/enhancements/blob/master/enhancements/agent-installer/automated-workflow-for-agent-based-installer.md for more detailed examples. @@ -201,17 +194,38 @@ and finalizers, i.e. those mechanisms that change the OCP API surface and behavi Fill in the operational impact of these API Extensions in the "Operational Aspects of API Extensions" section. -### Implementation Details/Notes/Constraints [optional] +### Topology Considerations -What are the caveats to the implementation? What are some important details that -didn't come across above. Go in to as much detail as necessary here. This might -be a good place to talk about core concepts and how they relate. +#### Hypershift / Hosted Control Planes -#### Hypershift [optional] +Are there any unique considerations for making this change work with +Hypershift? -Does the design and implementation require specific details to account for the Hypershift use case? See https://github.com/openshift/enhancements/blob/e044f84e9b2bafa600e6c24e35d226463c2308a5/enhancements/multi-arch/heterogeneous-architecture-clusters.md?plain=1#L282 +How does it affect any of the components running in the +management cluster? How does it affect any components running split +between the management cluster and guest cluster? + +#### Standalone Clusters + +Is the change relevant for standalone clusters? + +#### Single-node Deployments or MicroShift + +How does this proposal affect the resource consumption of a +single-node OpenShift deployment (SNO), CPU and memory? + +How does this proposal affect MicroShift? For example, if the proposal +adds configuration options through API resources, should any of those +behaviors also be exposed to MicroShift admins through the +configuration file for MicroShift? + +### Implementation Details/Notes/Constraints + +What are some important details that didn't come across above in the +**Proposal**? Go in to as much detail as necessary here. This might be +a good place to talk about core concepts and how they relate. ### Risks and Mitigations From dfe364d2ec66ff34868ffbf69f1104920c4dd7be Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 2 Feb 2024 15:48:43 -0500 Subject: [PATCH 3/7] implementation history is tracked in jira now --- guidelines/enhancement_template.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index b984e22d3b..d0ab072128 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -477,11 +477,6 @@ Describe how to - Namespaces deletion will not delete all objects in etcd, leading to zombie objects when another namespace with the same name is created. -## Implementation History - -Major milestones in the life cycle of a proposal should be tracked in `Implementation -History`. - ## Alternatives Similar to the `Drawbacks` section the `Alternatives` section is used to From ab8cab779c66ad9c2bc9877fcd1d7ab2dd201de8 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 2 Feb 2024 15:50:24 -0500 Subject: [PATCH 4/7] update the outline levels for some sections --- guidelines/enhancement_template.md | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index d0ab072128..30b9fc1c88 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -252,17 +252,14 @@ Does this proposal implement a behavior that's new/unique/novel? Is it poorly aligned with existing user expectations? Will it be a significant maintenance burden? Is it likely to be superceded by something else in the near future? - -## Design Details - -### Open Questions [optional] +## Open Questions [optional] This is where to call out areas of the design that require closure before deciding to implement the design. For instance, > 1. This requires exposing previously private resources which contain sensitive information. Can we do this? -### Test Plan +## Test Plan **Note:** *Section not required until targeted at a release.* @@ -278,7 +275,7 @@ challenging to test should be called out. All code is expected to have adequate tests (eventually with coverage expectations). -### Graduation Criteria +## Graduation Criteria **Note:** *Section not required until targeted at a release.* @@ -310,7 +307,7 @@ please be sure to include in the graduation criteria.** **Examples**: These are generalized examples to consider, in addition to the aforementioned [maturity levels][maturity-levels]. -#### Dev Preview -> Tech Preview +### Dev Preview -> Tech Preview - Ability to utilize the enhancement end to end - End user documentation, relative API stability @@ -319,7 +316,7 @@ to the aforementioned [maturity levels][maturity-levels]. - Enumerate service level indicators (SLIs), expose SLIs as metrics - Write symptoms-based alerts for the component(s) -#### Tech Preview -> GA +### Tech Preview -> GA - More testing (upgrade, downgrade, scale) - Sufficient time for feedback @@ -332,12 +329,12 @@ to the aforementioned [maturity levels][maturity-levels]. **For non-optional features moving to GA, the graduation criteria must include end to end tests.** -#### Removing a deprecated feature +### Removing a deprecated feature - Announce deprecation and support policy of the existing feature - Deprecate the feature -### Upgrade / Downgrade Strategy +## Upgrade / Downgrade Strategy If applicable, how will the component be upgraded and downgraded? Make sure this is in the test plan. @@ -378,7 +375,7 @@ Downgrade expectations: CVO does not currently delete resources that no longer exist in the target version. -### Version Skew Strategy +## Version Skew Strategy How will the component handle version skew with other components? What are the guarantees? Make sure this is in the test plan. @@ -392,7 +389,7 @@ enhancement: - Will any other components on the node change? For example, changes to CSI, CRI or CNI may require updating that component before the kubelet. -### Operational Aspects of API Extensions +## Operational Aspects of API Extensions Describe the impact of API extensions (mentioned in the proposal section, i.e. CRDs, admission and conversion webhooks, aggregated API servers, finalizers) here in detail, @@ -421,8 +418,6 @@ especially how they impact the OCP system architecture and operational aspects. automatically in CI) and by whom (e.g. perf team; name the responsible person and let them review this enhancement) -#### Failure Modes - - Describe the possible failure modes of the API extensions. - Describe how a failure or behaviour of the extension will impact the overall cluster health (e.g. which kube-controller-manager functionality will stop working), especially regarding @@ -430,7 +425,7 @@ especially how they impact the OCP system architecture and operational aspects. - Describe which OCP teams are likely to be called upon in case of escalation with one of the failure modes and add them as reviewers to this enhancement. -#### Support Procedures +## Support Procedures Describe how to - detect the failure modes in a support situation, describe possible symptoms (events, metrics, From 6e39ad5ad775136c4a782e8c22c5ae5beabe6838 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 2 Feb 2024 15:50:52 -0500 Subject: [PATCH 5/7] wording and whitespace changes --- guidelines/enhancement_template.md | 53 ++++++++++++++++-------------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index 30b9fc1c88..b6aef36e7f 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -58,13 +58,13 @@ around the enhancement process. ## Summary -The `Summary` section is incredibly important for producing high quality +The `Summary` section is important for producing high quality user-focused documentation such as release notes or a development roadmap. It should be possible to collect this information before implementation begins in order to avoid requiring implementors to split their attention between writing release notes and implementing the feature itself. -A good summary is no more than one paragraph in length. More detail +Your summary should be one paragraph long. More detail should go into the following sections. ## Motivation @@ -90,12 +90,15 @@ implementation details. Here are some example user stories to show what they might look like: -* As an OpenShift engineer, I want to write an enhancement, so that I can get feedback on my design and -build consensus about the approach to take before starting the implementation. -* As a product manager, I want to review this enhancement proposal, so that I can make sure the customer -requirements are met by the design. -* As an administrator, I want a one-click OpenShift installer, so that I can easily set up a new cluster -without having to follow a long set of operations. +* As an OpenShift engineer, I want to write an enhancement, so that I + can get feedback on my design and build consensus about the approach + to take before starting the implementation. +* As a product manager, I want to review this enhancement proposal, so + that I can make sure the customer requirements are met by the + design. +* As an administrator, I want a one-click OpenShift installer, so that + I can easily set up a new cluster without having to follow a long + set of operations. In each example, the persona's goal is clear, and the goal is clearly provided by the capability being described. @@ -108,7 +111,7 @@ reducing the install to a single click simplifies that process. Here are some real examples from previous enhancements: * [As a member of OpenShift concerned with the release process (TRT, dev, staff engineer, maybe even PM), -I want to opt in to pre-release features so that I can run periodic testing in CI and obtain a signal of +I want to opt in to pre-release features so that I can run periodic testing in CI and obtain a signal of feature quality.](https://github.com/openshift/enhancements/blob/master/enhancements/installer/feature-sets.md#user-stories) * [As a cloud-provider affiliated engineer / platform integrator / RH partner I want to have a mechanism to signal OpenShift's built-in operators about additional @@ -137,13 +140,17 @@ enhancement. ## Proposal -This is where we get down to the nitty gritty of what the proposal -actually is. Describe clearly what will be changed, including all of -the components that need to be modified and how they will be +This section should explain what the proposal actually is. Enumerate +*all* of the proposed changes at a *high level*, including all of the +components that need to be modified and how they will be different. Include the reason for each choice in the design and -implementation that is proposed here, and expand on reasons for not -choosing alternatives in the Alternatives section at the end of the -document. +implementation that is proposed here. + +To keep this section succinct, document the details like API field +changes, new images, and other implementation details in the +**Implementation Details** section and record the reasons for not +choosing alternatives in the **Alternatives** section at the end of +the document. ### Workflow Description @@ -242,11 +249,11 @@ Consider including folks that also work outside your immediate sub-project. ### Drawbacks The idea is to find the best form of an argument why this enhancement should -_not_ be implemented. +_not_ be implemented. -What trade-offs (technical/efficiency cost, user experience, flexibility, +What trade-offs (technical/efficiency cost, user experience, flexibility, supportability, etc) must be made in order to implement this? What are the reasons -we might not want to undertake this proposal, and how do we overcome them? +we might not want to undertake this proposal, and how do we overcome them? Does this proposal implement a behavior that's new/unique/novel? Is it poorly aligned with existing user expectations? Will it be a significant maintenance @@ -474,14 +481,12 @@ Describe how to ## Alternatives -Similar to the `Drawbacks` section the `Alternatives` section is used to -highlight and record other possible approaches to delivering the value proposed -by an enhancement. +Similar to the `Drawbacks` section the `Alternatives` section is used +to highlight and record other possible approaches to delivering the +value proposed by an enhancement, including especially information +about why the alternative was not selected. ## Infrastructure Needed [optional] Use this section if you need things from the project. Examples include a new subproject, repos requested, github details, and/or testing infrastructure. - -Listing these here allows the community to get the process for these resources -started right away. From 9ab562ba60e702c5b11247e0629a0d2a10406bd6 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 2 Feb 2024 17:00:36 -0500 Subject: [PATCH 6/7] add another example user story --- guidelines/enhancement_template.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index b6aef36e7f..48269d9a4b 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -93,6 +93,10 @@ Here are some example user stories to show what they might look like: * As an OpenShift engineer, I want to write an enhancement, so that I can get feedback on my design and build consensus about the approach to take before starting the implementation. +* As an OpenShift engineer, I want to understand the rationale behind + a particular feature's design and alternatives considered, so I can + work on a new enhancement in that problem space knowing the history + of the current design better. * As a product manager, I want to review this enhancement proposal, so that I can make sure the customer requirements are met by the design. From da6500436b19e70f44834aff1b01f578b130862f Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Tue, 6 Feb 2024 14:17:00 -0500 Subject: [PATCH 7/7] clarify template suggestion about implementation details Co-authored-by: Aravindh Puthiyaparambil --- guidelines/enhancement_template.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index 48269d9a4b..dfe578aed1 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -236,7 +236,9 @@ configuration file for MicroShift? What are some important details that didn't come across above in the **Proposal**? Go in to as much detail as necessary here. This might be -a good place to talk about core concepts and how they relate. +a good place to talk about core concepts and how they relate. While it is useful +to go into the details of the code changes required, it is not necessary to show +how the code will be rewritten in the enhancement. ### Risks and Mitigations