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

Product Principles

  1. You are here:
  2. Handbook
  3. Product Handbook
  4. Product Principles

Principles - Processes - Categorization - GitLab the Product - PM Responsibilities - Being a PM - Performance Indicators - Leadership

Our Product Principles

These are core principles we believe world class product organizations exhibit. The goal is to build a PM system that fosters and honors these principles, in a way that works for GitLab.

  1. Hiring is Job One. "A" players attract "A" players. Given the strategic importance of the PM role, a strong PM creates enormous leverage. We should strive to raise the average competency for the team with each new hire.
  2. Care personally & challenge directly. Employees that feel safe plus managers that coach honestly is how people do their best work. We encourage timely and actionable feedback, as well as managers that take the time to get to know their people as humans with feelings and personal lives, not just resources.
  3. Always be learning. Continuously invest in skill development, and have a growth mindset as individuals and as a team.
    • Helpful resource: Peak
  4. You’re not the customer. Talk to them. It is tempting to assume that we understand our customers, but we are often wrong. We validate our assumptions through qualitative and quantitative customer input.
  5. Start with the problem, not the solution. It is tempting to dive right into solutioning, but we are often wrong about the underlying problem. A well formed problem statement is the key to a successful project.
  6. Prioritize relentlessly. It is better to do a few things well than many things poorly. We should focus first on what we’re best at and what our customers need most, with a preference for simplicity. Customers will tell us when we’re missing something they need, but they’re unlikely to tell us when we’re overwhelming them with unwanted features.
  7. Assume you are wrong. Human intuition is often wrong. To fight this, have a hypothesis and try to invalidate it quickly.
  8. Iterate. Leverage a fast-paced build-measure-learn feedback loop to iterate your way to a good solution, rather than trying to plan it all out up front.
  9. Be data driven. Always have success metrics, track them, and try to move them in the right direction with our actions.
  10. Product-led growth. Strive to build a delightful product and user experience that seamlessly acquires, activates, and retains customers in partnership with Marketing, Growth, Pricing, Fulfillment, and Sales.
    • Product-Led growth does not mean product-management-led growth. However, following this principle product becomes a central piece in driving growth and is used for many activities that were traditionally outside of the product to provide a scalable approach.

How we follow our Principles

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

As a single-application for the entire DevOps lifecycle GitLab strives to enable you to bring ideas to production rapidly. We will do so AND avoid demonstrating our capabilities with toy app demos and simple trivial examples. That's because we understand that building a prototype is easy, but building a production line is hard.

The Minimal Viable Change (MVC)

We only ship in a Minimal Viable Product (MVP) style. We call it Minimal 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 deliver the smallest possible solution that offers value to our users. To avoid 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 minimal viable change should not be a broken feature.

Advantages of an MVC approach:

When considering how to scope a feature for a release, remember that it is ok to ship an "incomplete" feature to customers, assuming that it still offers value, is not broken, does not hurt usability, for UI changes (see the definition of done). When introducing a new component or pattern not found within Pajamas, it is the responsibility of that team to follow our component lifecycle guidelines to determine whether it should be added and, if so, contribute the addition/update back to Pajamas.

MVC means reducing the scope so we can ship quickly. It doesn’t mean shipping something that hurts the usability of GitLab. First impressions are important. A feature that does not offer enough value or hinders the user experience may have a negative effect that discourages users from trying that feature again in the future. If there are obvious gaps in your MVC or you can anticipate follow-up requests, consider whether your feature is complete enough to be released to users. If you are unsure whether your feature is complete enough to be an MVC (or if you know your feature is not complete enough to be an MVC and you want to gather additional feedback), you can use approaches such as dogfooding, beta programs, feature flags, and/or user research to help build confidence in your decision. In terms of talking about your feature, it's ok to add a release post item that announces your incomplete feature (making clear that it is an early iteration, and points to the direction for the feature) and follow up in a later release post with a new item when you've completed more of the functionality. As long as you call it cookie dough, not a cookie, it manages user expectations.

Examples:

There are scenarios when an MVC approach is not advised. These include:

Iteration

An MVC approach is a byproduct of our spirit of iteration. That means we break problems down as small as possible, use merge request rate as a performance indicator, and focus on reduced cycle time. Thinking iteratively is not always intuitive, and breaking certain topics or projects down can be challenging. Here's a helpful video from our CEO with guidance on how to think more iteratively.

