Feature process #613
Feature process #613
Conversation
* Update the template to move the tracking issue and the stability level to the front matter * When a PR is open, check that these fields are valid * Generate a HTML page for the proposal with these fields. Signed-off-by: Jeff Mesnil <jmesnil@redhat.com>
Based on the value of the `stability-level` field in the front matter, add a label `stability-level/xxx` to the PR. Signed-off-by: Jeff Mesnil <jmesnil@redhat.com>
|
I read the draft and got doubts about how this will collide with the current process for "default" stability level. There is no mention of any subtle distinction for this stability level, so I am not sure if finally, the intention would be whether to merge the requirements described here with the current ones we follow driving features in "default" stability level. For example, when we are developing a feature directly to "default" stability level, what sort of rules should we follow? The current rules we follow filling and completing an EAP7? the current rules described in this document? both rules? Maybe this could be more clear in this draft. |
|
@yersan This is a WildFly feature process. How EAP chooses to deal with its own internal requirements is not relevant to this document. If Red Hat asks its employees to do additional things when developing features that will appear in EAP, it's up to Red Hat to document those in its own internal policies. It's certainly likely that there may be redundant tasks, but this is a pretty lightweight process so I don't think there will be much. If there's anything in here that conflicts with how you expect things to work when you develop features for inclusion in EAP, please note those things. I, of course, am familiar with EAP's processes and I don't think there is a conflict, but I may have missed something. |
|
One thing that's in here (in the proposed template change) that relates to input from folks focused on EAP is some of the language around requirements, where for promotion to preview or community we only ask for changes but for promotion to default we ask for the complete set. This relates to then general process concept where for default stability we ask that the feature team involves people with specialized QE and docs expertise. Those folks may not have been involved with the feature when it was introduced at lower stability levels. In practice those folks will typically work for Red Hat on EAP. We got feedback that those folks don't want to have to piece together requirements etc by pulling content from previous analyses; they want it all in one document. That seems reasonable. For promotions to preview and community I opted for allowing something lighter that focused on what's new or changed. |
FEATURE_PROCESS.adoc
Outdated
| * 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]. | ||
| * 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 `wildfly-dev` mail list telling people about the upcoming work and asking for volunteers to participate in the feature team. |
There was a problem hiding this comment.
IMO the wildfly-dev list should be the full address, I am not sure if non subscribers can post so if not maybe we should also point to sign up information here.
There was a problem hiding this comment.
+1 to the full mail address. I was too lazy to look it up when I drafted this. I'll add the sign up link.
There was a problem hiding this comment.
A very minor point under your discretion. Could we also add an email subject format here? It could be useful to anyone who wants to filter and classify these message using the email client.
Following what has been sent in the past, the subject could be:
"Feature Team Formation - [stability level] [Jira issue] Short description"
There was a problem hiding this comment.
If we want something to be in a specific form maybe it could be a part of automation on issue creation to send the initial message?
There was a problem hiding this comment.
If we do anything like this, let's use automation. I'd like to keep this as free of small details as possible so people might actually read it. :)
Also, these emails are good candidates for starting threads for continued discussion of the feature itself and not just the process.
FEATURE_PROCESS.adoc
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
Is it also worth some comment that we only plan to have iterations for releases N and N+1 so if a feature is a longer running activity they may not be able to set the iteration?
Also do we consider iteration an "exit criteria" for this stage or useful info?
There was a problem hiding this comment.
Re the iteration I'll reword such that they should set the iteration if there is an iteration available that matches the team's expected timing. That leaves it up to us to create iterations, and its not the problem of teams if we haven't created enough. That leaves the opening for teams to move beyond planning without discussing this or without bothering to record their decision, but TBH I'm not in favor of micromanaging.
FEATURE_PROCESS.adoc
Outdated
|
|
||
| When the team believes all development work on the feature is complete, change the `Status` field of the WildFly Feature Planning project JIRA 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. |
There was a problem hiding this comment.
I think needing a note to say review is not a mechanism to request review is probably a sign we could maybe use a better name here.
There was a problem hiding this comment.
@jamezp what did you think?
There was a problem hiding this comment.
I think I agree @darranl. Possibly what it should be is "Awaiting Merge".
I could see some potential keeping Review to indicate to the merges that progress as been made, and PR's are simply waiting for approval. That said, In Progress really could mean the same thing.
There was a problem hiding this comment.
In a discussion today we agreed to drop the 'Review/Signoff' content until their is some sort of automation in place to support it, i.e. adding a stability-specific checklist to the issue description that the feature team would check off. And it would probably make more sense to do that addition when the issue moves to In Progress.
We also agreed to add a 'Ready for Merge' status, to which the feature team should move the issue once all requirements have been met. We discussed some automation around that (i.e. team checks off requirements and automation moves it when done), but that's for the future.
FEATURE_PROCESS.adoc
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
I wonder if that could be the time to use the assignee field? I don't find pings / notifications scale well nowadays but reviewing which issues I am assigned gives me something I can periodically look at..
There was a problem hiding this comment.
I was thinking we should probably add a 'Ready for Merge' state.
There was a problem hiding this comment.
Maybe we need to combine the naming discussion with the previous comment, I think ready for merge would be good so periodically we can look at what is ready and get it merged - but do we want a specific state for "Signoff" / "Reiew" or as that discussion is within the feature team could that be the last thing they do whilst in "In Progress"?
There was a problem hiding this comment.
I think you get a big vote on that one, as you'd be a prime beneficiary of the info provided by separating 'Review/Signoff' from 'In Progress'.
The other factor is we talked about a transition to 'Review' triggering automation to add a stability-specific checklist to the issue description, a la what Jakarta has in some of their issues. We could do that when the issue moves into In Progress, but then if the team changes the stability target things get messy.
There was a problem hiding this comment.
See above; for now we decided to drop the 'Review/Signoff' stage unless their is automation to bring value to it.
| 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 |
There was a problem hiding this comment.
The text below already exists but I am wondering if we should have some clarification in this doc to say things along the lines of, this process should be followed for:
- The introduction of a feature at a stability level.
- Further feature development at the same stability level.
- AND for the promotion between stability levels.
In all cases requiring an analysis doc covering the relevant progression.
There was a problem hiding this comment.
I added this; see "Feature Promotion" after "The Process".
bstansberry
force-pushed
the
feature_process
branch
from
22cb958 to
9a6a290
Compare
|
@darranl You approved this, but I have altered it fairly substantially; mostly for stuff related to your comments but also bits and pieces that occurred to me as I edited. (I think those bits and pieces were primarily adding a bit of rationale for why we want a JIRA and the feature issue, plus various minor copy edits / rendering improvements etc. |
* bring back Related Issues sections * clarify the issue metadata semantic Signed-off-by: Jeff Mesnil <jmesnil@redhat.com>
Signed-off-by: Jeff Mesnil <jmesnil@redhat.com>
FEATURE_PROCESS.adoc
Outdated
|
|
||
| When the team believes all development work on the feature is complete, change the `Status` field of the WildFly Feature Planning project JIRA 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. |
There was a problem hiding this comment.
I think I agree @darranl. Possibly what it should be is "Awaiting Merge".
I could see some potential keeping Review to indicate to the merges that progress as been made, and PR's are simply waiting for approval. That said, In Progress really could mean the same thing.
|
I will take another pass through |
|
@emmartins I also added you as a reviewer as this talks about adding features to the WildFly quickstarts |
FEATURE_PROCESS.adoc
Outdated
| * 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. Posting is restricted to subscribers.) | ||
|
|
||
| When the above tasks are complete, change the `Status` field of the WildFly Feature Planning project JIRA to `Planning`. |
There was a problem hiding this comment.
I think JIRA should be Issue
FEATURE_PROCESS.adoc
Outdated
|
|
||
| === 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 the target WildFly release in which they expect to complete the feature. |
There was a problem hiding this comment.
Maybe within the Planning section we can also say something like also not setting the iteration if as a team they are unsure and want to work on the feature first.
|
|
||
| === In Progress | ||
|
|
||
| The main work on the feature happens in this stage. The feature team works to meet the <<requirements,requirements>> that apply to the feature's target stability. |
There was a problem hiding this comment.
This is the kind of thing we can add later but as an open source project maybe we could make some suggestions about discussing publicly such as starting a Zulip thread or a thread on the dev list so others with an interest can follow the conversation.
There was a problem hiding this comment.
They are already asked to start a wildfly-dev thread.
But adding text to encourage public discussion is ok. I am concerned though about this turning into a mega document that no one reads.
|
|
||
| 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. |
There was a problem hiding this comment.
I am not sure if this should be phrased differently so it is not about "expertise", I think it is often more a case that the developer is too close to the feature being developed and may not automatically see the view of others coming from a different perspective who may themselves be experts on a different level. e.g. Experts in the internals of a subsystem vs experts in usability design.
There was a problem hiding this comment.
I left this as is but added a 3rd bullet about someone in this role bringing a different kind of expertise.
| * 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. |
There was a problem hiding this comment.
This came up in another discussion today, would we want to exclude people from other disciplines here such as professional quality engineers / writers?
There was a problem hiding this comment.
Not at all. For 'default' stability features my assumption is the quality engineers and writers we want involved would often act in this role, particularly the writers.
There was a problem hiding this comment.
Also, I don't want to get into this detail in this document, but as a practical matter if the team includes a professional QE person and a technical writer, the team has an 'Outside Perspective'. It seems like a real corner case where that wouldn't be reasonably true.
FEATURE_PROCESS.adoc
Outdated
| * 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. |
There was a problem hiding this comment.
Maybe we should add an expectation that if you introduce a feature at the experimental level you will directly engage the community for feedback , i.e. at experimental we are probably looking for a larger representation of "outside perspective" not smaller as this is the time changes can be made.
There was a problem hiding this comment.
I added a sentence.
github-actions
bot
removed
the
stability-level/community
github-actions
bot
added
stability-level/community
|
Thanks @yersan @darranl @jamezp @emmartins and @jmesnil |
Feature process
Beef up the feature process dco; add more metadata to the design doc.
This bases on #581. That branch may change though, in which case I'll need to rebase, so this is currently in draft state. Other than responding to review comments, I've done what I plan though, other than that rebase.