enhancements process documentation improvements

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,31 +56,90 @@ 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
 - (optionally) have done a prototype in your own fork
 - 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.

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.