Here is a great video that illustrates how to build MVCs using Iteration. It shows Lego climbing obstacles. The first design fails. The second one can climb a book and so on. It also illustrates how modularity and good interfaces help with iteration as things get complex.

Subtractive thinking

Humans tend to favor solutions that add features than solutions that remove them, even when removing features is more efficient - great PMs recognize this bias and utilize subtractive thinking to create great user experiences. Customers will tell us when we’re missing something they need, but they’re unlikely to explicitly tell us when we’re overwhelming them with unwanted features. However, we do have evidence that this challenge is already a consideration for us, as reflected consistently in our System Usability Scale verbatims. Here is an episode on the Hidden Brain podcast that explores this bias further.

SaaS First

Our customers choose SaaS because it reduces their operating costs, helps them adopt the latest capabilities without performing upgrades, and provides them peace of mind of high availability. This implies we adhere to SaaS first principles. SaaS first implies the following:

Feedback issues

An MVC approach allows for maximum feedback while iterating. To help gather that feedback, Product Managers are encouraged to create feedback issues (example) to consolidate suggestions and experiences from users. Consider mentioning the feedback issue in any release post items and related implementation issue(s) for awareness.

Celebrate and Learn from Failures

It's important that team members know they are encouraged by E-group to continue moving fast as GitLab grows and gets bigger as a company. This involves moving quickly even in the face of risk and complexity. In alignment with our transparency value, we'd like to celebrate examples of failures or mistakes that were made while moving fast, where we ultimately learned from it and moved on.

The following failures provided by the product team are celebrated as opportunities to gain insight, share learnings and move on with additional knowledge:

  1. We initially believed we should create a lift and shift translator for Jenkins, but learned from users and technical experts that it wasn't technically feasible and it would be better to invest in more detailed documentation and guidance.
  2. With Auto DevOps, we discovered the desire for composability and the need to iterate on your DevOps platform makes a one-pipeline fits all capability miss the mark for tackling that user pain.
  3. We integrated with some monitoring and observability tools as MVCs (Jaeger) that were just too MVC to give us data points on their success.
  4. We relied upon "MVC" not including on by default and usable by default - resulting in lots of MVCs that we thought would garner us new information, but did not.
  5. We spent time delivering a marketplace offering, and had very little traction. We learned marketplace offerings alone are not a vehicle for adoption, and we need a sales alignment with the marketplace vendor to achieve success.
  6. We had duplication of effort between Quality and Distribution. We didn't recognize / resolve this for too long. We have learned to better integrate Quality into the planning process.
  7. Data telemetry in general has been one of our failures. We didn't invest in telemetry seriously or early enough, and we attempted to accelerate via a 3rd party, but didn't do a good enough job talking to our community on the best ways to roll that out.
  8. We failed to capture significant users with APM. Internal Deck for Reference
  9. Historically, designers had been instructed to not spend time on problem validation, but we had a PM who realized in order for her group to be successful, she needed her design counterpart to be deeply involved in validation work.
  10. We learned that GitLab's original Serverless strategy was dependent on immature technology and not necessarily aligned with the market winner Lambda. This resulted in GitLab stopping investment in Serverless.
  11. We recognized a big gap in security concerns with GitLab managed clusters, which was prohibiting this feature from being adopted by customers. Once we learned from this 'failure' we introduced the Kubernetes agent instead.

If you have a failure that can serve as a learning opportunity, please make an MR to this page

Avoid "Not Invented Here" Syndrome

Just because something is 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:

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

We understand that a natural inclination when using application development tools is to create an array of buttons to press and knobs to turn. We believe, however, that adding options to an application does not necessarily improve the user's experience of that application. The best way to serve our users is to create an application that reduces complexity while still offering the features they need.

Inspiration

We admire other "convention over configuration" tools—like Ruby on Rails (the doctrine of which perfectly describes the value of integrated systems), Ember, and Heroku—and we strive to offer the same advantages for continuous delivery of software.

Furthermore, Ruby on Rails has significantly and positively influenced the Ruby community, uplifting the tool and making it more powerful and useful than ever before. We want GitLab to be to Kubernetes what Rails is to Ruby.

