Using GitLab to plan work

We use GitLab to document product strategy and manage our backlog. A couple of concepts that are key to this process are:

• Milestones: Align with our product releases and are used as our group’s planning timeboxes.
• Issues: Capture an atomic piece user value.which should able to be delivered within a singe milestone.
• Tasks (optional): Decompose an Issue into more detailed implementation steps.
• Epics: Group related issues together into a theme or goal. A best practice is for epics to not be everlasting containers but to represent a concrete scope of work, with the goal is for the epic can be closed once the work is complete.
• Boards: Aid in visualizing work moving through the product development flow and for milestone planning.
• Roadmaps: Aid in visualizing epics in a timeline view.

Issues

We use issues to define narrowly scoped items of work to be done. Issues can focus on a variety of different topics: UX problems, implementation requirements, tech debt, bugs, etc. A good guideline for experience-related issues is that they should address no more than one user story. If an issue includes multiple user stories, then it is likely an epic.

When to create an issue

You should create an issue if:

• There isn’t already an issue for what you’re intending to write. Search first
• A feature is mentioned in chat channels like #product, #competition or elsewhere
• A customer requests a particular feature

You should consider not creating an issue when:

• You’re breaking down work very far ahead of implementation. Create broad issues or epics for distant features to minimize the total number of issues and maintain flexibility to iterate on the plan closer to implementation.
• There is already an existing issue. Even if the quality is low, people might have linked to it. Consider rewriting the description instead and leaving a comment that you did so.

How to submit a new issue

1. Search the GitLab project to see if a similar issue already exists. We shouldn’t create duplicates if we can avoid them.
2. Use an issue template to capture all the right data elements:
   • Basic proposal for minor tasks or technical details for tracking larger issues.
   • Lean feature proposal and for all feature enhancements that will get proposals and potentially become release post items.
   • Feature proposal for large new features that may require more information or details and will become release post items.
   • Bug to report undesirable or incorrect behavior.
3. Do not
   • assign someone to the issue
   • assign a milestone
   • set a due date
   • add weight - weight represents the technical complexity and should be defined by our developers
4. Assign labels for work type classification.
5. Leave a comment and tag the product manager to triage the issue. Mentioning someone in an issue comment will trigger the notification mechanisms chosen by the people who are mentioned - therefore there is no need to notify people in another channel after the issue has been created (Slack, email).

Feature issues

Feature issues identify work to support the implementation of a feature and/or results in an improvement in the user experience.

• When considering whether an issue is a missing feature or a bug, refer to the definition of an MVC and Definition of Done for general guidance that works well in most cases.
• If there is doubt about whether you could expect something to be there or work, it’s a missing feature.
• We iterate to deliver features, so we often don’t have functionality that people expect. For this reason, ‘people could reasonably expect this functionality’ does not make it a bug.
• Whether the code results in user facing updates or not, if it is part of building the feature it should be labeled as such.
• Performance improvements and user interface enhancements improve the experience for end users and should be labeled as ~"type::feature".
• API additions including both REST and GraphQL should also be labeled as ~"type::feature".
• If people care about a missing feature and the solution is clear, the issue should be marked as ~"Seeking community contributions".
• If the missing feature has been reported by a customers, the issue should be marked as ~"customer".

Bug issues

Bug issues report undesirable or incorrect behavior, such as:

• Defects in shipped code.
• Inaccurate presentation or data.
• Part of GitLab not working according to the documentation or a universal expectation.
• Functionality inadvertently being broken, or changed from how it is supposed to work. This is also a regression.
• A security issue that is determined to be a vulnerability should be labeled as ~"type::bug" and ~"bug::vulnerability".
• Loss of data while using the product as intended or as documented. Data corruption/loss is one basis for classifying a bug as severity::1.

Epics

Issues related to the same feature should be bundled together into an into an epic.

Epics for a single iteration

Features may include multiple issues even if we are just targeting an MVC. In this case, we should use an epic to collect all of them in one single place. This epic should have a start and an end date, and it should not span more than 3 releases, otherwise we run the risk of having epics drag on indefinitely.

When these issues are finished and closed, we should have successfully achieved the epic’s goal. A good example of this kind of epic is the first iteration on a new feature. Epics representing MVCs should clearly state MVC at the end of the title and should have a parent epic relationship towards a category strategy or a meta epic.

