Beef up the feature process doc; add more metadata to the design doc …

…template

FEATURE_PROCESS.adoc

@@ -1,5 +1,112 @@
 = WildFly Feature Development Process
 
+The WildFly Feature Development Process defines the procedure that must be followed during the _development_ of features that appear in any of the following:
+
+* The standard WildFly distribution.
+* The WildFly quickstarts.
+* The WildFly Docker and OpenShift images.
+* Standard end-user tooling documented for use with standard WildFly.
+* WildFly Preview, if the feature is at `community` stability or higher.
+* Feature packs that WildFly Glow suggests to users. (WildFly Glow may introduce the concept of "incubating" feature packs that users can opt into having Glow suggest. Development of such feature packs need not follow this process, but they *must not* provide features at `community` or higher stability).
+
+This process should be followed once a developer anticipates beginning work on a feature in the next three months.
+
+NOTE: Requesting new features or recording ideas for new features are *not* part of this process. Feature requests are handled by simply filing an issue in the relevant project JIRA, typically https://issues.redhat.com/projects/WFLY/summary[WFLY].
+
+== The Process
+
+Feature development proceeds in five stages:
+
+=== Kickoff
+
+When a developer intends to begin work on a feature they should do the following:
+
+* If one doesn't already exist, file an issue in the relevant project JIRA, typically https://issues.redhat.com/projects/WFLY/summary[WFLY], https://issues.redhat.com/projects/WFCORE/summary[WFCORE] or https://issues.redhat.com/projects/HAL/summary[HAL]. These issues are important as they allow users and developers to see follow what has happened in a particular code base.
+* [[planning_issue]]File an issue with the https://github.com/orgs/wildfly/projects/7[WildFly Feature Planning project]. To do this create an issue using the https://github.com/wildfly/wildfly-proposals/issues/new?assignees=&labels=feature&projects=wildfly%2F7&template=feature-development.yaml[Feature Development issue template]. This issue is important because:
+** It is what allows effective coordination of overall feature development for a WildFly release from a single, publicly visible, point.
+** It allows users to see an overall roadmap for WildFly features.
+* Draft a minimal feature analysis, based on the current https://github.com/wildfly/wildfly-proposals/blob/main/design-doc-template.adoc[design-doc-template]. This should include the expected stability level, links to the issues above, and enough Overview and User Story information to give people interested in being part of the feature team a sense of what would be involved.
+* Submit a draft analysis PR to the https://github.com/wildfly/wildfly-proposals[`wildfly-proposals`] repository.
+* Send an email to the mailto:wildfly-dev@lists.jboss.org[`wildfly-dev@lists.jboss.org`] mail list telling people about the upcoming work and asking for volunteers to participate in the feature team. (If you don't have a `wildfly-dev` list subscription, visit the https://lists.jboss.org/admin/lists/wildfly-dev.lists.jboss.org/[list subscription page] to create one.)
+
+When the above tasks are complete, change the `Status` field of the WildFly Feature Planning project JIRA to `Planning`.
+
+=== Planning
+
+The `Planning` stage of a feature consists of <<feature-team,feature team>> formation and enough discussion of the feature among the team that they can agree on a target feature stability level and target WildFly release in which they expect to complete the feature.
+
+NOTE: The target WildFly release is just a target and is not a commitment.
+
+Update the feature analysis document with the planned stability level (if it has changed) and the GitHub ids of the feature team members.
+
+If there is an available iteration value that matches the target WildFly release, set the `Iteration` field in the <<planning_issue,WildFly Feature Planning project issue>> to that value.
+
+NOTE: The expectation is there will always be iterations available for the next two WildFly releases. If teams expect to target a later release than that and there's no iteration available, that's ok; just don't set it.
+
+When the above tasks are complete, change the `Status` field of the WildFly Feature Planning project JIRA to `In Progress`.
+
+IMPORTANT: Changes to the `Iteration` field of a WildFly Feature Planning project issue should always reflect the consensus of the feature team.
+
+=== In Progress
+
+The main work on the feature happens in this stage. The feature team works to meet the <<requirements>> that apply to the feature's target stability.
+
+When the team believes all development work on the feature is complete, change the `Status` field of the <<planning_issue,WildFly Feature Planning project issue>> to `Review`.
+
+NOTE: Developers should not move an issue to `Review` status as a means of asking other team members to do routine code review. Such intra-team coordination should be handled in some other way. Moving an issue to `Review` is a signal to WildFly release coordinators that work on the feature is about to conclude.
+
+=== Review
+
+In the Review stage the team formally validates that the <<requirements>> have been met.
+
+This should be a relatively quick stage, as the team should have a belief that the requirements are met before the feature issue is moved to `Review`. The work in this stage should simply be a formal check and signoff.
+
+When the signoff is complete, the feature team should notify the release coordinator for the current WildFly release.
+
+If the formal review reveals issues that will take more than three days to resolve, move the issue back to `In Progress`.
+
+=== Done
+
+The release coordinator moves the issue to `Done` status when all work associated with the feature has been merged.
+
+[[feature-team]]
+== The Feature Team
+
+A feature team consists of people in the following roles:
+
+=== Developer
+
+There is a single person in this role: the primary developer of the feature. Other members of the team may do development work, but the developer plays a leading role.
+
+=== Subject Matter Experts
+
+Multiple people can participate in this role. SMEs are knowledgeable in a technology area impacted by the feature.
+
+All feature teams must have at least one person in the Subject Matter Expert role.
+
+SMEs are expected to review all aspects of the feature analysis, implementation, test and documentation.
+
+=== Outside Perspective
+
+Multiple people can participate in this role. The Outside Perspective role is meant to serve two main purposes:
+
+* Attempt to bring a 'user' perspective to the feature team. The end user of the feature is unlikely to have anything close to the expertise of the Developer or a Subject Matter Expert, so things that seem understandable or intuitive to people in those roles may not be so for an end user.
+* Attempt to avoid 'group think' in the development team. The feature may be being developed in accordance with existing plans by a team that does work in the feature's technical area, with the Developer and a Subject Matter Expert part of that team. There's nothing wrong with this, but it's useful to have someone involved who was not part of creating those plans.
+
+Ideally a person in the Outside Perspective role would not be deeply knowledgeable in the feature's general technical area, although at times only people with some level of knowledge will be available. A person in the Outside Perspective role *must not* be someone who is part of a team that works in the feature's technical area.
+
+A person in the Outside Perspective role is not expected to do deep technical review of the feature implementation or tests. (Of course, they are welcome to do this if they choose.) They should focus on:
+
+* The Overview, User Stories and Requirements sections of the feature analysis.
+* The feature documentation, including any ancillary material like quickstarts or user guides.
+* Any end-user accessible API associated with the feature.
+* For features at `community` stability or above, a person in the Outside Perspective role should perform manual verification of the feature (i.e. try it out).
+
+All feature teams for features at `preview` stability or higher must have at least one person in the Outside Perspective role. Features at `experimental` stability are not required to have anyone in the Outside Perspective role.
+
+[[requirements]]
+== The Requirements
+
 WildFly features can have one of four different maturity levels, “Experimental”, “Preview”, “Community” and an unnamed default level.
 
 Promotion from one level to another, or initial feature incorporation at a given level, requires meeting various standards in the basic areas of requirements analysis, implementation, testing and documentation. The following table outlines the various standards for each of the maturity levels.
@@ -163,3 +270,4 @@ Documentation content as per analysis.
 | Same as Community
 //-------
 |===
+

design-doc-template.adoc

@@ -1,17 +1,33 @@
 ---
-categories:
 # Add any category for this proposal as a yaml list, e.g.
 # - core
 # - management
-# if missing, add it to _data/widfly-categories and use its id
-#
+# if missing, add it to _data/wildfly-categories and use its id
+categories:
 # Specify the stability level of the feature.
 # Values can be one of: experimental preview community default
 stability-level: 
 # Specify the main issue of the feature
 # Most of the time, it will be a issue in https://issues.redhat.com/browse/WFLY
 # or https://issues.redhat.com/browse/WFCORE 
-issue: 
+issue:
+# Provide the github ids of the members of the feature team, organized by role.
+# Provide a single id for the 'assignee' role. Use a yaml list for the 'sme' and
+# 'outside-perspective' roles, even if there is only one person in a role.
+feature-team:
+ developer:
+ sme:
+  -
+ outside-perspective:
+  -
+# If this issue tracks the promotion to a higher stability level of a previously
+# completed feature, provide the URL of the https://github.com/wildfly/wildfly-proposals/issues
+# issue that was used to track the previous feature.
+promotes:
+# This should be blank during initial development of a feature. It may be used
+# after the feature is completed if a subsequent issue is field to track promotion
+# of this feature to a higher stability level
+promoted-by:
 ---
 = <INSERT TITLE HERE>
 :author:            Your Name
@@ -27,6 +43,10 @@ __<The entire document should be one to two pages long. We will write each analy
 
 __<Define the requirement here. Be clear and succinct, you should be able to clearly define the context or problem in two or three paragraphs (if not sentences). Try to define the problem in the overall context and not to get into too much technical detail at this point.>__
 
+=== User Stories
+
+__<Provide one or more brief user stories that illustrate the intended users of
+ the feature and the goal they will seek to achieve by using the feature.>__
 
 == Affected Projects or Components
 
@@ -45,7 +65,22 @@ __<List the installation types thar are relevant for the features and remove any
 
 == Requirements
 
-__<Describe the requirements that must be fullfilled by this feature.>__
+__<Describe the requirements that must be fulfilled by this feature.>__
+
+__<For analyses of a promotion of an existing feature to
+'preview' or 'community' stability, only list new requirements; existing
+ requirements from the feature being promoted are assumed to continue unless
+ otherwise noted in the 'Changed requirements' section. Other analyses, including
+ those for promotion to the 'default' stability level, must list all requirements.>__
+
+=== Changed requirements
+
+__<Only relevant for analyses of a promotion of an existing feature to
+ 'preview' or 'community stability. Other analyses should remove this section.>__
+
+__<For any existing requirements from the feature being promoted that are
+ being changed or removed, describe the change.>__
+
 
 === Non-Requirements