- Work item and work item type terms
- Migrate requirements and epics to work item types
- Work item, work item type, and widgets roadmap
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 become bigger challenges 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.
- Codebase maintainability and feature development becomes a bigger challenges as we grow issues beyond its core role of issue tracking into supporting the different types and subtle differences between them.
Using the terms “issue” or “issuable” to reference the types of collaboration objects
(for example, issue, bug, feature, or epic) often creates confusion. To avoid confusion, we will use the term
work item type (WIT) when referring to the type of a collaboration object.
An instance of a WIT is a work item (WI). For example,
WI model will be built on top of the existing
Issue model and we’ll gradually migrate
model code to the WI model.
One way to approach it is:
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
column. There are
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
work_item_types will involve creating the set of WITs for all root-level groups.
For example, suppose there are three root-level groups with IDs:
assume the following base types:
What we will do to achieve this:
- Add a
work_item_type_idcolumn to the
- Ensure we write to both
issues#work_item_type_idcolumns for new or updated issues.
work_item_type_idcolumn to point to the
work_item_types#idcorresponding to issue’s project root groups. For example:
issues#work_item_type_idis populated, we can switch our queries from using
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_typesfor 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.
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.
In order to customize each WIT with corresponding active widgets we will need a data structure to map each WIT to specific widgets.
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.
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.
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
and we’ll keep current
epics tables to be used as proxies for old references to ensure
backward compatibility with already existing references.
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.
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 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
Feature that will provide feature parity with epics at the project-level. Having that combined with progress
on Consolidate Groups and Projects front will help us
provide a smooth migration path of epics to WIT with minimal disruption to user workflow.
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.