You should prefer well-considered choices based on current best practices. Avoid unnecessary configuration. Avoid configuration to support fragile workflows.

Configuration Principles

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

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. Controls that prevent changes from reaching Production are okay as safeguards, but they should be able to be quickly removed or disabled if necessary. When controls are changed in this way, logs or records should be created to support post-mortem analysis and allow for understanding why the control needed to be removed or disabled.

Parity between SaaS and Self-managed deployments

We want to provide the same capabilities to our users regardless of the method they choose to use GitLab (GitLab.com or Self-managed). At the same time, we believe in the power of a single code base.

Therefore we maintain feature parity between SaaS and Self-managed installations.

Principled adherence to the established knowledge architecture

Exception to this product principle requires CEO approval. Work with VP, Product Management to add your request to the Product Scale agenda describing the situation and request for exception to gain CEO approval.

Our simplicity and SaaS/Self-Managed Parity principles require that we adhere to our established knowledge architecture. Our established architecture is Workspace, Group and Project.

Note: This implies that we will take pains to avoid instance-level features as We expect to move all capabilities from instance to workspace over time.

Take pains to avoid instance-level features

After making a tier decision on a new feature, we should strive to maximize the number of users who can use it.

As part of this objective, we should avoid building instance-level features when possible. Building at the instance level (in the admin area) leads to a separation between GitLab.com and self-managed and limits your audience to self-managed customers only:

Historically (and even net-new proposed features) we've often started with an "instance-wide" mindset which then means we need to iterate and adjust features to work at a group-level. This often delays functionality for our SaaS customers and makes GitLab.COM feel like a second-class citizen.

There are factors that may justify an instance-level feature, like engineering efficiency and high infrastructure cost, but we should always have a clear view on how we might bring the feature to GitLab.com and clearly document why we started with the instance-level in the issue.

Deciding whether to add configuration

For a GitLab instance in gitlab.yml

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.

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.

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.

For a GitLab CI configuration in .gitlab-ci.yml

If the decision to add a configuration follows the principles above, add it to the repository-specific CI configuration options and be sure to default it to the option that results in the best user experience. We are much more liberal with additions to CI configurations than Instance configurations.

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 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 and GitLab's Pajamas design system.

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!

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

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 minimal viable changes, we are able to accomplish many more "impossible" things than other organizations.

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

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 helping novice and experienced users find features that benefit them, thereby increasing the value of GitLab for them. And the more users see and try our features, the faster we can get feedback to improve them.

However, when taken too far, this can have the unwanted effect of annoying users. 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.

Work with your product designer to improve the discoverability of your features. The Pajamas Design System has a number of patterns that support discoverability. We can also design new patterns. The Growth team can also help you with this, as they think about things like onboarding new users and promoting feature use within the app while supporting, not annoying, the user. General best practices, examples and more details are available in Pajamas.

Product Qualified Leads (PQLs)

As the GitLab userbase and team members who work on GitLab continue to grow we need to support both our users and team members by helping to connect users who may be interested in speaking with a member of the sales team to that particular person. We can call this a Product Qualified Lead or a PQL.

A PQL can be further broken down into two types, usage and hand-raise

Clarifiying out what a PQL is not

The future vision of PQLs within the GitLab product

Our goal is to develop a world-class PQL system whereby we monitor product usage to understand and constantly iterate on what constitutes a usage-based PQL and provide a unified intelligent interface in the product where users can submit a hand-raise, start a trial or upgrade touchlessly.

By monitoring product usage, usage PQL volume, SAO rate, and ASP we will be able to work in partnership with marketing and sales to ensure we’re sending high quality leads to the sales team.

In the product experience, we will develop an intelligent module for feature discovery moments whereby we help recommend what we believe should be the preferred option for the user whether it’s a hand-raise, trial or touchless upgrade by updating the default CTA based on their usage of the product along with demographic and firmographic data. This experience will be present on both SaaS and self-managed instances for air-gapped instances the CTAs will provide the user with external URLs to visit to complete the associated step. This experience should be able to be deployed by any stage to further their paid adoption rate.

Drive Product Usage

