💡 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 or closed=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 and status, as well as different status values for each type.
  • Incident: Triggered, Acknowledged, Resolved
  • Requirement: Unverified, Satisfied, Failed

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 be moved, duplicate, and promoted.
• 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 and To Do or Closed and Duplicate.
• An issue can already be both Duplicate, Moved, or Promoted and Closed, 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 as Archived.

Option 2: Introduce "status" as a separate attribute

• Introduce a Status attribute.
• All Status values are grouped within the four buckets under the Open state.
• Evolve the notion of Closed to Archived
• Complete and Incomplete 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 from State 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 and Closed states.

Cons:

• Changing the meaning of Closed to Archive may not be as intuitive for existing people intimately familiar with GitLab.

Open Questions

1. How does the solution interplay with the current "issue closing pattern" leveraged by Merge Requests?
2. For Requirements, should Verification Status values be separate from the Status 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 a Failed state while also having a separate "lifecycle" value (i.e. Fix In Progress)?

Validation Next Steps

1. Distribute this issue to the respective teams for feedback.
2. 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	--