馃挕 Status Solution Validation
Problem
The only notion of state or status within issues is state=opened
and state=closed
. This is problematic for multiple reasons:
- When an issue is closed, there is no way to differentiate between
closed=complete
orclosed=incomplete
. This has a negative side-effect of making all issue-related reports fairly inaccurate as things like burndown, burnup, insights, issue analytics, and VSA reports all communicate that all of the closed issues were completed, which is rarely the case. This also makes it impossible to accurately calculate velocity for teams using iterations. - There is no way to easily support visualizing an issue's lifecycle and report on it without first:
- Creating several scoped labels to represent different statuses (ex: workflowsolution validation)
- Creating corresponding lists on a Board.
- Creating a custom value stream analytics report, then creating a custom stage with corresponding events for each scoped label.
- Nothing works by default, which is an anti-pattern (https://about.gitlab.com/handbook/product/works-by-default/).
- There is no way to easily and automatically calculate how long an issue has been "active" vs. "inactive", which is a critical metric that many organizations want to track (especially those that have adopted the Flow Framework)
- As we've made progress on work items, two types of work items already use status (incident, requirement) and the behavior of status as a first-class field and how it interacts with other areas of the product (boards, report views, ...) need to be formalized.
Constraints
Whatever solution we land on needs to:
- Ideally be backward compatible with our current data model on issues (i.e.
state=open
,state=closed
). We cannot remove this attribute on issues as it would break our REST and GraphQL APIs. - Provide backward compatibility for incidents and requirements, which have both
state
andstatus
, as well as differentstatus
values for each type.- Incident:
Triggered
,Acknowledged
,Resolved
- Requirement:
Unverified
,Satisfied
,Failed
- Incident:
Options
The difference between State
vs. Status
is interesting (https://english.stackexchange.com/questions/12958/status-vs-state). If we had the opportunity to start from scratch, we may opt to use State
for the workflow stages and Status
for Open
and Closed
. Alas, we have to evolve from our current state in a graceful way that makes sense for users and does not introduce breaking changes.
What we have high confidence about:
- We need more options to describe the state/status for work items so we can model a default lifecycle for a work item and sprinkle on some automation rules to make managing the lifecycle more efficient (馃挕 Workflows Solution Validation (#344136))
- All the state/status values should be grouped in a way that allows us to programmatically determine if the work item is:
-
active
: the work item is being actively worked on. -
inactive
: the work item is waiting. -
complete
: the work item is complete. -
incomplete
: the work item was "closed" but never completed. Examples of this today would bemoved
,duplicate
, andpromoted
.
-
- The default state/status should be configurable so teams can customize the values to match their desired lifecycle for work items.
- Different work item types will have different lifecycles depending on the type.
- There are scenarios where one work item will be passed to multiple teams. Each team needs a way to measure their work item lifecycle progress (ex: Dev team completes work and hands issue over to a separate QA team). This means that when a team completes their steps, there needs to be a way to denote that a work item is "done" without closing it. The work item would then go through a separate lifecycle with the other team until they are "done." When there is no work left, the work item will be closed.
Option 1: Extend the behavior of "state"
- Add more values for
State
- Allow those values to be grouped into buckets that describe the nature of the state value.
- Provide a way to map states to a work item type
- Expose controls for adding/removing/updating state values
Work Item | Inactive | Active | Complete | Incomplete |
---|---|---|---|---|
Issue |
Open , To Do
|
Doing |
Done |
Moved , Duplicate , Closed , Cancelled
|
Requirement | Unverified |
Doing |
Satisfied |
Failed |
Incident | Triggered |
Acknowledged |
Resolved |
Closed |
Pros:
- Doesn't introduce another
status
attribute.
Cons:
- Does not do a good job of handling the scenario where one work item needs to go through multiple workflows. Once the final workflow is done and the work item moves into a
Complete
state, how do you denote that the work item is no longer active? - Potential confusion during the transition regarding the difference between
Open
andTo Do
orClosed
andDuplicate
. - An issue can already be both
Duplicate
,Moved
, orPromoted
andClosed
, so it would be a fairly substantial change to the mental model of everyone already familiar with GitLab. - We would likely need another mechanism to replace the current notion of
Closed
such asArchived
.
Option 2: Introduce "status" as a separate attribute
- Introduce a
Status
attribute. - All
Status
values are grouped within the four buckets under theOpen
state. - Evolve the notion of
Closed
toArchived
-
Complete
andIncomplete
status values have an option to "auto-archive" the work item. - Provide a way to map states to a work item type
- Expose controls for adding/removing/updating state values
Work Item | Inactive (state=open ) |
Active (state=open ) |
Complete (state=open ) |
Incomplete (state=open ) |
Archive (state=closed) |
---|---|---|---|---|---|
Issue | To Do |
Doing |
Done |
Moved , Duplicate , Cancelled
|
|
Requirement | Unverified |
Doing |
Satisfied |
Failed , Cancelled
|
|
Incident | Triggered |
Acknowledged |
Resolved |
Moved , Duplicate , Cancelled
|
Pros:
- Decouples
Status
fromState
in a manner that supports a work item going through multiple workflows. When the work item is "done done", it can be "archived" which feels intuitive and is a common pattern in other products (linear.app, Trello, ...) - Gracefully evolves our current
Open
andClosed
states.
Cons:
- Changing the meaning of
Closed
toArchive
may not be as intuitive for existing people intimately familiar with GitLab.
Open Questions
- How does the solution interplay with the current "issue closing pattern" leveraged by Merge Requests?
- For Requirements, should
Verification Status
values be separate from theStatus
values discussed in this issue?Verification Status
clearly speaks to the state of the codebase, but is that always the same state/status as a Requirement? Is there ever a time where a Requirement will need to be in aFailed
state while also having a separate "lifecycle" value (i.e.Fix In Progress
)?
Validation Next Steps
- Distribute this issue to the respective teams for feedback.
- Collaboratively determine what we want to finalize this solution proposal.
Team Approval
Given this solution will be leveraged by multiple teams that are consumers of work items, we need to ensure alignment and agreement on the general direction.
Team | DRIs | Sign-off |
---|---|---|
Project Management |
@gweaver @nickleonard
|
-- |
Product Planning |
@mushakov @uhlexsis @kcomoli
|
-- |
Certify | @mmacfarlane @danmh | -- |
Respond |
@abellucci @ameliabauerly
|
-- |