1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
---
stage: Plan
group: Project Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Work items and work item types
## Challenges
Issues have the potential to be a centralized hub for collaboration.
We need to accept the
fact that different issue types require different fields and different context, depending
on what job they are being used to accomplish. For example:
- A bug needs to list steps to reproduce.
- An incident needs references to stack traces and other contextual information relevant only
to that incident.
Instead of each object type diverging into a separate model, we can standardize on an underlying
common model that we can customize with the widgets (one or more attributes) it contains.
Here are some problems with current issues usage and why we are looking into work items:
- Using labels to show issue types is cumbersome and makes reporting views more complex.
- Issue types are one of the top two use cases of labels, so it makes sense to provide first class
support for them.
- Issues are starting to become cluttered as we add more capabilities to them, and they are not
perfect:
- There is no consistent pattern for how to surface relationships to other objects.
- There is not a coherent interaction model across different types of issues because we use
labels for this.
- The various implementations of issue types lack flexibility and extensibility.
- Epics, issues, requirements, and others all have similar but just subtle enough
differences in common interactions that the user needs to hold a complicated mental
model of how they each behave.
- Issues are not extensible enough to support all of the emerging jobs they need to facilitate.
- Codebase maintainability and feature development becomes a bigger challenge as we grow the Issue type.
beyond its core role of issue tracking into supporting the different work item types and handling
logic and structure differences.
- New functionality is typically implemented with first class objects that import behavior from issues via
shared concerns. This leads to duplicated effort and ultimately small differences between common interactions. This
leads to inconsistent UX.
## Work item terminology
To avoid confusion and ensure communication is efficient, we will use the following terms exclusively when discussing work items.
| Term | Description | Example of misuse | Should be |
| --- | --- | --- | --- |
| work item type | Classes of work item; for example: issue, requirement, test case, incident, or task | _Epics will eventually become issues_ | _Epics will eventually become a **work item type**_ |
| work item | An instance of a work item type | | |
| work item view | The new frontend view that renders work items of any type | | |
| legacy issue view | The existing view used to render issues and incidents | | |
| issue | The existing issue model | | |
| issuable | Any model currently using the issueable module (issues, epics and MRs) | _Incidents are an **issuable**_ | _Incidents are a **work item type**_ |
Some terms have been used in the past but have since become confusing and are now discouraged.
| Term | Description | Example of misuse | Should be |
| --- | --- | --- | --- |
| issue type | A former way to refer to classes of work item | _Tasks are an **issue type**_ | _Tasks are a **work item type**_ |
### Migration strategy
WI model will be built on top of the existing `Issue` model and we'll gradually migrate `Issue`
model code to the WI model.
One way to approach it is:
```ruby
class WorkItems::WorkItem < ApplicationRecord
self.table_name = 'issues'
# ... all the current issue.rb code
end
class Issue < WorkItems::WorkItem
# Do not add code to this class add to WorkItems:WorkItem
end
```
We already use the concept of WITs within `issues` table through `issue_type`
column. There are `issue`, `incident`, and `test_case` issue types. To extend this
so that in future we can allow users to define custom WITs, we will move the
`issue_type` to a separate table: `work_item_types`. The migration process of `issue_type`
to `work_item_types` will involve creating the set of WITs for all root-level groups.
NOTE:
At first, defining a WIT will only be possible at the root-level group, which would then be inherited by sub-groups.
We will investigate the possibility of defining new WITs at sub-group levels at a later iteration.
### Introducing work_item_types table
For example, suppose there are three root-level groups with IDs: `11`, `12`, and `13`. Also,
assume the following base types: `issue: 0`, `incident: 1`, `test_case: 2`.
The respective `work_item_types` records:
| `group_id` | `base_type` | `title` |
| -------------- | ----------- | --------- |
| 11 | 0 | Issue |
| 11 | 1 | Incident |
| 11 | 2 | Test Case |
| 12 | 0 | Issue |
| 12 | 1 | Incident |
| 12 | 2 | Test Case |
| 13 | 0 | Issue |
| 13 | 1 | Incident |
| 13 | 2 | Test Case |
What we will do to achieve this:
1. Add a `work_item_type_id` column to the `issues` table.
1. Ensure we write to both `issues#issue_type` and `issues#work_item_type_id` columns for
new or updated issues.
1. Backfill the `work_item_type_id` column to point to the `work_item_types#id` corresponding
to issue's project root groups. For example:
```ruby
issue.project.root_group.work_item_types.where(base_type: issue.issue_type).first.id.
```
1. After `issues#work_item_type_id` is populated, we can switch our queries from
using `issue_type` to using `work_item_type_id`.
To introduce a new WIT there are two options:
- Follow the first step of the above process. We will still need to run a migration
that adds a new WIT for all root-level groups to make the WIT available to
all users. Besides a long-running migration, we'll need to
insert several million records to `work_item_types`. This might be unwanted for users
that do not want or need additional WITs in their workflow.
- Create an opt-in flow, so that the record in `work_item_types` for specific root-level group
is created only when a customer opts in. However, this implies a lower discoverability
of the newly introduced work item type.
### Work item type widgets
All WITs will share the same pool of predefined widgets and will be customized by
which widgets are active on a specific WIT. Every attribute (column or association)
will become a widget with self-encapsulated functionality regardless of the WIT it belongs to.
Because any WIT can have any widget, we only need to define which widget is active for a
specific WIT. So, after switching the type of a specific work item, we display a different set
of widgets.
### Widgets metadata
In order to customize each WIT with corresponding active widgets we will need a data
structure to map each WIT to specific widgets.
NOTE:
The exact structure of the WITs widgets metadata is still to be defined.
### Custom work item types
With the WIT widget metadata and the workflow around mapping WIT to specific
widgets, we will be able to expose custom WITs to the users. Users will be able
to create their own WITs and customize them with widgets from the predefined pool.
### Custom widgets
The end goal is to allow users to define custom widgets and use these custom
widgets on any WIT. But this is a much further iteration and requires additional
investigation to determine both data and application architecture to be used.
## Migrate requirements and epics to work item types
We'll migrate requirements and epics into work item types, with their own set
of widgets. To achieve that, we'll migrate data to the `issues` table,
and we'll keep current `requirements` and `epics` tables to be used as proxies for old references to ensure
backward compatibility with already existing references.
### Migrate requirements to work item types
Currently `Requirement` attributes are a subset of `Issue` attributes, so the migration
consists mainly of:
- Data migration.
- Keeping backwards compatibility at API levels.
- Ensuring that old references continue to work.
The migration to a different underlying data structure should be seamless to the end user.
### Migrate epics to work item types
`Epic` has some extra functionality that the `Issue` WIT does not currently have.
So, migrating epics to a work item type requires providing feature parity between the current `Epic` object and WITs.
The main missing features are:
- Get WIs to the group level. This is dependent on [Consolidate Groups and Projects](https://gitlab.com/gitlab-org/architecture/tasks/-/issues/7)
initiative.
- A hierarchy widget: the ability to structure work items into hierarchies.
- Inherited date widget.
To avoid disrupting workflows for users who are already using epics, we will introduce a new WIT
called `Feature` that will provide feature parity with epics at the project-level. Having that combined with progress
on [Consolidate Groups and Projects](https://gitlab.com/gitlab-org/architecture/tasks/-/issues/7) front will help us
provide a smooth migration path of epics to WIT with minimal disruption to user workflow.
## Work item, work item type, and widgets roadmap
We will move towards work items, work item types, and custom widgets (CW) in an iterative process.
For a rough outline of the work ahead of us, see [epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033).
|
