Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Product

Are you not on the product team, but looking for information on how to get in contact with or provide information/ask questions to product managers? Please see our How to Engage guide.

The document below talks about how we do product at GitLab, not about what. For the what, see Product Direction.

If you are a product manager looking to learn our process, this document is broken into four sections:

On this page

Product Principles

GitLab is designed and developed in a unique way.

The direction for the GitLab product is spelled out on the Direction page. This document provides lessons and heuristics on how to design changes and new features. Our iterative process is demonstrated in a blog post.

Much of our product philosophies are inspired by the Ruby on Rails doctrine of 'Rails is omakase'. I highly suggest reading these.

TL;DR

  1. Minimally Viable Change: Work in iterations by implementing only the minimally viable change.
  2. Convention over Configuration: Avoid configuration and make it work out of the box.
  3. Be Ambitious: do things no one else is doing.
  4. Do not mess with Flow: frictionless from planning to monitoring. Avoid adding clicks.
  5. Embrace the single application: unlock the unique benefits of a single application in early iterations.

The Minimally Viable Change (MVC)

Reduce every change proposal to its absolutely minimally viable form. This allows us to ship almost anything within a single release, get immediate feedback and avoid deep investments in ideas that might not work. Other advantages:

The minimally viable change should not be a broken feature.

Content of an MVP

We only ship in a Minimally Viable Product style. Here are some guidelines about it:

mvc.png

Virtually every new feature must be maintained forever (the standard for sunsetting a feature is very high). Creating a new feature means that GitLab has to continually manage the technical costs of maintenance of that feature. Making small changes with quick feedback loops reduces the risk of introducing a new feature where the value doesn't justify the long-term costs.

A new feature also adds a tax on the user experience due to additional complexity in the product. Make sure that the benefits gained by users from the new feature more than cover the tax incurred, accounting for how frequently the new feature is used by users. In particular, the new feature should satisfy this inequality:

(benefits * frequency) / (tax * (1-frequency)) > 1

Despite its minimal form, the change

xkcd.com

Converting ideas into MVCs quickly

There is a certain failure case for MVC issues that product managers need to be aware of and actively work to prevent; because we don't have infinite capacity to work on everything, and good ideas are always coming in, it's possible (if the PM is not watching closely) for issues with good ideas to slowly but inevitably decay into something that is difficult to understand and move forward with. As more and more comments are added and the issue slowly morphs from idea to idea without any direction from a product manager, it will become difficult to ever make complete sense of it again without losing some important context. It will also be nearly impossible for someone who wants to make a community contribution to understand what the direction is. It becomes an undefined blob of ideas.

To prevent this, it is the responsibility of the product manager to quickly turn open-ended idea issues into something actionable, deliverable, and truly MVC as quickly as possible.

The guidance for product managers here is to never let an idea issue persist longer than three months without having been converted into a clear MVC. If this has not happened, you should ask yourself why this is the case: is the idea overly broad? Is there no clear immediate deliverable? Is it just not important enough to spend time on? These are all signals that should be acted upon without delay, before the issue degrades to the point that it becomes unusable without significant rework.

Convention over Configuration

Prefer choices that are well thought out and based on current best practices. Avoid unnecessary configuration. Avoid configuration to support fragile workflows.

For example, when considering whether to add a checkbox or two radio boxes, think carefully about what users really want. Most of the time, you'll find you really only need one solution, so remove the other option. When two possible choices really are necessary, the best or most common one should be the default, and the other one should be available. If the non-default choices are significantly less common, then consider taking them out of the main workflow for making decisions, by putting them behind an Advanced configuration tab, for example.

Every configuration option in GitLab multiplies its complexity, which means the application is harder to use, harder to develop, and less friendly to users.

Requests for configuration can be a proxy for trying to support a fragile workflow. Rather than enabling bad habits and incurring product debt, effort should be spent helping customers adopt best practices.

Making features configurable is easy and lazy. It's a natural reaction to propose a big change to be configurable, as you worry it'll negatively affect certain users. However, by making a feature configurable, you've now created two problems.

xkcd.com

Work on solutions that work for everyone, and that replace all previous solutions.

Sometimes configuration is inevitable or preferable. GitLab should work perfectly right out of the box for most users. Your configuration must not make that experience worse and should always get out of the way of the user.

Encouraging behavior

Convention also implies that we're encouraging our customers to do things in a certain way. A very concrete example of this is the ability to disable pipelines. We believe that our integrated solution will give a superior user experience and we're motivated to encourage this behavior. For this reason, adding a configuration to allow disabling this permanently (be that in a template or instance-wide), is something that should be avoided.

Encourage favorable behaviors by limiting configuration.

Default to ON

In addition to encouraging behavior by limiting the ability to toggle features, new features, when introduced, should default to turning things ON (if they are configurable at all).

Deciding on configurations

Avoiding configurations is not always possible. When we have no choice, the secondary priority is to configure something in the GitLab interface. A configuration should only appear in a file (gitlab.rb or gitlab.yml) as a last resort.

Configuration in file

There are two major configuration files available in GitLab. Adding configurations to either should be avoided as much as possible.

When you have to add a new configuration, make sure that the features and services are on by default. Only add a configuration line to either of these configuration files if the feature or service cannot be fully disabled from the admin UI.

Convention over configuration is also listed in the CONTRIBUTING file in GitLab's repositories.

Be Ambitious

Many crazy, over-ambitious ideas sound like they are impossible just because no one else is doing them.

Since we have amazing engineers and a culture of shipping minimally viable changes, we are able to do a lot more 'impossible' things than others.

That's why we're shipping merge conflict resolution, why we shipped built-in CI before anyone else, why we built a better static pages solution, and why we're able to compete.

xkcd.com

How this impacts Planning

Here at GitLab, we are an ambitious company and this means we aim for big things with every release. The reality of taking chances and planning aspirationally means that we won't always be able to deliver everything that we wanted to try in every release, and similar to our OKRs, we believe this is a good thing. We don't want to shy away from challenging ourselves and always want to keep a sense of urgency, and aiming for more helps us do that. Also see the importance of velocity

Simplicity

Doing something simple in GitLab should BE simple and require no human cpu-cycles to do so. Things that are simple now should still be simple two years from now, ten years from now, and onwards.

This sounds obvious, but messing with flow is easily done. In most cases, flow is disrupted by adding another action, or another click.

For instance: You want users to be made aware of the rules of a project. Your proposal is a little popup that shows the rules before they create an issue. This means that every time that someone creates an issue they need to click once before resuming their normal action. This is unacceptable. A better solution is to add a link to the issue that points the user to this.

xkcd.com

It's very hard to maintain flow with a lot of configurations and options. In cases where you want to enforce a certain behaviour, the most obvious step may be to add another step or action. This can be avoided by making the action work in parallel (like a link in the issue), encouraging rather than enforcing certain behaviours.

Also, we don't want users to be able to construct workflows that break GitLab or make it work in unpredictable ways.

Discoverability Without Being Annoying

Feature discoverability is important for allowing new and existing users to access old and new features, thereby increasing the value for them. It also allows GitLab to get as much feedback as possible, as fast as possible, in order to quickly iterate.

However, UI that purports to increase discoverability, but that is not carefully designed and implemented, may actually harm the overall experience by constantly shoving unwanted images and text in the face of the user. The end result is that the user loses trust in GitLab, and they no longer take the time to carefully parse text and other UI elements in the future. Even worse, they might leave GitLab because of this degraded experience. The following are a few illustrative examples and best practices.

Empty states

pipelines_empty_state.png

Banners

