diff --git a/README.md b/README.md index 9e0bab6bfa..65341bf51b 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,17 @@ community, but require consensus from domain specific project maintainers in order to implement and accept into the release. For an overview of the whole project, see [the roadmap](ROADMAP.md). + For a quick-start, FAQ, and template references, see [the guidelines](guidelines/README.md). +## Why are Enhancements Tracked? + +As the project evolves, its important that the OKD community understands how we +build, test, and document our work. Individually it is hard to understand how +all parts of the system interact, but as a community we can lean on each other +to build the right design and approach before getting too deep into an +implementation. + ## Is My Thing an Enhancement? A rough heuristic for an enhancement is anything that: @@ -47,6 +56,11 @@ and ask! ## When to Create a New Enhancement +Enhancements should be related to work to be implemented in the near +future. If you have an idea, but aren't planning to implement it right +away, the conversation should start somewhere else like the mailing +list or Slack. + Create an enhancement here once you: - have circulated your idea to see if there is interest @@ -54,24 +68,78 @@ Create an enhancement here once you: - have identified people who agree to work on and maintain the enhancement - many enhancements will take several releases to complete -## Why are Enhancements Tracked - -As the project evolves, its important that the OKD community understands how we -build, test, and document our work. Individually it is hard to understand how -all parts of the system interact, but as a community we can lean on each other -to build the right design and approach before getting too deep into an -implementation. - -## When to Comment on an Enhancement Issue - -Please comment on the enhancement issue to: -- request a review or clarification on the process -- update status of the enhancement effort -- link to relevant issues in other repos - -Please do not comment on the enhancement issue to: -- discuss a detail of the design, code or docs. Use a linked-to-issue or design PR - for that +## How are Enhancements Reviewed and Approved? + +The author of an enhancement is responsible for managing it through +the review and approval process, including soliciting feedback on the pull request +and in meetings, if necessary. + +Each enhancement should have at least one "approver" and several +reviewers designated in the header of the document. + +The approver assists authors who may not be familiar with the process, +the project, or the maintainers. They may provide advice about who +should review a specific proposal and point out deadlines or other +time-based criteria for completing work. The approver is responsible +for recognizing when consensus among reviewers has been reached so that a proposal is +ready to be approved, or formally rejected. In cases where consensus +is not emerging on its own, the approver may also step in as a +mediator. The approver does not need to be a subject-matter expert for +the subject of the design, although it can help if they are. + +Choosing the appropriate approver depends on the scope of an +enhancement. If it is limited in scope to a given team or component, +then a peer or lead on that team or pillar is appropriate. If an +enhancement captures something more broad in scope, then a member of +the OpenShift staff engineers team or someone they delegate would be +appropriate. Examples of broad scope are proposals that change the +definition of OpenShift in some way, add a new required dependency, or +change the way customers are supported. Use your best judgement to +determine the level of approval needed. If you’re not sure, ask a +staff engineer to help find a good approver by posting in +`#forum-arch` on the CoreOS Slack server and tagging +`@aos-staff-engineers`. + +The set of reviewers for an enhancement proposal can be anyone that +has an interest in this work or the expertise to provide a useful +input/assessment. At a minimum, the reviewers must include a +representative of any team that will need to do work for this EP, or +whose team will own/support the resulting implementation. Be mindful +of the workload of reviewers, however, and the challenge of finding +consensus as the group of reviewers grows larger. Clearly indicating +what aspect of the EP you expect each reviewer to be concerned with +will allow them to focus their reviews. + +## How Can an Author Help Speed Up the Review Process? + +Enhancements should have agreement from all stakeholders prior to +being approved and merged. Reviews are not time-boxed (see Life-cycle +below). We manage the rate of churn in OpenShift by asking component +maintainers to act as reviewers in addition to everything else that +they do. If it is not possible to attract the attention of enough of +the right maintainers to act as reviewers, that is a signal that the +project's rate of change is maxed out. With that said, there are a few +things that authors can do to help keep the conversation moving along. + +1. Respond to comments quickly, so that a reviewer can tell you are + engaged. +2. Push update patches, rather than force-pushing a replacement, to + make it easier for reviewers to see what you have changed. Use + descriptive commit messages on those updates, or plan to use + `/label tide/merge-method-squash` to have them squashed when the + pull request merges. +3. Do not rely solely on the enhancement for visibility of the + proposal. For high priority work, or if the conversation stalls + out, you can start a thread in `#forum-arch` on the CoreOS Slack + server or bring the enhancement to one of the weekly architecture + review meetings for discussion. If you aren't sure which meeting to + use, work with a staff engineer to find a good fit. +4. If the conversation otherwise seems stuck, pinging reviewers on + Slack can be used to remind them to look at updates. It's generally + appropriate to give people at least a business day or two to + respond in the GitHub thread first, before reaching out to them + directly on Slack, so that they can manage their work queue and + disruptions. ## Using Labels @@ -83,7 +151,6 @@ top level release priority. These will be highlighted in the ## Life-cycle - Pull requests to this repository should be short-lived and merged as soon as there is consensus. Therefore, the normal life-cycle timeouts are shorter than for most of our code repositories. @@ -109,14 +176,15 @@ the required sections. If you are working on an enhancement and the linter job fails because of changes to the template (not other issues with the markdown -formatting), handle it based on the maturity of the enhancement PR: +formatting), handle it based on the maturity of the enhancement pull +request: -* If the only reason to update your PR is to make the linter job +* If the only reason to update your pull request is to make the linter job accept it after a template change and there are no substantive content changes needed for approval, override the job to allow the - PR to merge. + pull request to merge. * If your enhancement is still a draft, and consensus hasn't been - reached, modify the PR so the new enhancement matches the updated + reached, modify the pull request so the new enhancement matches the updated template. * If you are updating an existing (merged) document, go ahead and override the job. diff --git a/guidelines/enhancement_template.md b/guidelines/enhancement_template.md index 9e7f524e2c..3c2b53f406 100644 --- a/guidelines/enhancement_template.md +++ b/guidelines/enhancement_template.md @@ -2,7 +2,7 @@ title: neat-enhancement-idea authors: - "@janedoe" -reviewers: +reviewers: # Include a comment about what domain expertise a reviewer is expected to bring. For example, "- @networkguru, for networking aspects" - TBD - "@alicedoe" approvers: @@ -22,38 +22,6 @@ superseded-by: - "/enhancements/our-past-effort.md" --- -Start by filling out this header template with metadata for this enhancement. - -* Enhancements should be related to work to be implemented in the near future. - -* Enhancements should have agreement from all stakeholders prior to merging. - -* `reviewers`: This can be anyone that has an interest in this work or the expertise - to provide a useful input/assessment. At a minimum it should include the lead for - any team that will need to do work for this EP, or whose team will own/support the - resulting implementation. Please indicate what aspect of the EP you expect them - to be concerned with so they do not always need to review the entire EP in depth. - -* `approvers`: All enhancements must be approved, but the appropriate people to - approve a given enhancement depends on its scope. If an enhancement is - limited in scope to a given team or component, then a peer or lead on that - team or pillar is an appropriate approver. If an enhancement captures - something more broad in scope, then a member of the OpenShift staff engineers team - or someone they delegate would be appropriate. Examples would be something - that changes the definition of OpenShift in some way, adds a new required - dependency, or changes the way customers are supported. Use your best - judgement to determine the level of approval needed. If you’re not sure, - just leave it blank and ask for input during review. - -# Neat Enhancement Idea - -This is the title of the enhancement. Keep it simple and descriptive. A good -title can help communicate what the enhancement is and should be considered as -part of any review. - -The YAML `title` should be lowercased and spaces/punctuation should be -replaced with `-`. - 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 @@ -77,6 +45,19 @@ To get started with this template: enhancement, explain why but do not remove the section. This part of the process is enforced by the linter CI job. +See ../README.md for background behind these instructions. + +Start by filling out the header with the metadata for this enhancement. + +# Neat Enhancement Idea + +This is the title of the enhancement. Keep it simple and descriptive. A good +title can help communicate what the enhancement is and should be considered as +part of any review. + +The YAML `title` should be lowercased and spaces/punctuation should be +replaced with `-`. + The `Metadata` section above is intended to support the creation of tooling around the enhancement process. @@ -88,7 +69,8 @@ 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 probably at least a paragraph in length. +A good summary is no more than one paragraph in length. More detail +should go into the following sections. ## Motivation @@ -97,16 +79,27 @@ this proposal. Describe why the change is important and the benefits to users. ### Goals -List the specific goals of the proposal. How will we know that this has succeeded? +Summarize the specific goals of the proposal. How will we know that +this has succeeded? A good goal describes something a user wants from +their perspective, and does not include the implementation details +from the proposal. ### Non-Goals -What is out of scope for this proposal? Listing non-goals helps to focus discussion -and make progress. +What is out of scope for this proposal? Listing non-goals helps to +focus discussion and make progress. Highlight anything that is being +deferred to a later phase of implementation that may call for its own +enhancement. ## Proposal -This is where we get down to the nitty gritty of what the proposal actually is. +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 +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. ### User Stories @@ -120,7 +113,7 @@ Include a story on how this proposal will be operationalized: lifecycled, monit ### API Extensions API Extensions are CRDs, admission and conversion webhooks, aggregated API servers, -finalizers, i.e. those mechanisms that change the OCP API surface and behaviour. +and finalizers, i.e. those mechanisms that change the OCP API surface and behaviour. - Name the API extensions this enhancement adds or modifies. - Does this enhancement modify the behaviour of existing resources, especially those owned @@ -147,7 +140,9 @@ What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger OKD ecosystem. -How will security be reviewed and by whom? How will UX be reviewed and by whom? +How will security be reviewed and by whom? + +How will UX be reviewed and by whom? Consider including folks that also work outside your immediate sub-project.