Epics for multiple iterations

Multi-level Epics can be used to track features that will require multiple iterations to fully implement. These epics typically don’t have a specific end date, as they represent an ongoing area of development. However, they should still have a clear goal and definition of success.

Some examples of multi-iteration epics include:

• Category strategy epics that outline the long-term vision for a product area
• Epics for large, complex features that will be built incrementally over time

When creating a multi-iteration epic:

1. Clearly define the overall goal and success criteria
2. Break down the work into smaller, manageable iterations or phases
3. Create child epics or issues for each iteration
4. Regularly review and update the epic as work progresses and priorities change

It’s important to balance between having a long-term vision and maintaining flexibility to adapt based on user feedback and changing priorities. Regularly reassess multi-iteration epics to ensure they still align with product strategy and user needs.

We try to avoid creating epics for time frames as reaching a certain date shouldn’t be considered an exit criteria for feature development. Instead scope epics for product features with a clear user experience goal in mind.

Meta epics for longer term items

To categorize issues and epics into themes or longer running items, we recommend using labels. You can also use epics to track many issues related to a specific topic, even if there isn’t a specific timeline for shipping. These epics should be marked as ~meta, they may not have a specific start or end date, and may contain single iteration epics. This approach can be problematic due to epics and issues within a meta epic may need to be re-parented to represent a work breakdown structure and then lose the meta epic relationship.

Work item state

When an issue or epic is open, this signals that we’re intending or considering implementing that change. It’s important to close items that we’re not considering implementing in the near future, so that we avoid creating uncertainty with customers and colleagues.

When to close an issue or epic

To clearly communicate to our stakeholders what we are going to do, it’s critical that you not only provide the positive view (what we will do), but also articulate the negative view (what we will not do). While this should be communicated in stage and category strategies, it starts with your work items (issues, epics and tasks). Rejecting a feature request or a merge request is not an easy thing. People can feel quite protective of their ideas. They might have invested a lot of time and energy in writing those ideas. You can be tempted to accept a feature only to avoid hurting the people who thought of it. Even Worse, if you reject an idea too harshly, you might discourage other people to contribute, which is something we should strive to avoid.

As a Product Manager you should close work items for the following reasons:

1. Duplicated elsewhere
2. Does not fit within or is antithetical to our vision, it presents a security risk, or other reasons you outline in the issue.
3. Too complex: We want to have a simple, user-friendly product that does complex things, not the other way around.
4. We don’t want another setting: whenever we can, we try to avoid having settings. Some settings are unavoidable, but most aren’t.
5. Low priority: sometimes features are interesting but we simply don’t have the capacity to implement them. In that case, simply tell the truth and indicate that we don’t have enough resources at our disposal to do it at the moment.
6. Brings an Enterprise exclusive feature to the Community Edition: this problem is already addressed in the Stewardship page.
7. No longer relevant.

The ’not the next iteration’ work items are the most important ones to resolve. It is very easy to create a large, comprehensive change with meta items and lots of improvements, but it is essential that we iterate and ship the minimal viable change. We have to ship the iteration, wait for it to be used, and ask for feedback. As a product manager, you must think about the bigger picture when making a proposal to improve the product. It’s important to avoid writing this down as a bunch of work items. Come up with a direction, but only record the first step. This way we can preserve the efficiency of our value of iteration. Closing work items whenever possible is an important part of your job and helps to keep a clear view of what is next.

When closing a work item, leave a comment explaining why you’re closing it, and link to anything of relevance (the other duplicate, the original feature that this is an iteration on, etc). Don’t forget to thank the authors for the time and effort taken to submit the feature request/merge request. In all cases and without exception, you should be nice and polite when interacting with users and customers.

Roadmaps

A roadmap for your group can aid in tracking timeline oriented long-running efforts (here’s an example). This can help keep work well organized, track progress and surface dependencies.

Boards

As part of our planning process it is important that you maintain a prioritized issue board for your group. It’s customary to call these boards STAGE - GROUP - Planning and to configure them to filter to all issues with your group label and with each milestone as a column (here’s an example).

As the DRI for milestone prioritization it is your responsibility to ensure that all items on your Planning board are scheduled to a milestone#milestones and are prioritized both within and across milestones. This means the lowest priority in the current milestone would generally be the top priority in the next milestone. In this regard your planning exercise is a complete prioritization of the near term issues.