Users can only experience GitLab's value when they actively use the product features. Therefore the Product team's mission isn't only shipping features and building products, but also driving usage and delivering value.

There are two frameworks we use to think about driving GitLab's product usage: we use the AARRR framework to think about how to drive a single feature's usage, and use the Customer Adoption Journey to think about cross-adoption of product features. These two frameworks are also interconnected with each other.

Single Feature usage: AARRR framework

AARRR stands for Acquisition, Activation, Retention, Revenue, and Referral which is often referred to as "Pirate Metrics". These five words represent the customer journey and the various means a product manager may apply Product Performance Indicators to drive a desired behavior in the funnel.

While the AARRR framework is commonly used to drive overall active users, it is also a great way for PMs to think about how to drive feature usage.

classDiagram Acquistion --|> Activation Acquistion : Are users aware of the product or feature set? Acquistion: Measurement (Insert Metric) Activation --|> Retention Activation : Are users applying the feature? Activation: Measurement (Insert Metric) Retention --|> Revenue Retention : Are users applying the feature over time? Retention: Measurement (Insert Metric) Revenue --|> Referral Revenue : Are users paying for the features? Revenue: Measurement (Insert Metric) Referral --|> Acquistion Referral : Are users encouraging others to use the feature? Referral: Measurement (Insert Metric)

Add AARRR funnels for your stage or group's Product Performance Indicators directly with mermaid markdown. It's easy if you use this live editor.

Product managers can use these various states to prioritize features that drive a desired action. This could mean focusing on the Activation metric to drive awareness and generate more top of funnel leads. As an example, in the Release stage the Release Management group tracks actions on the Release Page in GitLab. Users that view a Release Page have been acquired and those that create a release on a Release Page are activated users. The Product Manager can choose to target features that drive users to view the Release Page more, resulting in a greater interest in the number of users that become activated and create their own Releases.

Multi-feature usage: Adoption Journey

GitLab is a complete DevOps platform. Our customers get the most value out of the GitLab product when they use multiple features together. Below is the most common path our customers follow to adopt GitLab's product stages.

As PMs, in addition to driving usage of individual features, we should also proactively think about how to design product and user experiences to help users adopt more stages and features, therefore benefiting more from using GitLab.

graph TD; id1(Create - 99%) --> id2(Plan - 91%) id3(Verify - 84%) --> id4(Secure - 36%) id1 --> id5(Manage - 35%) id1 ==> |Golden Journey|id3(Verify - 86%) id3 ==> |Golden Journey|id6(Release - 54%) id3 --> id7(Package - 7%) id6 --> id9(Monitor - 8%) id6 --> id10(Configure - 2%) id6 --> id11(Govern - 28%)

Note: There are numerous potential variants to this adoption journey, but it's important to keep this representation simple and consistent. Please check with David DeSanto first before making any changes to the adoption journey image.

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:

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

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.

This principle does not apply to our SaaS offering as limits are occasionally introduced to limit our hosting costs and protect other users from potential abuse. As an example we have shared runner minute quotas and implement rate limiting.

Avoid enforced workflows but allow enterprise flexibility

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:

When considering a customer need for enforcement or limitations:

As an example, customers requested instance-wide enforcement through required CI jobs. Doing this would have been a mistake. Instead:

While workflow enforcement should be avoided in most cases, there are organizations that rely on enforced workflows for a variety of reasons. These organizations have problems adapting existing workflows as they move to GitLab and as a result, we should consider allowing some enforcement at the group level in order to balance team efficiency and organizational policy. Page 79 of Accelerate outlines "teams that reported no approval process or used peer review achieved higher software delivery performance." As we implement features to allow organizations to enforce workflows, we should do so at the group level and default them off. GitLab should be a product teams use to accelerate product development, but flexible enough to solve for requirements of all sizes of organizations.

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.

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.

Component Principles

In GitLab the product, it is sometimes the case that optional software or infrastructure is required to enable new capabilities. Some examples include:

The following are best practices we consider when building such components.

Start with enabling Developers

As we learned with GitLab CI/CD, the ability for developers to quickly attach needed Runners to enable their own use of GitLab CI/CD allowed for rapid adoption of GitLab CI/CD within an organization. When considering the workflow to enable additional capabilities, start with enabling developers first. A guiding principle should be low-friction developer enablement, which will positively impact adoption.