Think of this: Your co-worker is hard at work in front of their computer, and you suddenly tap their shoulder or yell at them to tell them about some new cool widget. You better have a good reason for that: that widget better be awesome.

Back to the analogy: Your co-worker said they don't care about that new cool widget. Never, ever, ever, bring it up again. They told you they don't care, and you need to respect that.

pipelines_empty_state.png

Leveraging navigation is an effective design paradigm to introduce a user to a new feature or area of GitLab.

Back to the analogy. We're not going to bother our co-worker with 5 different cool new widgets at the same time.

tooltip_boards.png

Flow One

Shipping only MVCs can result in a large set of loosely connected pieces that don't necessarily combine into a single, great user experience.

An obvious solution to this would be to plan out the future in detail, creating a long-term roadmap. However, this is unwanted as it can restrict your flexibility and ability to respond to changing needs or feedback.

Flow One offers an alternative. You draw out a workflow consisting of MVCs (that can be shipped individually). The workflow should only cover a specific, narrow use-case, and nothing more.

This means you:

Flow One should cover the first iteration of a particular workflow. After this, individual MVCs can be introduced to expand the use-cases or loosen the assumptions (e.g. from a feature that can only be used if you're using feature branches, to one that works for other git strategies).

Breadth over depth

See our thoughts on breadth over depth on our strategy page. While we prioritize breadth over depth, Product Managers should not lose sight of maturing each product category, with the ultimate goal of each category moving into a lovable state. A good rule of thumb to consider when planning product improvements, is that over time, approximately 70% of engineering effort should be allocated on breadth, and 30% on depth.

Data-driven work

Using data to learn from our users is important. Our users are spread across GitLab.com and self-managed instances, so we have to focus our efforts on learning and providing benefit to both when we decide to collect more data, or build and use additional analytics tools. If we do this, we can help make the rest of the company successful as well. This means that we should:

No artificial limits in Core

Per GitLab Stewardship, we will not introduce artificial limits in Core. Artificial means arbitrarily setting a small number (such as: 1) as a limit on a given GitLab object category, that would incur no additional effort or cost had we chosen a larger number. The additional effort includes product, design, and engineering effort to create the feature in the first place, and to maintain it over time.

For example, GitLab Core has the issue board feature in every project. In GitLab EE, each project supports multiple boards. This does not mean that Core has an artificial limit of one board per project, because there is additional effort to manage multiple boards such as supporting the navigation interface, and all the associated engineering work.

No enforced workflows

We're discussing enforced workflows in this issue.

Enforced workflows should be avoided in GitLab. For example, there are three issue states (Open, In Progress (as of 10.2), and Closed), and any issue should be allowed to transition from one state to any other state without workflow restrictions. (Roles and permissions is a separate concern.)

A comment on Hacker News perfectly details what can go wrong when enforcing workflows:

"The down side for the true end-users, those who actually use the software day-to-day, is that most business processes are awful. If your experience is the hellish existence that I see strolled about on threads where JIRA comes up …:

  1. Your admin(s) set it up once and hasn't bothered to iterate on those workflows.
  2. The business mapped their autonomy stripping processes onto JIRA intentionally. I'd guess that most of your work experience is similar. Process stifled nonsense."

But that comment also specifies the advantage:

"JIRA's most powerful feature is that it affords for mapping businesses processes onto software. This is incredibly compelling to enterprise customers. Software that enforces workflows, procedures and requirements can be an incredible lever and JIRA's price point makes build vs buy decisions an absolute no-brainer."

We should ensure that GitLab makes it easy to help with enterprise workflows:

Prefer small primitives

Small primitives are building blocks in GitLab. They are an abstraction not at the technical level, but truly at the product level. Small primitives can be combined, built-upon further, and otherwise leveraged to create new functionality in GitLab. For example, the label lists in issue boards use the smaller primitive of labels.

When iterating on GitLab, strongly consider using small primitives instead of creating new abstractions.

Product Process

Introducing changes requires a number of steps, with some overlap, that should be completed in order:

Important dates PMs should keep in mind

The following dates are derived from the Product Development Timeline.

(current release = published this month, upcoming release = published next month)

Planning horizon

  1. Mission: generation
  2. Strategy: lustrum
  3. Vision: year
  4. Milestones: quarter (we have issues assigned to specific release milestone for a rolling 3 months)
  5. Release: month (we try to not change the release that is started)

Inspired by:

Prioritization: Ahead of kickoff

  1. Proper discovery has been done and requirements for the change are defined
  2. Engineering has been involved in the discovery process (FE, BE, UX, as needed)
  3. Technical architecture has been drafted and is agreed upon
  4. Scoping and splitting up into actionable issues has happened

Kickoff meeting

Preparation

  1. The release post manager that will lead the release post will be the directly reponsible individual for presenting and leading the meeting for the same release. So the release post manager for GitLab X.Y will present the X.Y Kickoff.
  2. The format of the meeting will be that of a panel interview focused on the product. This will mean they they will prepare the introduction and closing thoughts.
  3. Relevant issues are added to the Kickoff doc
    • Product managers should add any issue that is marked ~direction and ~Deliverable for the upcoming milestone (no ~Stretch issues)
    • Issues should report the tier they will be included in
  4. Issues from previous release are marked merged or not merged on the rightmost column. If any direction items were added (new items or newly marked as ~direction) add those to the document and mark them in bold.
  5. PM should consider if issues from previous release which are marked not merged should be included again in the next release
  6. Issue descriptions are updated to include an introduction to the underlying problem, use cases, and a complete proposal. It should be easy to understand the problem from reading the issue title and description without digging through comments.

Meeting

  1. In order to prevent distraction, when presenting the Kickoff doc use the "View for Web" version
  2. The release post manager starts the meeting by:
    • Giving a small introduction about the topic of this meeting
    • Introducing the panel interviewees and themselves
    • Reminding anyone who may be watching the video/stream about how we plan ambitiously.
  3. During the discussion about a product category
    • The release post manager will continue to screenshare to aid the interviewee.
    • The interviewee will explaining the problem and proposal of listed items and guides the RPM through the inividual issues. If there is a UX design or mockup available, it will be shown.
  4. The release post manager often ends the meeting by quickly highlighting several high impact issues to communicate our excitement in the upcoming release. Consider even using one of our popular phrases: “This will be the best release ever!”

Execution

  1. Design
  2. Backend development
  3. Frontend development
  4. QA and feature assurance
  5. Deploy

QA RCs on staging and elsewhere

After the feature freeze, it's expected of each product manager to test their own features and perform quality assurance to the best of their ability and follow up where necessary.

Product managers can use the staging environment once the release managers have deployed a release candidate to staging. Release managers should post in the #product channel in Slack that a new release candidate is available. Product managers can also use other environments as needed, such as GitLab provisioned on Kubernetes with GKE.

Feature assurance

Before a new features is shipped, the PM should test it out to make sure it solves the original problem effectively. This is not about quality assurance (QA), as developers are responsible for the quality of their code. This is about feature assurance (FA). Feature assurance is necessary because sometimes there are misunderstandings between the original issue proposal and the final implementation. Sometimes features don't actually solve the intended problem, even though it seemed like it would, and sometimes solutions just don't feel as useful as intended when actually implemented.

If you can test out the feature during development, pulling down branches locally (or with a review app!), that's great. But sometimes it's not feasible to test a feature until it's bundled into a release candidate and deployed to GitLab.com. If so, make sure to test out features as soon as possible so any new issues can be addressed before final release. Also, take the FA cycle into account when scheduling new milestone work.

If you are looking to test code that has not been merged to GitLab.com or is not yet part of an RC, you can pull the branch down locally and test it using the GitLab Development Kit (GDK).

Dealing with security issues

Product managers should set Milestones for issues marked with the security label to guarantee they are shipped by their due date, as defined in the Security Team process. Product Managers are the DRIs for prioritization. As such they should deeply understand the implications and risks of security related issues and balance those when prioritizing. You may need to set a different milestone for security issues, for example because of low capacity, but before doing that you should engage a conversation with the Security Team. Priority labels and Due Date designations should not be modified by product managers in any case, since they are directly managed by the Security Team, and used to track metrics and progress.

How to work as a PM

If you follow the principles and workflow above, you won't be writing long, detailed specs for a part of the product for next year. So how should you be spending your time?

Invest the majority of your time (say 70%) in deeply understanding the problem. Then spend 10% of your time writing the spec for the first iteration only and handling comments, and use the remaining 20% to work on promoting it.

A problem you understand well should always have a (seemingly) simple or obvious solution. Reduce it to its simplest form (see above) and only ship that.

Once you've shipped your solution, both you and the community will have a much better idea of what can be improved and what should be prioritized for future iterations.

As a PM, you're the person that has to kick-off new initiatives. You're not responsible for shipping something on time, but you are responsible for taking action and setting the direction. Be active everywhere, over-communicate, and sell the things you think are important to the rest of the team and community.

As a PM, you need to set the bar for engineering. That is, to push engineering and the rest of the company. You almost want engineering to complain about the pace that product is setting. Our default instinct will be to slow down, but we can't give in to that.

As a PM you don't own the product; ask other people for feedback and give team members and the community the space to suggest and create things without your direct intervention. It's your job to make sure things are decided and planned, not come up with every idea or change.

Where should you look when you need help?

Responsibilities and Expectations

As a PM you're expected to:

Scope of responsibilities

The product team is responsible for iteration on most of GitLab's products and projects:

This includes the entire stack and all its facets. The product team needs to weigh and prioritize not only bugs, features, regressions, performance, but also architectural changes and other changes required for ensuring GitLab's excellence.

Goals of Product

Everyone at GitLab is involved with the product. It's the reason why we are working together.

With every release of GitLab, we want to achieve each of the following goals.

  1. Improve GitLab's existing tools.
  2. Achieve our vision of a complete toolset.
  3. Make our product more interesting for our customers through Products and EE exclusive features.

Objectives and Key Results (OKRs)

Like all teams, the Product team participates in GitLab OKRs. The Product team OKRs are tracked as issues in the Product project.

The process for doing so is:

Prioritization

As this document and the direction page shows, there are a million things we want to do. So, how do we prioritize them and schedule things properly? Roughly speaking, we balance the following priorities:

  1. Security fixes and data-loss prevention
  2. Regression fixes (things that worked before including major performance regressions)
  3. New features, technical debt, community contributions, and all other improvements

Issues like security come in different severity levels. Lower severity means a lower priority, at ~S4/~P4 their priority is no different then other feature proposal.

Any new feature will have to meet the following requirements:

  1. It is technically viable
  2. The technical complexity is acceptable. We want to preserve our ability to make changes quickly in the future so we try to avoid complex code, complex data structures, and optional settings.
  3. It is orthogonal to other features (prevents overlap with current and future features).
  4. The requirements are clear.
  5. It can be achieved within the scheduled milestone. Larger issues should be split up, so that individual steps can be achieved within a single milestone.

New features are prioritized based on several factors:

Every release of GitLab has to be better than the last. This means that bugs, regressions, security issues, and necessary performance and architecture changes always take up whatever capacity they require to ensure GitLab remains stable, secure and fast.

We hope to realize our vision, while making sure we're building things that our customers want. In practice this means that we aim to ship features that align with our vision, but also solve problems our customers have. These features bring the product forward, and build value for the largest group of people possible. For example, issue relationships is a highly requested feature that also fits neatly within our vision. Everyone will benefit from this.

In practice, it is not possible to always ship things that only fall within our vision. Other changes are prioritized and scheduled based on demand. An example would be a specific form of authentication that is only used in particular organizations. This is not a big win to all our customers, but if it's not too much work, it can be a very big win to a subset of customers. Demand can also come internally, such as things that'll help GitLab achieve goals within a team or specifically drive business goals such as specific EE features.

We take all priorities in account when planning and scheduling larger initiatives across the teams (such as: "we're integrating CI, so everyone has to contribute to this in some way"). Our teams always self-manage priorities with an eye towards global optimization. Still, most changes are scheduled at a team-level, like: "make issues faster", or "add a new way to schedule pipelines".

Community Considerations

GitLab is open-source, and encouraging and promoting a large ecosystem of contributors is critical to our success. When making prioritization decisions, it's important to heavily weight activities which will encourage a stronger community of contributors. Some of those activities are:

Example

To make it clear with an example, the CI/CD team might ask:

Milestones

We schedule an issue by assigning it a milestone; for more on this see Planning a Future Release.

Working with Your Group

As a product manager, you will be assigned as the stable counterpart to a single group. At GitLab we abide by unique, and extremely beneficial guidelines when interacting with our groups. These include:

  1. Product Managers are the DRI for all prioritization within their group including bug fixes, security issues, feature, tech debt, and discovery. They alone determine and communicate priority. The process for doing so is documented and standard across all groups.
  2. Product Managers provide the what and when, Engineering (UX, Backend, Frontend, Quality) provide the how. This process is documented as part of our monthly product, engineering and UX cadence. We define stable counterparts for each of these functions within a group.

As an all-remote company, our crispness when it comes to responsibilities throughout the Product Delivery process was born out of necessity, but it pays untold dividends. Some of the benefits include:

From Prioritization to Execution

As described above, prioritization is a multi-faceted problem. In order to translate the priorities of any given group into action by our engineering teams, we need to be able to translate this multi-faceted problem into a flat list of priorities for at least the next release cycle. Product Managers are responsible for taking all these prioritization considerations and creating a clear, sequenced list of next priorities. This list should be represented as an issue board so that each team has a clear interface for making decisions about work. From this list, Engineering Managers and Product Managers can work together to determine what items will be selected for work in the immediate future.

This does not mean that items will be addressed in strict order - EMs and PMs need to be cognizant of dependencies, available skillsets, and the rock/pebbles/sand problem of time management to make the best decisions about selecting work.

Prioritizing for Global Optimization

Individual product managers must consider, and advocate for global optimizations within the teams they are assigned to. If your assigned team requires expertise (remember everyone can contribute) outside the team you should make all reasonable efforts to proceed forward without the hard dependency while advocating within the product management team for increased prioritization of your now soft dependencies.

If you have a request for additional help within your group, it is your responsibility to advocate for it. It's important to avoid generic "we need another Developer in X group" statements. Instead, create an issue which includes a concrete list of critical issues for no more than the next three months (example).

These issues should all be considered "top priority" and generally fall in one of the following three categories:

Include your proposal for other issues and groups outside of your own which should be considered a lower priority. Once you've reviewed the issue with your assigned Engineering Manager - ping your Product and Engineering Directors for review and refinement. If a global optimization which spans beyond your Department leaders is required, then the Senior Director of Engineering, VP of Product and VP of Engineering should be pinged.

Private tools and dashboards for monitoring and KPI tracking

These information sources may be useful to help you prioritize.

Managing creation of new groups, stages, and categories

As GitLab grows we will need to create new groups, stages, and categories. During this transition period we need to globally optimize, and ensure that important issues are not blocked during the creation of a new group.

There are three common scenarios which may encounter these transition periods:

In each of these scenarios, a Group may become temporarily responsible for a future Group's issues and backlog. During this time, the responsible Group should balance the needs of our users and organization, prioritizing across the common backlog.

Splitting a Stage into multiple Groups

As the group(s) working on a Stage grow in size, a new Group may need to be formed so group sizes remain manageable. For example, today there is a single group for Manage, but will be splitting into control and framework groups.

To prepare for splitting a Stage into multiple Groups, we should:

  1. Update categories.yml and stages.yml, assigning each Group a set of Categories
  2. Ensure all issues remain labelled with the Stage name, like devops:manage
  3. Ensure all issues also have a group label, like Control or Framework
  4. Prior to the new groups being formed, the PM and EM prioritize the shared devops:manage backlog

Once the first PM or EM is hired, the new Group should be formed:

  1. The other PM/EM's will need to continue working across both Groups. For example if a backend EM is hired, the frontend EM and PM will continue to work across both Groups until additional hires are made.
  2. EM's and engineers should work together and divide the existing engineering team to staff the new groups, like Control and Framework. Ideally, each group would have at least two backend engineers, but that is not always possible.
  3. Update stages.yml and team.yml to reflect the current group members.

As the rest of the EM/PM's are hired, they take over that role for the respective group.

Adding a new category to a Stage

The categories within a Stage will change over time, based on GitLab's direction and the market landscape. The groups within a Stage will need to be able to handle these changes, without issues falling in the cracks.

When the categories change, we should:

  1. Update categories.yml and stages.yml, ensure all categories are assigned to a Group
  2. If two categories are merging, apply the new category label to issues from both of the old categories
  3. If a new category is being added, create a new category label and apply it to relevant issues
  4. Update category epics to reflect the new labels and categories
  5. Review the handbook and other material which may link to old categories
  6. Remove old category labels

Adding a new Stage

When GitLab decides to address additional needs within the single application, a new Stage may need to be created. For example, Defend may be created to address additional needs beyond what Secure focuses on.

When a new Stage is added, and its Group has yet to be formed, we should:

  1. Ensure all issues for the new Stage are assigned with the Stage labels, like devops:defend and Defend
  2. Identify an existing Group, like Secure, which will be initially responsible for the new Stage
  3. The existing Group will prioritize across a common backlog of both Stages, in this example devops:defend and devops:secure
  4. Update categories.yml and stages.yml, listing the new Stage with the members of the existing responsible Group

Once the first PM or EM is hired, a new Group for the Stage should be formed:

  1. The other PM/EM's will need to continue working across both groups. For example if a backend EM is hired, the frontend EM and PM will continue to work across both groups until additional hires are made.
  2. EM's and engineers should work together to staff the new Group, like Defend. Each Group should have at least two backend engineers.
  3. Now that the new Group is formed, both Groups can focus on their respective Stages. In this case, Secure on Secure and Defend on Defend.
  4. Update stages.yml to reflect the new Group and its members.

As the rest of the EM/PM's are hired, they take over that role for the new Group.

Planning and roadmaps

As a PM, you must plan for the near term (more detailed) as well as for the long term (more broad). Together, these form a nearsighted roadmap. This will enable you to efficiently communicate both internally and externally how the team is planning to deliver on the product vision.

Stage vision

You need to create and maintain a vision for your stage of the DevOps lifecycle through the medium-to-long term of 1-2 years. This lives in a page linked from the direction page, e.g. /direction/create.

Your long-term vision should be more concrete for things that are closer in time, and vice versa. The format of the 2018 vision is a great way to structure your vision. You're free to do otherwise, just make sure it's easily consumable from the website.

The purpose of this page is to make it clear in what greater context individual changes fall. E.g. you might deliver a feature that allows admins to track username changes. That is not very interesting and hard to sell - but if it's clear that this is part of a greater push to improve auditing in GitLab, this becomes an enticing part of a greater whole.

The vision for the stage should also include:

  1. A list of categories within your stage with a brief description and link to the category vision epic.
  2. A link to a YouTube video recording of you presenting your vision updated in the last three months.

Category vision

Create and groom epics for each of the categories within your group. When creating these epics, it's important to focus your time and attention on specific actions and future iterations. It's natural to want to spend significant effort predicting the future, but iteration is one of our primary values and that applies to category visions as well. Your category visions should contain short paragraphs with lots of references to specific issues. Here is an example. While we cannot create epic templates, below is the markdown template to use for category vision epics:

Category Label: ~"ADJUST LABEL" | [ADJUST - Issue List]() | [ADJUST - Overall Vision]() | [ADJUST - Other Links]()

## Description
<!-- A good description of what your category is. If there are
special considerations for your strategy or how you plan to prioritize, the
description is a great place to include it. Please include usecases, personas, 
and user journeys into this section. -->

## Target audience and experience
<!-- An overview of the personas involved in this category. An overview 
of the evolving user journeys as the category progresses through minimal,
viable, complete and lovable maturity levels.-->

## What's next & why
<!-- This is almost always sourced from the following sections, which describe top
priorities for a few stakeholders. This section must provide a link to an issue
or [epic](https://about.gitlab.com/handbook/product/#epics-for-a-single-iteration) for the MVC or first/next iteration in
the category.-->

## Competitive landscape
<!-- The top two or three competitors, and what the next one or two items we should
work on to displace the competitor at customers, ideally discovered through
[customer meetings](https://about.gitlab.com/handbook/product/#customer-meetings). We’re not aiming for feature parity
with competitors, and we’re not just looking at the features competitors talk
about, but we’re talking with customers about what they actually use, and
ultimately what they need.-->

## Analyst landscape
<!-- What analysts and/or thought leaders in the space talking about, what are one or two issues
that will help us stay relevant from their perspective.-->

## Top Customer Success/Sales issue(s)
<!-- These can be sourced from the CS/Sales top issue labels when available, internal
surveys, or from your conversations with them.-->

## Top user issue(s)
<!-- This is probably the top popular issue from the category (i.e. the one with the most
thumbs-up), but you may have a different item coming out of customer calls.-->

## Top internal customer issue(s)
<!-- These are sourced from internal customers wanting to [dogfood](https://about.gitlab.com/handbook/product/#dogfood-everything)
the product.-->

## Top Vision Item(s)
<!-- What's the most important thing to move your vision forward?-->

In order to filter and recognize these epics more easily, you can label them with product category, the Team label, the Stage label, and the label for the given category (e.g., sast).

You must keep these categories in sync with categories.yml and for new categories, link to the category epic from the alt_link in categories.yml. Adding the category epic as the alt_link will automatically create links in the home page and the categories page so people have an understanding of what each new category really means.

Of course for categories that have already shipped, and that have a marketing product page, categories.yml should link to the product page, and the product page should then have a link to the category epic (you can see an example for GitLab Pages with a Vision button here). You should also, of course, link to your category epics from your stage vision page.

It's okay if your vision changes over time. Ideally, what you'll change are minor things: links, issues, smaller features. Large, strategic initiatives are unlikely to change frequently - when they do, it's probably worth talking about. See the categories.yml file itself for more information about formatting and available values.

3-month roadmap

In order to plan effectively around releases, as a PM you should have a detailed 3-month roadmap at all times. The issues contained in this near-term roadmap are the ones you should be spending the most energy on (fleshing them out, adding detail, discussing, etc). These issues will go through a refinement period where Product, Engineering, UX, and other parties will discuss the proposal until a proper MVC proposal is reached (see Contents of an MVP for more detail). Most of the communication should happen within the issue comments, but some may happen offline (such as via Slack). Ensure that any relevant information that arise as part of an offline conversation is added to the issue title and issue description. As a PM you must ensure that issues have enough detail added to them before they become actionable as part of an iteration.

The near-term roadmap will also help planning for capacity with engineering and UX in order to commit to the contents of the next release.

Sensing Mechanisms

Our ability to iterate quickly is a measure of our efficiency, but our effectiveness is just as critical. As a product manager you are critical to us not just working correctly, but working on the correct things. You do that by prioritizing appropriately. Your prioritzation decisions will be enhanced if you maintain a sufficient understanding of the context in which you make them.

There is no limit to the amount of inputs you can utilize for making prioritization decisions. For new PMs consider this guidance (in no particular order) for places to ensure you are plugged in to maintain sufficient context.

Special consideration

The roadmap should also delimit which items will be delivered prior to the next summit, as well as prior to the end of the current calendar year. These delimitations will help determine both the internal and external communication for both product and marketing.

Managing Upcoming Releases

Refer to the Product Development Timeline for details on how Product works with UX and Engineering to schedule and work on issues in upcoming releases.

Planning for Future Releases

Product Managers assign milestones to issues to indicate when an issue is likely to be scheduled and worked on. As we consider more distant milestones, the certainty of the scope of their assigned issues and their implementation timelines is increasingly vague. In particular, issues may be moved to another project, disassembled, or merged with other issues over time as they bounce between different milestones.

The milestone of an issue can be changed at any moment. The current assigned milestone reflects the current planning, so if the plan changes, the milestone should be updated as soon as possible to reflect the changed plan. We make sure to do this ahead of starting work on a release. Capacity is discussed between the PMs and the engineering managers.

In general, closer-to-current-time milestones are assigned to issues that are higher priority. The timing also reflects an approximate product roadmap, with more distant milestones reflecting increasing uncertainty.

The milestones are:

These assigned milestones should be used as a signal for GitLab stakeholders and collaborators, to help them with their own respective workflows.

In addition, we have two special milestones: Backlog and Awaiting further demand. Product Managers assign these issues to milestones that they have reviewed and make sense, but do not fit within the upcoming release milestones due to either a lack of comparitive urgency or because we have not yet seen enough user demand to prioritize the item yet. The best way to demonstrate urgency on either of these items is to vote on them and, if possible, add comments explaining your use case and why this is important to you.

Again, the milestone of an issue can be changed at any moment, including for both of these special milestones.

For a detailed timeline, see the product development timeline.

Shifting commitment mid-iteration

From time to time, there may be circumstances that change the ability for a team to ship the features/issues they committed to at the beginning of the iteration. When this happens, as a PM you must ensure the related issues and the roadmap are updated to reflect the new plan (for example, remove deliverable tag, update milestone, etc.). Additionally, notify your manager of the shift and update the kick-off document to reflect the status of the item within the iteration (merged, not merged).

Utilizing our design system to work autonomously

Our design system provides the means to work autonomously, without always needing UX insight and feedback. When problems can be solved using an already documented paradigm, you don't need to wait for UX approval to bring an issue to a reasonable state within a first iteration.

If lingering questions remain, subsequent iterations can address any shortcomings the feature might have.

Introducing a breaking change in a minor release

As a product manager, you should carefully consider the costs and benefits when planning to introduce a breaking change. Breaking changes may heavily impact existing users, and it is your responsibility to minimize the negative effects.

If you want to introduce an urgent breaking change in a minor release (e.g. you need to provide support for a new feature that cannot be backward compatible), you have to consider how many users will be affected by the change, and whether the change can wait until the next major release instead.

If you evaluate that the impact on users is acceptable (e.g., you have evidence that the feature is not used significantly), and the change will allow many users to benefit of new features or to solve problems, follow this process:

  1. Create an issue to discuss the breaking change, describing it in details including the impact and benefits
  2. Consider if you really need to do a breaking change in a minor. Can you wait for the next major release
  3. Communicate the breaking change as soon as possible, for example:
    • Publish a blog post about the upcoming change, with a timeline and a simple way to recognize who is affected, and who is not
    • Ask to schedule tweets about the blog post in the #twitter Slack channel
    • Ask to reach out customers that may be affected by the change in the #customer-success and #sales Slack channels
    • Mention the problems customers may report and how to address them in the #support_self-managed and #support_gitlab-com Slack channels
  4. Throughout this process, think like a customer. Figure out actions that could make the breaking change less painful from their point of view.
  5. Always keep the issue up-to-date

Communication

Communication guidelines for product managers

As a product manager, you're vastly more knowledgeable about GitLab than others. This means that you have the responsibility to always provide a balanced and complete view when discussing anything related to product. Other people won't have the same background and context you might have.

For example, when someone involved in sales asks you about upcoming issues in a particular area, you would respond with:

This seems obvious, but a slight misunderstanding can have big consequences, for example: promising a customer that something will be done by a certain date is very different than indicating that we're working on something and hope to have a first iteration in the near future.

Internal and external evangelization

Before shipping a new or updated feature, you are responsible for championing it, both internally and externally. When something is released, the following teams need to be aware of it as they will all need to do something about it:

You can promote your work in several ways:

GitLab University

To promote a major new feature internally, you can ask to host a GitLab <– internal promotion, but GitLab University is external? –> University, a company wide demo session. This is a great opportunity to make sure every one is on the same page.

Communicating product vision

Occasionally, we rally around a product vision, a direction to aim towards, to improve alignment internally and externally. We usually start out with a clear, simple concept like going faster from idea to production, or shipping complete DevOps. We announced our first Master Plan as part of our Series B funding announcement, and our second master plan with our Series C announcement. While the first iterations and presentations are great for aligning the product team and announcing the vision to the world, the text and slides only go so far to convey the depth of the vision. So, we usually iterate on the vision by fleshing it out more in various stages and communicating it in different ways, usually increasing fidelity over time.

This iteration may look like this, for example:

The interactive prototype video is a good time to reiterate the vision with a blog post.

Additionally, the direction page contains the specific vision for each devops stage along with links to the epics that contain the work to be done. We aim to use these epics and issues as the single source of truth for our plans, and as such we strive to maintain them up-to-date with the latest developments and plans.

Working with Product Marketing (PMM)

Product marketers and managers should be joined at the hip. Just as a feature without documentation should not be considered shipped, benefits of GitLab that we're not actively talking about might as well not exist.

Product marketers rely on product managers to be guided to what is important and high impact. In general, you should:

Marketing materials

As a PM you're responsible for making sure changes you've shipped are well represented throughout GitLab's documentation and marketing materials. This means that on release, features.yml is updated, documentation is merged and deployed, and any existing content is updated where necessary.

It's not acceptable to do this after the release. GitLab is very complex, and features and functions are easily missed, even those that provide significant value to customers (e.g. the many ways you can authenticate with GitLab).

You can recruit the help of the marketing and technical writing team if needed, but it's highly recommended to do small updates yourself. This takes less time and overhead than communicating what needs to be done to someone else.

Major feature rollout

Major features deserve proper attention from Product and Marketing. With a proper rollout, we'll have ample marketing opportunities and receive more feedback ahead of, during, and after the release.

Here is the ideal rollout schedule. For each step there is an indication for who is responsible for it.

  1. Feature is drafted in an issue (PM)
  2. Feature is planned in an upcoming release (PM)
  3. A feature proposal blog post is made (PM or Dev), which includes:
    • What we are planning on doing.
    • How people will be able to get it: CE or any EE Editions.
    • A link to the issue.
    • When it'll be available, if possible.
    • Anything else that is interesting to share in order to fuel the discussion.
  4. Feature is implemented, and documentation is written (Dev).
  5. Feature should appear on the website (Marketing)
    • For very significant features: Feature page on the website is made and pushed, with the mention "Available from X.X"
    • For other features: Feature should be listed on some page (/devops-tools, Enterprise page, /features page).
  6. Feature is launched with the release (Marketing)
    • "Available from X.X" is removed
    • Documentation and other resources are linked
    • Pricing page is updated if needed
  7. Feature is highlighted in a blog post (Marketing)
    • This post is linked from the feature page on the website (if applicable)

Release posts

As a PM, you are accountable for adding new features (under your umbrella) to the monthly release post, respecting the guidelines defined in the release posts handbook and its due dates. Be sure to go over all the details.

Every month, a PM will take the leadership of the release post, and will be responsible for delivering it in time.

Writing release blog posts

For every monthly release, there is a blog post announcing features. The blog post should contain everything exciting or disruptive. All new features should appear in the blog post. We want to help people understand exciting features (which are often new), and increase adoption. Disruptive features may change workflows or even introduce unavoidable inconveniences. We want to anticipate questions and avoid confusion by communicating these changes through the blog post. Smaller tweaks and bug fixes don't necessarily need to be mentioned, but if interesting, can be included at the bottom of the post.

Writing about features

As PM we need to constantly write about the features we ship: in a blog post, internally to promote something, and in emails sent to customers.

While we want every PM to have a unique voice and style, there are some guidelines that one should take into account when writing about features. Let's highlight them with a concrete example, Preventing Secrets in your repositories, that we shipped in 8.12.

It's a bad idea to commit secrets (such as keys and certificates) to your repositories: they'll be cloned to the machines of anyone that has access to the repository. If just a single one is insecure, the information will be compromised. Unfortunately, it can happen quite easily. You write git commit -am 'quickfix' && git push and suddenly you've committed files that were meant to stay local!

GitLab now has a new push rule that will prevent commits with secrets from entering the repository.

Just check the checkbox in the repository settings, under push rules and GitLab will prevent common unsafe files such as .pem and .key from being committed.

Stakeholder Management

Updated SSOT for stakeholder collaboration

Stakeholder collaboration and feedback is a critical competitive advantage here at GitLab. To ensure this is possible, and facilitate collaboration, you should maintain an updated single source of truth (SSOT) of your stage direction, category visions, and roadmap, at all times. This equips anyone who wants to contribute to your stage’s product direction with the latest information in order to effectively collaborate.

Actively and regularly reach out to stakeholders. Encourage them to view and collaborate on these artifacts via these (non-exhaustive) opportunities:

Here is some guidance for new PMs to ensure your stage direction, category visions and roadmap are up-to-date and visible to critical stakeholders:

Customer meetings

It's important to get direct feedback from our customers on things we've built, are building, or should be building.

As a PM you should have regular meetings with customers that are using the things you've been working on, and also with customers that are not, in order to get an idea of why they're not switching to our solution.

One technique is to take the top 3 competitors in each stage and talk to customers using that competitor asking: What is missing to have you switch from X to us? We’re not aiming for feature parity with competitors, and we’re not just looking at the features competitors talk about, but we’re talking with customers about what they actually use, and ultimately what they need.

Another technique is to schedule specific "customer discovery" calls with users from key customers of your group's categories and features. Solicit them for what they love about the features and ask about their current pain points with both the features as well as the surrounding workflows when using those components of GitLab?

Regardless of your technique, be sure to share what you've learned in customer meetings with the broader product team in #product.

Set up a meeting

To set up a customer meeting, identify what you're interested in learning and prepare appropriately.

You can find information about how customers are using GitLab through Sales and version.gitlab.com. Sales and support should also be able to bring you into contact with customers.

There is no formal internal process to schedule a customer meeting, but if the need arises, we can formulate one.

During and after

During the meeting, spend most of your time listening and obtaining information. It's not your job to sell GitLab, but it should be obvious when it's the time to give more information about our products.

After the meeting, make sure all your notes and feedback land in issues.

Customer Advisory Board Meetings

One specific, recurring opportunity to get direct feedback from highly engaged customers is the GitLab DevOps Customer Advisory Board. You may be asked by the CAB to present your stage at these meetings. Here are some guidelines when doing so:

Working with (customer) feature proposals

When someone requests a particular feature, it is the duty of the PM to investigate and understand the need for this change. This means you focus on what is the problem that the proposed solution tries to solve. Doing this often allows you to find that:

  1. An existing solution already exists within GitLab
  2. Or: a better or more elegant solution exists

Do not take a feature request and just implement it. It is your job to find the underlying use case and address that in an elegant way that is orthogonal to existing functionality.

This prevents us from building an overly complex application.

Take this into consideration even when getting feedback or requests from colleagues. As a PM you are ultimately responsible for the quality of the solutions you ship, make sure they're the (first iteration of the) best possible solution.

Competition Channel

When someone posts information in the #competition channel that warrants creating an issue and/or a change in features.yml, follow this procedure:

How and when to reject a feature request

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.

However, as the number of issues and merge requests grows incessantly, we should be diligent about rejecting features we are sure will not work out. It's better for everyone: for the product team, so we don't maintain a huge backlog of things we will never do anyway, and for the users who won't have to wait for our feedback indefinitely.

Note: it's fine to not respond to issues that we think have potential until they gather momentum.

Feature requests and merge requests can be rejected for the following reasons:

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.

Analyst Engagement

Part of being a product manager at GitLab is maintaining engagement with analysts, culminating in various analyst reports that are applicable to your stage. In order to ensure that this is successful and our products are rated correctly in the analyst scorecards, we follow a few guidelines:

It's important to be closely connected with your product marketing partner, since they own the overall engagement. That said, product has a key role to play and should be in the driver's seat for putting your stage's best foot forward in the responses/discussions.

Internal customers

Product managers should take advantage of the internal customers that their stage may have, and use them to better understand what they are really using, what they need and what they think is important to have in order to replace other products and use GitLab for all their flows.

We want to meet with our internal customers on a regular basis, setting up recurring calls (e.g., every two weeks) and to invite them to share their feedback.

This is a mutual collaboration, so we also want to keep them up to date with the new features that we release, and help them to adopt all our own features.

Dogfood everything

The best way to understand what pains users experience is to go through what we ask them to do to set up or use GitLab. As a PM, you should go through every feature, at the minimum the ones you are responsible for. All of them. That includes features that are not in GitLab's UI directly but require server configuration. If you, as a PM, can't understand the documentation, or if you struggle to install something, would anyone else bother to do it too? Going through this is not only beneficial for understanding what the pain points are, it will also tell you what can be enhanced, such as a better flow or better documentation.

As a Product function, it is our responsibility to ensure that the entire company is dogfooding. We do this by:

  1. Maintaining a set of internal stakeholders who represent GitLab team members who use GitLab for the purposes of developing and operating GitLab and GitLab.com.
  2. Including top internal customer issues in the relevant category epics.

More than just using the features ourselves as Product Managers, internal usage of GitLab by our teams has an outsized impact. This impact includes:

The impacts are not only outsized, but they are more likely to materialize quickly. That is because working with internal stakeholders comes with the additional benefit of having immediate feedback. We can reduce cycle times with more actionable feedback to de-risk early investments in new categories and features by having a strong internal stakeholder dogfooding early. Due to these impacts, a general rule of thumb is to evaluate an internal stakeholder request as 10x a customer request.

It's because of this outsized impact that, all other factors being equal, we should choose to more highly prioritize issues requested by internal stakeholders. Similarly, when internal customers are evaluating whether to dogfood, we should use the following process to confirm the outsized impact is being considered:

  1. Internal stakeholder creates an issue for the relevant group.
  2. Internal stakeholder applies the internal customer label and mentions the relevant Product Mananger.
  3. Product Manager prioritizes appropriately and provides an estimate when the feature will be delivered.
  4. Internal stakeholder determines whether the timeline is acceptable.
  5. If not the internal stakeholder team should use the '2x' rule to evaluate whether they should build the tooling inside of GitLab themselves. If the effort will take a team twice as long, but it resides in our product at the end they should build it within GitLab.
  6. If the internal stakeholder chooses to build tooling outside of the product they should add a note justifying why they are choosing to do so on the issue.

We should strive that less than 10% of internal stakeholder requests aligned to our product vision choose to build tooling outside of our product.

Here is a partial list of features and functionality that currently exist outside the GitLab project, that should be brought inside. Note: use the Rebuild in GitLab label to add an issue to this backlog.

Example: configuring GitLab

Most of GitLab is configured through the file gitlab.rb. It's tempting to add a new parameter in this file - it's easy, fast to do, and won't require adding a new UI element to allow the configuration of this new setting. However, changing this file requires you to reconfigure GitLab. To do that, you have to login to your server and type in commands to reconfigure your instance, possibly multiple times if you have more than one server.

This is not something that we can ask our customers to do. Only by using your own product and features will you realize that some practices should be avoided as much as possible.

Issues & Epics

When to create an issue

You should create an issue if:

You should consider not creating an issue when:

Issue state

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

When closing an issue for this reason, make sure to update the issue body and leave a comment explaining why the issue is being closed. Issues can be reopened if we change our stance on them.

When to close an issue

In order to clearly communicate to our stakeholders our plans, 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 visions, it starts with issues:

As a Product Manager you should close issues that are:

  1. duplicated elsewhere.
  2. no longer relevant due to other reasons.
  3. 'not the next iteration': an iteration on a proposed feature that is unlikely to ship in the next few months.
  4. 'won't do': An issue that we have no intention on implementing because it does not fit within or is antithetical to our vision, it presents a security risk or other reasons you outline in the issue.

When closing an issue, leave a comment explaining why you're closing the issue and link to anything of relevance (the other duplicate, the original feature that this is an iteration on, etc).

The 'not the next iteration' issues are the most important ones to resolve. It is very easy to create a big plan with meta issues and lots of improvements, but it is essential that we iterate and ship the minimum viable change. We have to ship the iteration, wait for it to be used, and look for the 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 issues. Come up with a plan but only record the first step. This way we can preserve the efficiency of our value of iteration. Closing issues whenever possible is an important part of your job and helps to keep a clear view of what is next. Consider using the following template to close an issue:

Closing this because XXX is something we should do first. When that feature is finished, we can learn from observing it in use. If we learn that this issue is still relevant, we can then reopen it. See /handbook/product/#when-to-create-or-close-an-issue for more detail about this policy.

How to submit a new issue

  1. If you have time, the first thing you should do is search both CE and EE projects to see if a similar issue already exists. We shouldn't create duplicates if we can avoid them.
  2. Identify if the issue is about GitLab Community Edition (CE) or GitLab Enterprise Edition (EE), although this can easily be changed later.
  3. You should clearly state what the current pain point is, what we are trying to solve, what the benefits will be, what it should do, how to accomplish that and the next steps.
  4. The body of the issue should be written in a clear way, without ambiguity.
  5. The initial issue should be about the problem we are solving. If a separate product discovery issue is needed for additional research and design work, it will be created by a PM or UX person.
  6. If the body contains too many paragraphs, it can surely be rewritten to be shorter.
  7. Do not use acronyms or abbreviations. Everyone should be able to jump on the issue and participate without needing a glossary.
  8. Choose labels which are relevant to the issue. If you are unsure about what certain labels are for, check the labels pages (CE or EE), and read the descriptions. The contributing doc provides a breakdown of the label types and how to choose the right label.
  9. Unless you know what you are doing, 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
  10. Mention the different stakeholders in the body of your issue. In most product related issues, we usually mention the product manager, the design, frontend, and backend managers as appropriate. Some teams have experts or liaisons that can be mentioned instead of the managers. Mentioning the people in the body of the issue 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).

How to use 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 vision epic or a meta epic.

Epics for a long-term plan

We 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 is useful to have an overview of the future so participants and observers can understand how the pieces fit together. It can be really useful to understand the context of where we think we’re going so we can do a good job with the MVC.

Also, it conveys confidence internally and externally that we understand what we need to do when the MVC is particularly minimal. But don't get too caught up in long-term epics as you risk making proposals too complex, and overrepresenting certainty in the solution. Don't work too far in the future; we'll know better once we ship something small.

When creating a vision epic, there's a natural tendency to capture it as quickly as possible and then move on, but we must always strive to create a more specific epic for the first iteration, or the next iteration if something already exists. Describing an MVC means that the community can contribute more easily. Also, after distilling things down to a first iteration, you might realize it’s a lot easier than you thought, and prioritize it earlier. You can have an MVC without a Vision. But you can't have a Vision without an MVC.

Epics for a category vision

See category vision.

Product Discovery Issues

When a product discovery step is needed to design a feature, PMs should create a separate issue (linked to the epic and implementation issue) for that research and design work to occur. We should not repurpose or otherwise reuse the existing implementation issue; doing so creates a risk of the issue being closed when the design work is complete and thereby losing track of the actual delivery of the item.

It's also important to ensure that product discovery issue is really even needed. It's possible in many situations to simply use the initial ticket for any design discussions - this will ensure all of the back and forth is in one place, avoiding the risk of losing track of parts of the discussion. If you find you are creating a issue simply to reserve time or people on the roadmap, consider trying to secure the capacity in another way.

In certain cases a product discovery issue can be worked ahead of time, but a best-practice for good product development is to plan for and do this sort of research and development work within the milestone, including engineering and other stakeholders directly. Doing product discovery ahead of time, without the full group is generally not an effective approach.. Because we aim to deliver MVC features, there should almost always be enough time in a single release to both research and deliver a feature that adds value for our customers.

Be sure to follow the CE contribution guidelines on correct labeling practices for the product discovery label.

Wireframes

When relevant, you can include a wireframe in your issues in order to illustrate your point. You don't need to include wireframes on your own; our UX/design team can help us on that matter. Simply ping them if you need their help. We like Balsamiq for its simplicity and its sketch-style approach. If are struggling for inspiration, you can also paste screenshots of similar features in other products.

What is a Meta issue?

We assign the Meta label to issues that contain a large list of todos. If you are familiar with the Agile methodology, it's similar to an epic. At GitLab we have a short release cycle: the 22nd of every month. In some cases we won't be able to tackle all the tasks of a meta issue in a single release. This is why we centralize everything that we need to do in a meta issue, then break it down to issues small enough that they will fit into one release. Most of the time, meta issues generate lots of comments and passionate discussions. As a consequence, they always lead to something great.

Meta issues themselves generally should not be assigned to a milestone as the actual work is covered in sub-issues. Sometimes, for example if you want a meta issue to show up in our direction page for a given release, you may add a milestone, but only if you know for sure that all sub-issues will be completed by that milestone. Don't assign a milestone for when you're going to start a meta issue.

Long-lasting issues

A general guideline is that an issue should only span one release. If we know an issue is going to span multiple releases, split it up into multiple issues.

Meta/epic issues are the exception to this rule, but should be kept to a minimum and only serve to guide broader subjects, not a single feature over multiple releases. This is to make sure we stick to our values of the minimally viable change. This means that feature issues should be closed after the first iteration whenever possible. We'll know more in the future and this keeps any remaining issues short and actionable.

In addition, it's often a good idea to throw away an original plan and start fresh. Try to do this more often, even more than you're comfortable with. Close the issue and create a new one.

Which issue should you be working on?

When you don't have any specific tasks assigned, you should work on issues that are labeled Product work, in both the EE and CE projects. These are issues that need our attention the most.

GitLab as a Product

Single application

GitLab is a single application, rather than a set of loosely connected components. This is a big advantage, read why here.

Consider opportunities to take advantage of this unique attribute in early iterations. Integrating features with different parts of the application can increase the adoption of early iterations. Other advantages:

Although not every feature needs to be integrated with other parts of the application, you should consider if there are unique or powerful benefits for integrating the feature more deeply in the second or third iteration.

GitLab.com

GitLab.com runs GitLab Enterprise Edition.

To keep our code easy to maintain and to make sure everyone reaps the benefits of all our efforts, we will not separate GitLab.com codebase from the Enterprise Edition codebase.

To avoid complexity, GitLab.com tiers and GitLab self-managed tiers strive to match 1:1.

Since we are not able to give admin access and do not yet have full feature parity between self-managed instances and GitLab.com, we avoid saying that there is a one to one match between subscription levels and tiers in marketing materials. This has been a source of confusion in the past for customers.

GitLab.com subscription scope and tiers

GitLab.com subscriptions work on a namespace basis, which can mean:

This means that group-level features are only available on the group namespace.

Public projects get Gold for free. Public groups do not get Gold for free. Because:

Admittedly, this is complex and can be confusing for product managers when implementing features. Ideas to simplify this are welcome (but note that making personal namespaces equal to groups is not one of them, as that introduces other issues).

Talking about Paid-only decisions

When talking about why a certain change goes into a Paid tier instead of Core, mention the stewardship page in the handbook directly and link to it.

Stewardship

Our stewardship of the open source project that is GitLab Community Edition is incredibly important. We are expected to act as good stewards and have to work hard to maintain that right, which is documented on the stewardship page.

If you want to make any changes to this page, create a merge request and assign it to the CEO.

What goes in what paid tier

Please see The likely type of buyer determines what features go in what tier.

Starter, Premium, and Ultimate requirements

All Starter, Premium, and Ultimate features must:

Pricing plans

For more information about how we think about pricing, please see the pricing page in the handbook.

Designing features for paid tiers

To make it possible to ship a feature for paid tiers, ideally the code is completely separate. For example, the frontend and backend of the feature only exist in the gitlab-ee project. However, this is not always possible.

In cases where it's preferable to have the backend code live in the gitlab-ce repository, it's acceptable to only ship the frontend for the feature in EE. In practice this makes the feature paid-only.

Bringing features to lower tiers

If you are considering bringing a feature that exists in Premium to Core, for example, follow this process:

After appropriate consideration, update all stakeholders on the decision that you've made and move forward with making that change (or simply close the issue with the reasoning for why not).

Alpha, Beta, GA

Occasionally we need to test large, complex features before we are confident that we'll be able to scale, support and maintain them as they are. In this case we have the option to release them as Alpha or Beta versions.

In general, we should avoid releasing Alpha or Beta versions of features. A minimally viable change should be viable and therefore should not need a pre-release. That said, if there is a situation where we have no valid alternative, the definitions of each stage is below.

It's never acceptable to make changes that risk any damage to existing production data accessed by our users.

Alpha

Closed Beta

Similar to Beta, but only available to selected users.

Beta

Generally Available (GA)

Passed the Production Readiness Review for GitLab.com, which means that it is:

Discouraging, deprecating and removing features

Deprecating features (changes) follows a particular pattern. Use the language Discouraged (maintained), Deprecated (not maintained) or Removed to specify the state of a feature that is going to be or is removed.

Features that are discouraged, deprecated or removed should be:

  1. Labelled accordingly in the documentation
  2. Labelled accordingly in the application

Features that are Deprecated or Removed should be removed from marketing pages.

Discouraged (maintained)

Deprecated (no longer maintained)

Removed

Naming features

Naming new features or renaming existing features is notoriously hard and sensitive to many opinions.

Factors in picking a name

Process

Renaming

The bar for renaming existing features is extremely high, especially for long-time features with a lot of usage. Some valid but not exclusive reasons are:

Permissions in GitLab

Use this section as guidance for using existing features and developing new ones.

  1. Guests are not active contributors in private projects. They can only see, and leave comments and issues.
  2. Reporters are read-only contributors: they can't write to the repository, but can on issues.
  3. Developers are direct contributors, and have access to everything to go from idea to production, unless something has been explicitly restricted (e.g. through branch protection).
  4. Maintainers are super-developers: they are able to push to master, deploy to production. This role is often held by maintainers and engineering managers.
  5. Admin-only features can only be found in /admin. Outside of that, admins are the same as the highest possible permission (owner).
  6. Owners are essentially group-admins. They can give access to groups and have destructive capabilities.

To keep the permissions system clear and consistent we should improve our roles to match common flows instead of introducing more and more permission configurations on each resource.

For big instances with many users, having one role for creating projects, doing code review and managing teams may be insufficient. So, in the long term, we want our permission system to explicitly cover the next roles:

  1. An owner. A role with destructive and workflow enforcing permissions.
  2. A manager. A role to keep a project running, add new team members etc.
  3. A higher development role to do code review, approve contributions, and other development related tasks.

All the above can be achieved by iteratively improving existing roles and maybe adding one more.

Documentation on permissions

Security Paradigm

You can now find our security paradigm on the Secure Vision page.

Also see our Secure Team engineering handbook.

Statistics and performance data

Traditionally, applications only reveal valuable information about usage and performance to administrators. However, most GitLab instances only have a handful of admins and they might not sign in very often. This means interesting data is rarely seen, even though it can help to motivate teams to learn from other teams, identify issues or simply make people in the organisation aware of adoption.

To this end, performance data and usage statistics should be available to all users by default. It's equally important that this can be optionally restricted to admins-only, as laws in some countries require this, such as Germany.

Not all instance-data is available to all users in GitLab yet. This issue and the epic above should solve this.

Internationalisation

GitLab is developed in English, but supports the contribution of other languages.

GitLab will always default to English. We will not infer the language / location / nationality of the user and change the language based on that. You can't safely infer user preferences from their system settings either. Technical users are used to this, usually writing software in English, even though their language in the office is different.

Performance

Fast applications are better applications. Everything from the core user experience, to building integrations and using the API is better if every query is quick, and every page loads fast. When you're building new features, performance has to be top of mind.

We must strive to make every single page fast. That means it's not acceptable for new pages to add to performance debt. When they ship, they should be fast.

You must account for all cases, from someone with a single object, to thousands of objects.

Read the handbook page relating to performance of GitLab.com, and note the Speed Index target shown there (read it thoroughly if you need a detailed overview of performance). Then:

Of course, you must prioritize improvements according to their impact (per the availability & performance priority labels). Pages that are visited often should be prioritized over pages that rarely have any visitors. However, if page load time approaches 4 seconds or more, they are considered no longer usable and should be fixed at the earliest opportunity.

Restriction of closed source Javascript

In addition, to meet the ethical criteria of GNU, all our javascript code on GitLab.com has to be free as in freedom. Read more about this on GNU's website.

Changing the Product handbook

This is the Product handbook. If you (a Product team member, a GitLabber, or anyone else) see any typos or small copywriting errors here, consider correcting them with a merge request and merging it yourself (provided you have merge permissions to this repository), and mentioning a Product team member afterward as a courtesy so that we can thank you, since we have a bias for action and trust your judgement. If you have a larger change (or don't have merge permissions), create a merge request and mention any Product team member for further review so that we can incorporate your change (if it makes sense) as soon as possible. Please don't assign anybody to the merge request.