---
layout: handbook-page-toc
title: 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](/handbook/product/how-to-engage) guide.

The document below talks about _how_ we do product at GitLab, not about _what_.
For the _what_, see [Product Direction](/direction/).

If you are a product manager looking to learn everything about being a PM at GitLab, this document is
broken into the following sections:

- [Product Principles](/handbook/product/index.html#product-principles) covers our guiding ideas about how to build the GitLab product.
- [GitLab as a Product](/handbook/product/index.html#gitlab-as-a-product) contains information about GitLab as a product and how we manage it.

Other important sub-pages of this one that are relevant include:

- [PM responsibilities and job details](/handbook/product/product-management)
- [PM process](/handbook/product/product-management/process)

## On this page
{:.no_toc .hidden-md .hidden-lg}

- TOC
{:toc .hidden-md .hidden-lg}

### Other Product Handbook pages
{:.no_toc}

* [Product Development Flow](/handbook/product-development-flow/)
* [How to Engage Product](/handbook/product/how-to-engage/)
* [Product Pricing Model](/handbook/ceo/pricing/)
* [Product Categories](/handbook/product/categories/)
* [Product Application Types](/handbook/product/application-types/)
* [Product Metrics](/handbook/product/metrics/)
* [Product Feature Instrumentation](/handbook/product/feature-instrumentation/)
* [Making Gifs](/handbook/product/making-gifs/)
* [Product Leadership](/handbook/product/leadership/)
* [Product Management README's](/handbook/product/readme/)
* [Product Communication](/handbook/product/communication/)

## Product Principles

The direction for the GitLab product is spelled out on the
[Direction page](/direction). This document provides lessons and heuristics on
how to design changes and new features. Our iterative process is demonstrated in
a [blog post](/blog/2017/01/04/behind-the-scenes-how-we-built-review-apps/).

Much of our product philosophies are inspired by the [Ruby on Rails doctrine](http://rubyonrails.org/doctrine/) of ['Rails is omakase'](http://david.heinemeierhansson.com/2012/rails-is-omakase.html). I highly suggest reading these.

### Enabling Collaboration

From development teams to marketing organizations, everyone needs to collaborate
on digital content. Content should be open to suggestions by a wide number of
potential contributors. Open contribution can be achieved by using a mergeable
file format and distributed version control. The [mission of GitLab](/company/strategy/#mission)
is to **allow everyone to collaborate on all digital content** so people can
cooperate effectively and achieve better results, faster.

### Bringing Ideas to Reality

Ideas flow through many stages before they are realized. An idea originates in a
chat discussion, an issue is created, it is planned in a sprint, coded in an
IDE, committed to version control, tested by CI, code reviewed, deployed,
monitored, and documented. Stitching together all these stages of the DevOps
lifecycle can be done in many different ways. You can have a marketplace of
proprietary apps from different suppliers or use a suite of products developed
in isolation.

### The Minimally Viable Change (MVC)

We only ship in a [Minimally Viable Product](http://ask.leanstack.com/en/articles/902991-what-is-a-minimum-viable-product-mvp) (MVP) style. We call it Minimum Viable Change (MVC), because our business model is focused on adding additional value to our integrated product suite, instead of building separate, new products.

MVC means we start by delivering the smallest possible solution that offers value to our users. To avoid [feature bloat](https://www.productplan.com/glossary/feature-bloat/), we rely on user research to validate whether our idea addresses a market need in a desirable way. This approach sets us up to expend the smallest possible amount of effort to build new capabilities, while learning more about how to best add additional functionality over time.

While an MVC may not have the robust functionality of a fully developed feature, it should still address fundamental user needs through a bug-free and highly usable experience. The minimally viable change should not be a [broken feature](https://blog.crisp.se/2016/01/25/henrikkniberg/making-sense-of-mvp).

Advantages of an MVC approach:

- It prevents over engineering.
- It forces everyone involved to look for the simplest solution to a problem,
which is often the best solution.
- It forces working towards an 80/20 solution. While competing products might cater
to the last 20% of the market, a minimally viable solution is _good enough_ for 80%.
- A bigger change is harder to review.
- A bigger change is harder to roll back.
- The bigger the change, the larger the risk of a conflict with someone else's contribution.
- The bigger the change, the longer it takes before everyone can benefit from the change.
- Further changes or enhancements to the change are driven by feedback from
actual users. This is a much more informative mechanism than the intuition
of a product person (though note that this doesn't mean we should just build
whatever feedback tells us).

### Iteration

An MVC approach is a byproduct of our spirit of iteration. Even when not pursuing an MVC, we will encourage iteration in our own development process. That means we [break problems down](/handbook/product-development-flow/#build-phase-1-plan) as [small as possible](/handbook/values/#make-small-merge-requests), use [throughput as a performance indicator](/handbook/engineering/development/performance-indicators/#throughput), and focus on [reduced cycle time](/handbook/values/#reduce-cycle-time).  Thinking iteratively is not always intuitive, and breaking certain topics or projects down can be challenging.  Here's a helpful [video](https://www.youtube.com/watch?v=zwoFDSb__yM) from our CEO with guidance on how to think more iteratively.

### Avoid "Not Invented Here" Syndrome

Just because something is [not invented here](https://en.wikipedia.org/wiki/Not_invented_here)
doesn't mean it doesn't have a perfect home within our solution. GitLab is an
Open Core product and is part of the broader ecosystem of Open Source tools in
the market. Every day there are new innovative tools out there that solve
real-world customer problems; we should not be afraid of embedding these tools
into our own products in order to solve those same problems for our customers
too. Leveraging existing technology allows us to get to market much more quickly,
to contribute to Open Source (and help strengthen Open Source as a whole), and
allows us to focus our own people on making GitLab itself better. Building
professional relationships with these tool creators also is a positive for GitLab
since they may have important user perspectives around your categories.

We have achieved many successes following this approach:

- [Code Quality](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html) in CI/CD pipelines by embedding [CodeClimate](https://codeclimate.com/)
- [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html) by using the [Unleash](https://github.com/Unleash/unleash) client library
- [Mobile publishing](/blog/2019/03/06/ios-publishing-with-gitlab-and-fastlane/) by writing about how to utilize [FastLane](https://fastlane.tools/) with GitLab

There are also many more examples throughout the company where this has been successful.
As a product manager you should be monitoring the world of Open Source as it
relates to your area to see where new innovative tools are being developed, and
not be afraid of integrating those. One thing to keep in mind, integrating could
be anything from a blog post describing how the tool works together with GitLab
all the way up to bundling it inside of our own installation, and this can
evolve iteratively.

### Convention over Configuration

As an application development tool, we understand the natural inclination to create an array of buttons to press and knobs to turn.

We believe however that more options are not necessarily better, and that our users are better served by an application with reduced complexity yet still contains the features they need.

#### Inspiration

We admire other convention over configuration tools like [Ruby on
Rails](http://rubyonrails.org/) (that doctrine of which perfectly describes the [value of integrated systems](http://rubyonrails.org/doctrine#integrated-systems)), [Ember](http://emberjs.com/), and
[Heroku](https://www.heroku.com/), and strive to offer the same advantages for a
continuous delivery of software.

Furthermore, Ruby on Rails has been of massive influence to the Ruby community.
Uplifting it, and making it more powerful and useful than ever before, for many
more usecases. We want GitLab to be to Kubernetes, what Rails is to Ruby.

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

#### Principles

When considering adding new configuration, we follow the following principles:

* **Ensure a great experience by default** - GitLab should work perfectly right out of the box for most users. While it should be resisted, sometimes configuration is inevitable or preferable. Your configuration must not make that [experience worse](https://gitlab.com/gitlab-org/gitlab/issues/14432) and should always _get out of the way of the user_.
* **Encourage favorable behaviors by limiting configuration** - 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.
* **Design for users not intermediaries** - GitLab should avoid falling into the [Blackboard trap](https://twitter.com/random_walker/status/1182637292869115904) of building a product that administrators of GitLab love because it is configurable, but developers and other users of GitLab hate because it is overly complex and confusing.
* **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 - preferably they should not be), and when necessary, automatically migrate existing users/groups/projects to have the new features ON. Similarly, feature flags should be consistently ON for both GitLab.com and self-managed users whenever possible. It is important to remember that vocal proponents of an issue that a Product Manager might interact with would likely be inclined to take the extra effort to enable a feature, but most users will not.
  * Default to ON can be rolled out incrementally. A feature can sometimes be activated within days via a feature flag on [GitLab.com](gitlab.com). Other times a feature can take months to prove that it has the performance enterprises need like we need to do for [Container Network Security](https://about.gitlab.com/direction/defend/container_network_security/).
* **Avoid Limits** - Limits should be in place to [protect the system](https://gitlab.com/gitlab-com/www-gitlab-com/issues/5617) but not to "slowly try out" a feature. By limiting the usefulness of a feature right from the start the only thing you are achieving is limiting its adoption and usefuleness. If you are going to default to OFF or limited, you must have a good, documented reason for this.
* **Avoid configuration completely when possible** -  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.
  * **Configuration builds up over time** - Every configuration option in GitLab multiplies its complexity, which means the application is harder to use, harder to develop, and less friendly to users.
  * **Configuration is hard to remove** - Removing a configuration after it shipped and in use is much more work than not introducing it in the first place. This is because you change the behavior for customers that selected the less popular option.
  * **Configuration is an expensive testing mechanism** - 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](https://xkcd.com/927/) to maintain going forward. Adding a configuration is a [one way door](/handbook/values/#make-two-way-door-decisions) that should be avoided if possible. As a result, consider using feature flags instead of configuration.

#### Always Allow for Deploying to Production

Sometimes fast deployments are needed to fix a service or application outage that can cost a business money and reputation, we understand time is of the essence in these situations. That’s why we believe giving the team control over this is important in crucial moments of the development lifecycle

<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/03ODv1cEO6E" frameborder="0" allowfullscreen="true"></iframe>
</figure>

#### Deciding whether to add configuration

Product Managers at GitLab are frequently confronted with the choice of whether to add new configurations or not. These can frequently be times where an outside perspective is important. That's why we've created the option to request a [New Config Review](/handbook/product/product-management/process/#mvc-and-new-config-reviews).

Here's an example of how to consider whether to add new configuration. Let's say you are proposing we add a checkbox or two radio boxes in a feature dialog box. 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.

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.

- [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example)
is the configuration file used by the Rails application. This is where the domain is configured. Other configurations should be moved to the UI as much as possible and no new configurations should be added here.
- [`gitlab.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template)
is the configuration file for Omnibus-GitLab. It acts not only as
an abstraction of the configuration of `gitlab.yml` for GitLab-Rails, but also
as the source for _all configurations_ for services included and managed within
the Omnibus-GitLab. Newly introduced services probably need to be configured
here.

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.

### User Experience

Within each stage, the learning curve must be at least comparable to our best-in-class competitors, with clear, cohesive workflows, a highly usable interface, and comprehensive documentation. Product works closely with the [User Experience](/handbook/engineering/ux/) team to achieve our user experience goals.

Below are some general user experience principles we should always keep in mind. Additional UX principles to familiarize yourself with can be found in the [UX Department strategy](/handbook/engineering/ux/#our-strategy) and [GitLab's Pajamas design system](https://design.gitlab.com/get-started/principles).

#### Simplicity

Using GitLab should be easy. Users should be thinking about the applications they are building and teams they are collaborating with, not about how to make our app work. [Don't make users think!](https://www.goodreads.com/book/show/18197267-don-t-make-me-think-revisited?)

This sounds obvious, but it can be hard to keep things simple as an application becomes more complex, with more features and more options to cover more use cases and more user types.

The good news is that the product designer assigned to your stage group has a high level of expertise in how to simplify the complex, and how to make decisions about when to add or avoid complexity. Involve product design in all changes that impact the UI.

[![xkcd.com](https://imgs.xkcd.com/comics/app.png)](https://xkcd.com/1174/)

### 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](https://imgs.xkcd.com/comics/squirrel_plan.png)](https://xkcd.com/1503/)

#### How this impacts Planning

Here at GitLab, we are an [ambitious](#be-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](/handbook/ceo/#three-levels-of-performance),
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](/handbook/engineering/#the-importance-of-velocity)

We arrived at our preference for ambitious planning after measuring our velocity and finding that our velocity was unchanged whether we scheduled ambitiously or scheduled for providing slack.


### 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

- Empty states are the simplest paradigm for feature discoverability. They should always be considered.
- Typically, any empty list view should be replaced with an empty state design, similar to below.
- Empty state designs should provide an immediate call to action, thus improving discoverability.
- Once the UI area is no longer "empty", that design is no longer present and there is no harm to the user experience at all.

![pipelines_empty_state.png](/handbook/product/pipelines_empty_state.png)

#### Banners

- Banners draw attention to the user by introducing a feature to them in a nearby context.
- Benefits
  - Attractive graphics to draw attention.
  - Brief explanatory text.
  - A call to action for the user to start using the feature.
- Downsides
  - They invade the user's current flow and intended actions.
  - They are visually disruptive.
- To offset the downsides
  - There should only be one banner on the page at a time.
  - They should carry minimal information and not overwhelm the page.

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.

- Banners need to be dismissible permanently so that a user _never_ sees it again,
_ever_, after they have dismissed it.
- We have only one chance to introduce a feature to a user with a banner.
- Once they have chosen to dismiss it, it should never appear again because we do
not want to betray their trust when they click dismiss.
- Trust is incrementally earned with delightful experiences. If a banner
re-appears after dismissal, trust is destroyed.

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.

- Banner dismissal must be associated with the user in the system database, and
it must persist, even across version upgrades.
- If a user accesses GitLab with different clients, the dismissal state must be
consistent and the user has zero chance of seeing that banner again.
- A corollary is that banners should only be shown when a user is logged in.

![pipelines_empty_state.png](/handbook/product/banner_customize_experience.png)

#### Navigation

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

- See example design below: There is a subtle pulsating blue dot to draw a user's attention.
- This plants a seed in the user's mind that they can go and investigate that feature at a later time.
- If at the current moment they don't want to be disturbed, they can just ignore it because it is only
a slight visual disturbance (as compared to a banner which takes up more screen real estate).

- The pulsating blue dot UI element should be dismissible, with the same dismissibility
requirements as banners, for the same trust reasons discussed above.
- If dismissed once, it stays dismissed forever, for that user, across all clients that the user can
access GitLab with.

- In the same way that a page should not have more than one banner, the navigation should
_not_ have more than one call to action (the blue dot in this case).
- We do not want to overload the user with too much noise.

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

- GitLab should only ever show at most one blue dot. This should be implemented by
GitLab having a prioritized list of blue dots stored in the backend.
- It should show the highest priority blue dot that has not already been dismissed.

![tooltip_boards.png](/handbook/product/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 detailed plan. 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:

- avoid creating an inflexible, long-term plan
- can more easily construct a full feature/ capability, which is more easily marketed
- can provide context to each individual change ("we need this as part of X")
- can continue to ship MVCs
- work concurrently on several items, none of which are blocking

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](/company/strategy/#breadth-over-depth). 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:

- Build and use tools that work for both GitLab.com and self-managed.
- Start from a question, and build / collect what we need to answer that question. This avoids wasting time with data we don’t need.
- Use and improve existing tools we have inside of GitLab before leaning towards off-the-shelf products.
- Our customers, sales team and customer success teams all benefit greatly from similar insights into their usage as the product team does. Make things that help all of these people.

### No artificial limits in Core

Per [GitLab Stewardship](/company/stewardship/#promises), 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](https://docs.gitlab.com/ee/user/project/issue_board.html) in every project.
In GitLab EE, each project supports [multiple boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-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](https://gitlab.com/gitlab-org/gitlab-ee/issues/2059).

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.)

- Enforced workflows restrict GitLab to a smaller number of use cases, thus reducing the value of GitLab.
- Enforced workflows require overhead to maintain in the product. Each new feature
must account for any existing enforced workflows.
- We should trust our users to use GitLab responsibly, giving them freedom, instead
of imposing enforced workflows that we think made sense at the time of design and implementation.

[A comment on Hacker News](https://news.ycombinator.com/item?id=16056678) 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.
1. 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:

- When starting a branch with an issue (number) we link it to the branch.
- When merging an MR you automatically close the issue(s) it fixes.
- In GitLab CI you can define your deployment stage progression (staging, pre-production, production) including manual approval.
- We run quality and security tools automatically and provide dashboards to check status instead of making it a step in the process.
- We limit the impact of mistakes with incremental rollout and automatic rollback.

### 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](https://docs.gitlab.com/ee/user/project/issue_board.html)
use the smaller primitive of [labels](https://docs.gitlab.com/ee/user/project/labels.html).

They are especially powerful because they usually take less effort _and_ provide
higher leverage than you would get from a more "complete" but standalone feature.
Think of how simple Unix command line utilities can be chained together to do
really complicated things, much easier (and certainly more flexibly) than you
could have done with a dedicated tool.

When iterating on GitLab, strongly consider using small primitives instead
of creating new abstractions, especially when considering MVC features
that will provide the foundations for further improvements. To do this
you can start with easy to apply concepts that meet the needs of intermediate
to advanced users; from here document the usage clearly and be sure to think about
discoverability. The UX can very often be refactored or enhanced later when there's
a demonstrated need for refinement, onboarding for less sophisticated users, or
other new abstractions needed that were identified through real-world usage.

### Avoid plugins and marketplaces

Closed source software vendors commonly depend on plugins and marketplaces because:

1. These allow third parties the ability to add functionality without needing access to the underlying codebase.
1. Third parties can charge for the plugins, which gives them an incentive to build them.

Because GitLab is an [open core product](https://en.wikipedia.org/wiki/Open-core_model), third parties can add functionality directly to GitLab. Adding directly to the GitLab codebase (as opposed to building a plugin) _may_ mean more work for them and will limit the ways in which they can charge for that functionality.

However, for **users of GitLab**, this has significant advantages:

1. They are more likely to use this functionality, because it's distributed to all users by default.
1. The functionality always works out of the box, [requiring no additional software](/handbook/product/#convention-over-configuration).
1. Users don't have to search for what plugins are available, or test multiple options to see which one works the best.
1. Installations can't have varying combinations of plugins, making it easier to use and support the product.
1. Administrators never have to avoid an upgrade for fear that it might break an important plugin since all  code is tested together.

And for **developers of GitLab** including the third parties, this has significant advantages as well:

1. Their work isn't limited in functionality, because they're changing the code of the product itself.
1. Their code will be tested along with the rest of the product as things change refactoring is easier, reducing the likelihood that it suffers from [software atrophy](https://vijay.tech/articles/wiki/SoftwareEngineering/SoftwareAtrophyAnExample) because something is hard to change.
1. Community effort is not wasted on developing multiple plugins that all ultimately do the same thing and compete with eachother for usage.
1. Developers don't have to sacrifice [velocity in favor of predictability](/handbook/engineering/#velocity-over-predictability), since they don't have to worry about breaking the plugin API.

Overall, we believe that this approach creates the best possible experience for both the users of and the contributors to GitLab, and to that end we encourage people to [contribute functionality to GitLab directly](/community/contribute/).

If adding code directly to GitLab isn't an option, we encourage third-parties to integrate through our [APIs](https://docs.gitlab.com/ee/api/README.html).

_Note: GitLab does support [plugins that respond to system hooks](https://docs.gitlab.com/ee/administration/plugins.html), which tie directly to application events and are primarily used for administrative purposes such as auditing, logging, and other administrative tasks._

### Next Generation

While our [big, hairy, audacious goal](/company/strategy/#sequence) spans all development processes, personas, and use-cases, there are primary targets in each one of these venues.
When considering prioritization we should first aim to provide complete [maturity](/direction/maturity/) for developers building cloud native applications in a modern way prior to moving to other development methodologies, personas, and application types.

#### Modern first

When developing features to compete with existing competitors, make sure to
solve problems for modern development teams first, and *then* see what's missing
for legacy teams. e.g. For project management, make great project management
capabilities for teams doing conversational development, lean, or even agile
development before doing Scaled Agile Framework (SAFe) or waterfall.

It's important that modern first does not mean non-modern never. It means that
we should first learn how teams are using the feature in a modern way, and then
see what's missing. The modern way provides the path forward, and then we can add
customizability or the path to modern for teams who are not quite there yet.

#### Developer first

Our strategy includes going after a lot of new personas, going from developers to
operations, security, product managers, designers, etc. But when developing
features in these new areas, it's important to remember to start with the
developer. If we can make security great for developers and *then* great for
security professionals, we'll be much more successful.

#### Cloud-native first

Development teams deploy to tons of different platforms, from bare metal to
cloud VMs to cloud-native Kubernetes clusters. We build features for
cloud-native first, and *then* support the rest. This allows us to focus on
where development is going, and deliver solutions that every company aspires to
use eventually, even if they're not ready to today.

#### Prioritize current adopters

By focusing on next-generation development flows, personas, and use cases - we build features and experiences where our initial users are in the relatively small population of early adopters. While we might build experiences to support them today, we presume there will always be a much larger population of future users of these experiences. Therefore, we optimize GitLab to support the larger number of current and future adopters of next-generation principles - those who are beginning to operate in the workflow (modern), team setup (developer first), or application architectures (cloud native) we support. We focus our investment in the most modern workflows that will best support those current adopters. This will come at the cost of sustained investment in initial workflows for early adopters.

For example - we first provided an application log experience based on direct scraping of logs via kubectl. After adding support for installing Elasticsearch to your Kubernetes cluster, we should not continue to invest in the kubectl log view as we'd recommend newcomers to use Elasticsearch.

## GitLab as a Product

### Single application

We believe that a single application for the DevOps lifecycle
based on [convention over configuration](/handbook/product/#convention-over-configuration) offers a superior user experience. The
advantage can be quoted from the [Wikipedia page for convention over
configuration](https://en.wikipedia.org/wiki/Convention_over_configuration):
"decrease the number of decisions that developers need to make, gaining
simplicity, and not necessarily losing flexibility". In GitLab you only have to
specify unconventional aspects of your workflow. The happy path is
**frictionless from planning to monitoring**.

We're doubling down on our product for concurrent DevOps which brings the entire
lifecycle into one application and lets everyone contribute. We are leaning into
what our customers have told us they love: our single application strategy, our
pace of iteration, and our deep focus on users.

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:

- A minimal viable feature that is well integrated can be more useful than a
sophisticated feature that is not integrated.

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](/handbook/marketing/product-marketing/tiers/) strive to match 1:1.

- Free: Core features
- Bronze: Starter features
- Silver: Premium features
- Gold: Ultimate features
- Public projects are considered to have a Gold subscription level

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:

- personal namespace, e.g. `JaneDoe/*`
- group namespace, e.g. `gitlab-org/`

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:

- This would add significant additional complexity to the way we structure our features, licenses and groups. We don't want to discourage public groups, yet it wouldn't be fair to have a public group with only private projects and for that group to still get all the benefits of Gold. That would make buying a license for GitLab.com almost entirely moot.
- All value of group level features is aimed at organisations, i.e. managers and up (see our [stewardship](/company/stewardship/)). The aim with giving all features away for free is to enable and encourage open source projects. The benefit of group-level features for open source projects is significantly diminished, therefore.
- Alternative solutions are hard to understand, and hard to maintain.

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).

### Paid Tiers

Keep in mind that the [CEO is the DRI for pricing and tiers](/handbook/ceo/pricing/#departments). This includes any changes that directly impacts how we charge customers under our licensing model, such as a [change to how we handle active users](https://gitlab.com/gitlab-org/gitlab/issues/22257). Please review the entirety of the [stewardship](/company/stewardship/) and [pricing](/handbook/ceo/pricing/) pages before making any determinations of which tier a given feature should go in.

#### What goes in what paid tier

Our [stewardship principles](/company/stewardship/) determine whether something belongs in a
paid tier. The [likely buyer](/handbook/ceo/pricing/#the-likely-type-of-buyer-determines-what-features-go-in-what-tier) determines which tier.

#### Determining the tier of a new feature

When making a decision on the tier for a new feature, please refer to the [pricing page](/handbook/ceo/pricing/) for guidance. Be sure to consider
documenting your rationale for the decision in the issue description, including a reference to our [stewardship page](/company/stewardship/) when appropriate.

Please indicate the applicable tier for an issue by applying the label associated with the tier (e.g. `GitLab Core`, `GitLab Starter`) and the
`Enterprise Edition` label for features targeting a paid tier. Ensure this is defined before feature development begins.

Should you have any questions when making this decision, do not hesitate to collaborate with your manager, [product leadership](/handbook/product/leadership/), or the CEO in the issue for clarification.

#### Bringing features to lower tiers

To propose bringing a feature to a lower tier, follow the process on the [CEO pricing page](../ceo/pricing/#moving-a-feature-down).

#### Changing a price or introducing a new price

If you are considering launching a paid feature, or changing any other aspect of pricing, follow this process:

- Create a confidential issue in the [Product issue tracker](https://gitlab.com/gitlab-com/Product/issues) describing the approach and the reasons behind this change. Ensure the issue contains the margin analysis for the proposed price in addition to other relevant details related to finance or accounting, such as roll over credits
- Get approval from the VP Product
- Get approvals from the [CEO](/handbook/ceo/pricing/#departments), CFO, CRO, and VP of Field Operations
- Share the issue for feedback with the rest of the team on the GitLab company call
- Join the weekly Sales Team call, explain the proposal, and direct them to the issue to provide feedback. If attending the meeting is not feasible, ping the CRO on the issue and ask them to add it to an upcoming Sales Team meeting agenda
- If necessary, update proposal and reobtain [CEO](/handbook/ceo/pricing/#departments) approval.

Once a final determination has been made, consider making the confidential issue non-confidential. Ensure product marketing has a related website page for the feature and price. Ensure documentation is updated to accurately portray all facets of the feature. Consider a blog post to outline the feature.

#### Paid Tier requirements

All Starter, Premium, and Ultimate features must:

- Work easily for our customers that self-host GitLab. i.e. Their
  licenses need not be updated and the new feature is default-on for the
  instance.
- Work with GitLab.com Bronze / Silver / Gold subscriptions. This means there has to be
  some way of toggling or using the feature at a namespace level.
- Have documentation.
- Be featured on [products](/product/) and [DevOps tools](/devops-tools) at launch.

### 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

- not ready for production use
- unstable and can cause performance and stability issues
- the configuration and dependencies are likely to change
- features and functions may be removed
- data loss can occur (be that through bugs or updates)

#### Closed Beta

Similar to Beta, but only available to selected users.

- not ready for production use
- unstable and can cause performance and stability issues
- configuration and dependencies unlikely to change
- features and functions unlikely to change
- data loss less likely

#### Beta

- not ready for production use
- unstable and can cause performance and stability issues
- configuration and dependencies unlikely to change
- features and functions unlikely to change
- data loss not likely

#### Generally Available (GA)

Passed the [Production Readiness Review](https://gitlab.com/gitlab-com/infrastructure/blob/master/.gitlab/issue_templates/production_readiness.md) for GitLab.com, which means that it is:

- ready for production use at any scale
- fully documented and supported

### Deprecating and removing features

Deprecating features follows a particular pattern.
Use the language `Deprecated` or `Removed` to specify the state
of a feature that is going to be or is removed.

Features that are deprecated or removed should be:

1. Labelled accordingly in the documentation
1. Labelled accordingly in the application
1. Removed from marketing pages

#### Deprecated

- May be removed at a specified point in the future
- Still available with new installations, but documentation mentions deprecated state
- No longer receives new features and active development, but still supported: critical bugs and regressions are fixed

#### Removed

- No longer available in the latest version of the product

### Naming features

Naming new features or [renaming existing features](https://docs.gitlab.com/ee/development/renaming_features.html) is notoriously hard and sensitive to many opinions.

#### Factors in picking a name

- It should clearly express what the feature is, in order to avoid the [AWS naming situation](https://www.expeditedssl.com/aws-in-plain-english).
- It should follow [usability heuristics](http://www.designprinciplesftw.com/collections/10-usability-heuristics-for-user-interface-design) when in doubt.
- It should be common in the industry.
- It should not overlap with any other existing concepts in GitLab.
- It should have as few words as possible (so people won't use a shortened name).
- If you remove words from the name, it is still unique (helps to give it as few words as possible).

#### Process

- It's highly recommended to start discussing this as early as possible.
- Seek a broad range of opinions and consider the arguments carefully.
- The PM responsible for the area involved should make the final decision and not delay the naming.
- Naming should definitely not be a blocker for a feature being released.
- Reaching consensus is not the goal and not a requirement for establishing a name.

#### 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:

- New branding opportunities
- Reducing confusion as we introduce new adjacent features
- Reducing confusion as we re-factor existing features

### 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.
1. Reporters are read-only contributors: they can't write to the repository, but can on issues.
1. 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).
1. Maintainers are super-developers: they are able to push to master, deploy to production.
   This role is often held by maintainers and engineering managers.
1. Admin-only features can only be found in `/admin`. Outside of that, admins are the same as the highest possible permission (owner).
1. 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, if at all possible.

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.
1. A manager. A role to keep a project running, add new team members etc.
1. 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](https://gitlab.com/gitlab-org/gitlab/issues/21906).

[Documentation on permissions](https://docs.gitlab.com/ee/user/permissions.html)

### Security Paradigm

You can now find our [security paradigm](/direction/secure/#security-paradigm) on the [Secure Strategy](/direction/secure/) page.

Also see our [Secure Team engineering handbook](/handbook/engineering/development/secure/).

### 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.

### 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](/handbook/engineering/performance), and note the Speed Index target shown there
(read it thoroughly if you need a detailed overview of performance). Then:

- Make sure that new pages and interactions meet the Speed Index target.
- Existing pages should never be significantly slowed down by the introduction of new features
or changes.
- Pages that load very slowly (even if only under certain conditions) should be sped up by
prioritizing work on their performance, or changes that would lead to improved page load speeds
(such as pagination, showing less data, etc).
- Any page that takes more than 4 seconds to load (speed index) should be considered too slow.
- Use the [availability & performance priority labels](/handbook/engineering/performance/#performance-labels)
to communicate and prioritize issues relating to performance.

You must prioritize improvements according to their impact (per the [availability & performance priority labels](/handbook/engineering/performance/#performance-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](https://www.gnu.org/software/repo-criteria-evaluation.html),
all our javascript code on GitLab.com has to be free as in freedom.
Read more about this on [GNU's website](https://www.gnu.org/philosophy/javascript-trap.html).

### Why cycle time is important

The ability to monitor, visualize and improve upon cycle time (or: time to
value) is fundamental to GitLab's product. A shorter cycle time will allow you
to:

- respond to changing needs faster (i.e. skate to where the puck is going to be)
- ship smaller changes
- manage regressions, rollbacks, bugs better, because you're shipping smaller changes
- make more accurate predictions
- focus on improving customer experience, because you're able to respond to their needs faster

When we're adding new capabilities to GitLab, we tend to focus on things that
will reduce the cycle time for our customers. This is why we choose
[convention over configuration](/handbook/product/#convention-over-configuration)
and why we focus on automating the entire software development lifecycle.

All friction of setting up a new project and building the pipeline of tools you
need to ship any kind of software should disappear when using GitLab.

### Plays well with others

We understand that not everyone will use GitLab for everything all the time,
especially when first adopting GitLab. We want you to use more of GitLab because
you love that part of GitLab. GitLab plays well with others, even when you use
only one part of GitLab it should be a great experience.

GitLab ships with built-in integrations to many popular applications. We aspire
to have the world's best integrations for Slack, JIRA, and Jenkins.

Many other applications [integrate with GitLab](/partners/integrate/), and we are open to adding new integrations to our [technology partners page](/partners/). New integrations with GitLab can vary in richness and complexity; from a simple webhook, and all the way to a [Project Service](https://docs.gitlab.com/ee/user/project/integrations/project_services.html).

GitLab [welcomes and supports new integrations](/partners/integrate/) to be created to extend collaborations with other products.
GitLab plays well with others by providing APIs for nearly anything you can do within GitLab.
GitLab can be a [provider of authentication](https://docs.gitlab.com/ee/integration/oauth_provider.html) for external applications.

There is some natural tension between GitLab being a single-application for the
entire DevOps lifecycle, and our support for better user experience via integration
with existing DevOps tools. We'll prioritize first our efforts to improve the single-application
experience, second to enable a rich ecosystem of partners, and third to improve integration with the broader ecosystem
to other tools. GitLab is open-source so this should not prohibit contributors adding
integrations for anything that they are missing - as long as it fits with GitLab product vision.

If you don't have time to contribute and are a customer we'll gladly work with you to design the API addition or integration you need.

### Who GitLab competes with

In pursuit of our product vision of becoming a complete platform for the entire DevOps lifecycle, delivered as a single application, GitLab will inevitably compete for user and business with other DevOps tools technologies and vendors. For clarity, GitLab publicly competes with other vendors only in categories where our product is lovable (in our [maturity model](https://about.gitlab.com/direction/maturity/)). We may at times name these competitors publicly.

For all other categories, GitLab will highlight examples of tools that have functionally similar features to the features GitLab is developing, but we will not name them as explicit competitors. This does not mean that we will not be trying to acquire users or business based on those categories, but it does mean that we will not refer to those other vendors as 'competitors', as our goal is to pursue our product vision (not to specifically win against other tools or vendors where we are not yet lovable).

## Changing the Product handbook

This is the Product handbook. If you (a Product team member, a GitLab team-member, 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](/company/team/) afterward
as a courtesy so that we can thank you, since we have a [bias for action](/handbook/values/#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.

[features]: https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/doc/features.md
[CAB]: /handbook/marketing/product-marketing/customer-reference-program/#gitlab-devops-customer-advisory-board