Build for production use, not demo use

As we learned from the certificate-based Kubernetes Integration, building starting experiences that support demoing a getting-started process doesn't necessarily translate into real usage. For example, the certificate-based integration lacked strong security primitives and the ability to manage the integration on an ongoing basis. As a result, we should build capabilities that target real-world production use first, even as part of MVCs.

Integrate other applications thoughtfully

GitLab's vision is to be the best single application for every part of the DevOps toolchain. However, some customers use tools other than our included features, and we respect those decisions. With this in mind, it's sometimes valuable to integrate with 3rd-party services and products to help bridge the gaps in their toolchain. While a single application is the best approach, multiple applications that work well together is better than ones that don't.

With this in mind, below are some product guidelines to consider:

Avoid plugins and commercial marketplaces

Note - We intend to provide a place where everyone can contribute, such as code snippets, project templates and CI/CD templates. Marketplaces are traditionally transaction based, where users are purchasing solutions. GitLab CI/CD templates on the other hand, will offer an in product experience for consuming templates for YAML configuration from a library of GitLab maintained templates.

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

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

Because GitLab is an open core product, 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.
  2. The functionality always works out of the box, requiring no additional software.
  3. Users don't have to search for what plugins are available, or test multiple options to see which one works the best.
  4. Installations can't have varying combinations of plugins, making it easier to use and support the product.
  5. 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.
  2. 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 because something is hard to change.
  3. Community effort is not wasted on developing multiple plugins that all ultimately do the same thing and compete with each other for usage.
  4. Developers don't have to sacrifice velocity in favor of 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.

If adding code directly to GitLab isn't an option, we encourage third-parties to integrate through our APIs.

Note: GitLab does support plugins that respond to system hooks, which tie directly to application events and are primarily used for administrative purposes such as auditing, logging, and other administrative tasks.

Product and feature naming guidelines

Give products and features descriptive, not distinctive, names

GitLab is a DevOps Platform, not a collection of DevOps point solutions; the naming of GitLab products and features should reflect this. Adopting descriptive names brings other advantages:

As an example, CI/CD Components Library is a descriptive name while CI/CD ATOM is a distinctive name.

Exceptions to this principle are considered in limited circumstances - if a product or feature is a differentiator in the market, adopting a descriptive name risks it getting lost in the sea of same. Here, a distinctive name may be justified. To discuss an exception, reach out to #marketing in Slack.

Use prepositions when referring to third-party products and services in names

When naming a GitLab extension, plugin, app, or integration for a third-party product or service (a "tool"), either include the third-party service name with a preposition like for, or don't include it at all. A preposition is important as it indicates that the third party isn't officially affiliated with the tool. For example, our integration with Jira Cloud is called GitLab.com for Jira Cloud.

Provided we use the tool's full name in marketing materials and technical documentation, as exceptions to this general principle we can: (1) refer to the tool solely by the third-party service name in places where we list GitLab's tools in product; and (2) refer to the tool solely as "GitLab" in the third-party product's app directory. For example, we refer to the GitLab for Slack app as "Slack" in our lists of GitLab integrations, and as "GitLab" in the Slack App Directory.

For more guidance on the feature naming process, see naming features.

Next Generation

While our big, hairy, audacious goal 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 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. When doing so we will ensure we clearly communicate with our users what the preferred path is.

For example - We first provided the ability to attach Kubernetes Clusters via the Certificate method. After realizing this wasn't optimal for production use cases we added the GitLab Agent for Kubernetes method of cluster attachment. As soon as we were certain that the certificate method was no longer the preferred method we communicated via our docs and in the product that the Agent was the preferred path for current adopters. This should not mean an immediate deprecation, but a clear signal that the legacy method will become deprecated once the alternative approach is able to substitute it.

Customer Support on all features

We provide customer support to paying customers on all features that are in the tier of their paid license as well as any lower tiers. This means a feature in Core, should get customer support in all paid tiers. For example, when there is a feature that is available in the lowest paid tier, but only has customer support in higher tiers, the feature should be removed from that lowest paid tier. In accordance with our stewardship policy we can never remove features from Core into paid tiers, but we can build additional features around it which are available to paying customers only.

Open in Web IDE View source