This is a work in progress for the Marketing Project Management Simplification project.
Issues are a core building block in GitLab that enable collaboration, discussions, planning and tracking of work.
Issues are typically used to
Because issues can serve so many purposes and roles in GitLab, understanding where they exist and how to best utilize them is incredibly important.
The top section of an issue is the body of the issue - the "Description" In the "Description", is where the core themes and topics of the issue is captured. It is not uncommon to find lengthy issue descriptions, which are used to capture the most current status of the issue.
Because the issue discussions can be long and flowing, often a best practice is to update the description with the most current/ up to date content.
There are many detailed parts of an issue, such as:
In each project, a set of "Issue Templates" can be defined to make it easy to create common issues for different situations or problems. Learn how to create an issue template
Issues enable and support discussions on images and designs with Design Management. Design management makes it very useful in reviewing graphics and design work asynchronously.
Issues, Merge Requests and Epics all support the ability to use keyboard shortcuts trigger key actions in the issue, MR or epic.
Quick Actions are effectively commands that make it easy and efficient to change an issue such as:
/label followed by the label name will add a label./assign followed by a user ID, will assign the issue to a person/close will close an issue/duplicate followed by an issue number will close the current issue as a duplicate and link to the given (open) issue/epic followed by an epic ID will assign the issue to an epicand so on.
Issues can be either open or confidential.
Default to public issues, and use the guidance on non-public communication to make a decision when in doubt.
In the Markdown language that is used to write the description and comments in issues it is possible to create lists of items that work as checkboxes - a list of tasks
Realize that task lists are a relatively simple list of items that can be 'checked off'.
In order to manage interdependency between issues, it is possible to create several types of relationships between issues:
With issue relationships, it is possible to create a series of tasks/issues where there is a sequential requirement that one issue is completed before the following issues are completed.
Define and use Issue Templates for any repetitive types of issues that a team/project will need.
The issue template can be accessed directly through a URL such as
https://gitlab.com/gitlab-com/marketing/strategic-marketing/product-marketing/-/issues/new?issuable_template=A-SM-Support-Request
Where the first half of the URL is the link to the project and then new?issuable_template= followed by the name of the template.
Use Quick Actions in the issue template to ensure that the issues have the appropriate labels, epics, and milestones associated with the issue.
DRI stands for Directly Responsible Individual. As such, an issue should represent a clear deliverable to be completed by the DRI. If work is required from multiple team members, with certain tasks required at different time intervals, in most cases you should break the issue into multiple issues to clarify the deliverable from each team member.
For example, if copy is needed for a landing page, and a different team member will create the page, there should be an issue for the creation of the copy and an issue for creation of the page on about.gitlab so that dependencies are clearly indicated and milestones can be applied correctly with clear DRIs for each action (copy and separately landing page creation).
Issue discussions can be lengthy and exhaustive. As a best practice, update issue descriptions with the most current status and information. For example, if a discussion thread results in a better answer or improved part of the description - update the description. Don't force everyone to read the entire thread and history in order to understand the current status of the issue.
Issues maintain a history of the changes to the descriptions, so update descriptions when it makes sense.
Tip! Using a header with a clear highlight on the "latest update" can be a quick and clear indication to any viewer what has been last agreed in conversations.
Issue weight can be made relative to the tasks within an issue. Issue weight is an estimate of how much time is required to complete the tasks in the issue.
| Time | Weight |
|---|---|
| <4 hours | 0 |
| 4 hours / half a day | 1 |
| 8 hours / 1 day | 2 |
| 12 hours / 1.5 days | 3 |
| 16 hours / 2 days | 4 |
You can use the /weight <value> quick action to define the weight.
In general, avoid using markdown task lists within issues, unless they define very simple tasks, verification or approval steps. Every non-trivial task should be an issue.
Every non-trivial task related to a Marketing program should be filed as an issue instead of a task list within the description of another issue.
When interpreted as a work unit, issues enable better planning and accountability. In particular, they can be added to milestones for scheduling purposes and to assess workload and capacity. In this regard, they also contribute to an iterative approach by having dedicated issues focused on completing a specific task only.
At a glance, everyone should be able to have a basic understanding of the task at hand by reading an issue title, and then delve into the description when more context is needed. This can contribute to scan through issue lists on GitLab.com or on e-mail efficiently.
In general, most issue titles should describe a task as a unit of work to be completed: