Labels in GitLab¶
We use scoped
GitLab to manage the issue life cycle and to aid discovery. Scoped labels use
:: to separate the scope from the label text. For example the label
~team::DevOps becomes teamDevOps in GitLab.
We also use un-scoped labels to categories issues into broad work areas. For
example, the label
~Documentation is used to tag all documentation-related
issues and becomes Documentation in GitLab.
A good rule of thumb for deciding if something should be a label is "would I want to search for issues with it". For example, it is desirable to search for issues which relate to a particular role within a product. It would not be necessary to label issues with, for example, the exact epic they are part of because one could just list all issues in that epic directly.
Issue life cycle and workflow¶
workflow::... scoped labels are used to manage the issue life cycle. It
is the responsibility of all team members to make sure that the labels reflect
reality but the daily stand up provides a good opportunity to re-visit issues
within the current sprint to check they are labelled correctly.
Labels used before the sprint¶
The following labels are usually applied to issues before they enter the current sprint.
- workflowNeeds Refinement
- The issue requires refining to meet the Definition of Ready. This refinement usually happens as part of the sprint refinement ceremony.
- workflowNeeds Sizing
- The issue has been refined but needs an estimate on how long it will take in order to meet the Definition of Ready. This sizing is usually done as part of the sprint planning ceremony.
- Work on this issue cannot proceed because of external restrictions. Ideally blockers will be identified before issues enter a sprint.
- workflowSprint Ready
- This issue meets the Definition of Ready and can become part of a sprint.
- workflowBAU Blocked
- This issue represents ongoing business-as-usual work which has stalled due to an external restriction.
We try to be asynchronous where possible but we do have two important ceremony meetings where the entire team is present: backlog refinement where issues in need of refinement can be discussed and sprint planning where we schedule the next sprint.
On the face of it, the workflowNeeds Refinement and workflowSprint Ready labels should suffice for those
meetings but we sometimes want to tag issues we particularly want to discuss at
the next meeting. For these we have
meeting:: scoped labels:
- meetingbacklog refinement
- meetingsprint planning
These labels should be temporary since they explicitly refer to the next
meeting. At the end of the meeting, there should be no issues labelled with the
Labels used during the sprint¶
- workflowIn Progress
- This issue is currently under development. It should be assigned to the person currently performing the work. Ideally people should only be assigned to one "in progress" issue at any one time; if they cannot proceed, it should be moved to workflowBlocked.
- workflowReview Required
- The work required for this issue has been completed and is ready for review. For issues with associated code changes, this usually means there is a Merge Request open which references the issue.
- workflowNeeds Testing
- For teams which have separate testing roles, this issue is ready to be picked up by QA.
- workflowIn Testing
- For teams which have separate testing roles, this issue is currently being tested after a positive review.
- The work completed as part of this issue has had some changes requested by the reviewer or, for teams which have separate testing roles, the tester.
- workflowNeeds Deployment
- The work associated with this issue has been merged but a manual deployment step is required for the work to be completed.
- Issue meets the Definition of Done. Usually the issue will have also been closed.
Labels used after the sprint¶
Once closed in a sprint, issues are generally not looked at again but it is useful to tag them with the ultimate resolution for the benefit of anyone watching the issue via GitLab notifications.
An issue being closed usually means "the work in this issue has been done".
This is not always the case and it is useful to be able to see at a glance what
ultimately caused an issue to be closed. We use the
labels to record this for issues which were closed for reasons out of the
- resolution Can't Reproduce
- The issue appears to report a bug but, either through lack of steps or because it was fixed before being looked at, the bug cannot be triggered by a developer so that they can find and fix it. The issue was closed but could be re-opened if a way of triggering the bug is found.
- resolution DevNotPlanned
- The issue relates to a potential feature which we have decided not to implement.
- resolution Duplicate
- This issue contains work which is already contained in an existing issue and has been closed in favour of the existing one.
- This issue represented either a bug or misconfiguration which has been addressed.
- resolution Won't Fix
- The issue appears to report a bug which is actually either an example of the product working as intended or is functionality we can accept within the scope of the product.
We have multiple teams within DevOps. The
team::... scoped labels can be used
to denote "ownership" of issues by a particular team. By taking ownership of an
issue, a team commits to refining and sizing it until it is sprint ready and to
schedule it as appropriate in upcoming sprints.
The following team labels are defined:
There is also teamDevOps for issues which are, in some way, the responsibility of the entire division.
Although teams can usually reflect priorities within a sprint by directly ordering the issues in the workflowSprint Ready column of the sprint board, it is useful for the team to have a wider view of product priorities and for those priorities to be assigned to issues before they enter the sprint.
priority::... scoped labels describe priorities and indicate in which
order issues should be done within the sprint. For example, priority 1 issues
should be picked up in a sprint before priority 2 ones and so on.
Priority labels should not be used to indicate strict ordering outside of the sprint. For example, do not create a sprint consisting entirely of issues with priority 0 when there are priority 1 issues open since this will cause resource starvation for lower-priority issues.
- priority0 Highest
- The issue has the highest priority and requires immediate attention. This label should be used for issues tracking work which is necessary now to prevent service disruption or some other severe consequence.
- priority1 High
- The issue is urgent and needs to be addressed as soon as possible.
- priority2 Medium
- The issue has "normal" priority. The issue can be scheduled for a sprint and can be addressed at any point during the sprint. We do strongly desire that the issue be addressed at some point within the sprint.
- priority3 Low
- The issue reflects work we would like to complete within a given sprint but it is not necessary that the work be completed. For example, the work has a natural due date which is well beyond the end of the sprint and is not currently blocking any other work.
- priority4 Lowest
- The issue represents a "nice-to-have" but does not have any natural due date and does not prevent further enhancement of the product.
We structure epics as a tree grouped into three levels which are, from most
general to least: "features", "initiatives" and simple "epics". We use the
EpicType::... scoped labels to label epics so that we can tell at a glance
where they sit in this hierarchy.
- Used to group all issues and epics related to a single high-level feature. Usually this will have initiatives or epics as children.
- Used for grouping detailed epics for easier management.
- The most detailed type of epic. Issues should be attached to epics at this level.
- Used early in the life of a feature to capture anticipated work before it is refined into epics and issues.
Often the same broad categories of issues come up within a sprint. The
issueType::... scoped labels are used to provide a broad category for an
issue so that the balance of a sprint may be seen at a glance.
- The issue describes a way in which the functionality of the product is not as designed or intended by the code author.
- issuetypeUser Story
- The issue captures an end-to-end user-centric piece of work sized to fit within a single sprint
- The issue captures feedback on the product provided by users.
- The issue captures a support request from a user of the product.
- The issue represents a general task which needs to be performed but is not directly related to a bug or a new feature.
Issues have a habit of growing in refinement. For these issues we have the following temporary labels which indicate that they should be split into epics or features.
- This issue has unpacked into a large collection of work, comprised of one or more epics. The issue should be split into features and thence into epics.
- This issue represents work which has grown beyond the size of a single issue and needs splitting out into an epic.
While the use of issue type labels is a convenience for those building new features or fixing bugs, it is also of great utility to those providing user support for a product. As such the issuetypeSupport label is one of the heavier used issue type labels and it is probably useful to bookmark the list of issues with this tag.
We have some labels which describe which role(s) within the product team especially relate to the issue.
Remember, a golden rule is "it is your responsibility to move things forward". Just because an issue is labelled with a particular role, it doesn't mean that your input on the issue is not valued.
- Issues which relate to making the product accessible for users with additional needs. Usually used by teams with dedicated accessibility testing.
- Business Analysis
- Issues which require analysing business practices of the University.
- Issues which require active software or infrastructure-as-code development work.
- Developer Experience
- Issues which require technical work which does not directly improve the product but is required to make future development easier or more pleasant.
- Issues which require writing documentation for the team or for end-users.
- Issues which relate to deployment or packaging of products.
- Issues relating to testing tools, procedures, technologies or practices.
- UI Design
- Issues which require user interface design work
- UX Research
- Issues relating to user experience research.
We have some labels which are used to indicate "special" issues which have properties we care about. This section discusses these labels.
Good first issues¶
Everyone will be new to a product at some point. Some issues may lend themselves to a newcomer because they involve a small, well-defined task which also illustrates an important feature of the product's architecture of deployment. As a courtesy to people new to a product we use the good first issue label to indicate these issues.
The work required to address some issues is "obvious" or "well rehearsed". We call these issues "chores" since they reflect repetitive work which many team members could do. Examples of chores include: fixing typographic or grammatical errors in documentation, sending an email requesting something from the rest of the business or performing some manual configuration of a service.
We use the chore label for such issues.
A "chore" may be sufficiently small that it can be addressed and closed without progressing to review. Usually, however, it is good practice for even small configuration changes to be put into workflowReview Required as an additional check and to allow at least one other team member to see what work had been done.
Some issues have the potential to be open-ended. These are usually issues which require some form of research into a particular technology or business practice. It can be hard to estimate such issues as they could expand to fill the available time.
To make it possible to estimate work from a point of knowledge, an issue may be labelled as with spike. A spike is an issue which is time-boxed, usually to one day. The team member picking up the spike does as much work as they can within the spike's time window and reports back in the issue.
The report can be used to more accurately gauge what work is required to close an issue and how long it will take. It may also result in the team deciding to close or de-sprint the issue if the work/reward ratio is not favourable.
Usually any code arising from a spike is considered "prototype" or "throwaway". Occasionally the refinement of the code into a more polished initial version may be added as a new issue.
Inevitably, despite one's best efforts, issues will arise mid-sprint which need to be addressed. In sprint planning we usually keep a small amount of time back for these issues. When they arise we add the placeholder label to them.
Way back in the before times, we used to manage our sprint physically on boards with sticky notes. We would create dedicated "placeholder" notes in the sprint at planning time which would be exchanged for mid-sprint issues. By having a fixed number of "placeholder" notes, we ensured that we did not introduce too many additional issues.
These sticky notes were indicated with a purple sticky dot for easy identification because we had a lot of purple dots. This is the reason for the name, and the colour, of the label.
Quick to review¶
The quick to review label can be added to issues in workflowReview Required to indicate to potential reviewers that review should be a straightforward and quick process. If you find yourself waiting for a long deployment or for a slow test suite to run, consider picking up a quick to review issue to help move the sprint along.
The Comms Required label is often used in combination with workflowBlocked. It is used to indicate that the work has been completed but that deploying the change cannot be done before external communications have been sent out to users by the UIS Communications team. They can be contacted at email@example.com.
Modifying top-level labels¶
The labels discussed on this page are defined within the uis/devops group and are intended to be shared as a common language between teams. As such it is considered courteous to make changes to these labels in co-ordination with the Head of DevOps so that consistency between teams can be maintained.