This section describes the approach that the Geo team takes to break down the requirements into work-in-progress items that engineers move through the workflow of implementation.
First, we describe general agile work item terminology to create alignment and use common industry vocabulary. We then map these general terms to the specific work item terminology used by GitLab.
Finally we provide some guidelines and rules of thumb when creating new items and about choosing the right level of granularity for them.
Depending on your previous experience, you may be accustomed to a number of different terms to reference work items in an agile development environment. However, it will usually be the case that a certain hierarchy structure is in place to organize project work in groups of increasingly larger scope.
A common breakdown of this hierarchy in general terms is as follows:
We start with the definition of a user story. This is a description of a low granularity piece of functionality or business value that will be delivered to users of the system. It is often expressed in simple terms free of technical jargon or domain-specific terminology, as much as possible.
The point of a user story is that it is as small in scope as possible, while still being a complete piece of functionality. This means that it would be difficult to divide into smaller pieces of work. And if it were to be divided further, at that point it would be difficult to test or feel incomplete from the user’s perspective (i.e. it would provide no actual value on its own).
User Stories should not be confused with the concept of Minimum Viable Change (MVC) at GitLab. An MVC is used to define how much scope of functionality will be delivered by a single iteration of the product, while a user story is a technique or template used to describe individual pieces of business logic in a way that a developer can know when they are done with that part. In this way, an MVC could be composed of multiple user stories.
User stories are typically expressed by a combination of the story itself and a list of acceptance criteria. The story has a structure like:
As a <role>, I would like to <action> so that <outcome and/or motivation>.
The acceptance criteria is a simple bullet list of points that describe how the system should behave and validate inputs in a way that allows the user to complete the task that the user story describes.
Example:
Say you are building a contact form for a website. The story and acceptance criteria could look something like this: User Story: As a website visitor, I would like to submit my contact information to the website administrators so that they can answer my questions via email.
Acceptance Criteria:
From this example, we can see how we could attempt to separate each piece of criteria into a separate user story, but it would then not provide full value to a user. For example, accessing a form from a menu item which can’t be submitted would not be very helpful to the user.
A feature in this context is a grouping element of user stories that share a common goal or a similar theme. This collection of stories would address a higher-level job to be done by users of the system. The feature would have a description in this higher level scope and explain how the individual user stories would work together to meet the feature requirements.
Following our example. A feature could be “Support Requests”, where the contact form is just one user story of various ways that a visitor to the website could request support. Other user stories in this feature could include searching an FAQ or engaging with a Chat Bot or initiating a live chat session with a customer representative.
An Epic is another grouping entity for work. This is a much higher level one and it can include multiple features that deliver on a whole subsystem. Alternatively, it could include features from multiple subsystems that happen to deliver on a cross-cutting job to be done.
An example of an epic might be the development of a customer support portal, which is an entire website with capabilities to browse the documentation, a forum to engage with other customers, and the Support Request feature cited above.
Going in the opposite direction, a task provides more granularity than user stories. Tasks are often actually technical in nature and they describe the implementation steps that need to be taken to satisfy the acceptance criteria for a User Story. Typically an engineer would create a task breakdown outlining the changes that the system needs to undergo to consider the work completed.
In our Contact Form example, tasks could include writing the HTML to layout the fields, adding CSS to style the form, writing javascript to do validation and submit the fields, writing a back-end script to process the fields and send the email etc.
This hardly requires an explanation. A bug is a defect in the intended functionality of the product or a problem that degrades the performance, user experience or usability of the system. Bugs are usually lower in the hierarchy usually assigned to user stories. However, they can be independent pieces of work in a project, especially when they are detected in production after the initial user story or feature was already deployed.
A bug item should have:
GitLab (the platform) has an approach to project management that is agnostic to development methodologies, which provides for a lot of flexibility. However, this means that there are fewer opportunities to represent in a more explicit way the hierarchy of work items presented in the previous section.
This table aims to provide a mapping between the concepts in the hierarchy and the actual capabilities and features of GitLab.
| Concept | GitLab Work Item |
|---|---|
| Epic | Parent Epic |
| Feature | Epic |
| User Story | Issue |
| Task | Tasks * |
| Bug | Issue with label type::bug |
* For tasks, there is a couple of options, we can use task lists in the issue description using markdown, or we can create formally Tasks that are its own work item type in GitLab.
Planning Breakdown workflow and you should then proceed to flesh out the details and provide an estimation of effort. At that point have a discussion with the PM and/or EM about priorities before moving it to the Ready for Dev stage.Ready for Dev until they have been fleshed out with details and estimated.