As everything at GitLab, this document is forever in draft. Merge requests are very welcome. Infographics from xkcd.
The document below talks about how we do product at GitLab, not about what. For the what, see Product Strategy.
Table of contents
If you have any product-related questions, comments, input or otherwise, the product manager is the primary person you should talk to, if creating an issue does not suffice. Otherwise, read this section on how to create an issue.
This includes, but is not limited to features, bugs and other changes that need more attention, be prioritized, changed, or discussed.
Product managers will reach out to stakeholders in making or communicating any decision. The weight of balancing priorities and ensuring we build excellent software is on the product manager and they will need all the input they can to achieve this.
See below who to contact for what in detail. In short it is:
Enterprise edition features fall under their respective PM, not under one PM in particular. For instance, Service Desk falls under Victor, because it's part of our Issues.
Reach out for anything that falls under the following things.
For example, if a customer would like us to support a particular extension to LDAP or wants to have a particular importer, contact Mike.
For anything related to GitLab.com, Mike is also the first responder. If you want to know more about the rollout of particular features on GitLab.com or how our plans work, talk to Mike.
For anything that falls under:
This means that if a customer would like to see burndown charts, which relates to issues, you should speak to Victor.
Anything related to the Idea to Production demo itself is Mark's responsibility, but not all features in the idea-to-production scope.
Anything related to monitoring inside of GitLab, falls under Josh's responsibility. If a customer wants to monitor particular data or see this improved, speak to Joshua.
Fabio handles anything related to CI and CD within GitLab. If a customer would like to see build artifacts improved, speak to Fabio.
Edge relates to any of the supporting applications and tools that are not directly part of GitLab. This includes:
This also includes anything related to how GitLab handles licenses and how we handle data that we get from customers through the usage ping.
Build is all about how we ship GitLab and make sure everyone can easily install, update and maintain GitLab. This includes:
Please contact Sean (Technical Writing Lead) and not the technical writers for any work scheduling.
We, the Technical Writing team, are responsible for the following assets:
We are there to assist developers in their documentation writing process by providing copy editing and reviewing services and are not responsible for writing the first draft of documentation for new or updated features.
We will mantain and improve the overall health of documentation e.g. by creating topic index pages, improving orgnization and creating tutorials.
We manage our documentation tasks for CE and EE on the following issues boards which track labels beginning with
Contact Job for any questions about the strategy of product or process within product.
At GitLab, the PM leads their specialization. That is, the Platform PM decides what is being worked on by the platform team in which release and makes sure this furthers our goals. This includes bugs, features, architectural changes.
The PM can't be expected to parse every single bug, issue that comes by, so they will have to rely heavily on the input of the various stakeholders. To be able to achieve this, both the PM and the stakeholders have to actively work together. It's a two-way street.
In general terms, if you require something to happen with the product or if you need engineering resources for a particular change, you approach a PM. Preferably through creating an issue, the GitLab way and mentioning them there.
In the same vein, PMs are required to ask for feedback from the stakeholder of particular changes. If a change will affect GitLab.com and its maintenance, a PM should proactively reach out to infrastructure engineers to help with the scoping, design and decisions on this change.
It is then up to the PM to weigh all these inputs and decide on a prioritization. It is to be expected that they are best equipped to make this prioritization, keeping in mind all goals of GitLab.
If you hear a feature request from a customer, you should follow the normal procedure: you create an issue, label it correctly. Let's say the customer requests an enhancement to Issues. You know by reading above that you'll have label this with
Discussion and you can mention or reach out to Victor to expedite this if warranted.
Same as before, make sure an issue is made and make your case with Mark on that this is becoming a problem and needs to be fixed. Mark will make sure that this is fixed or resolved in some other way.
Everything in GitLab should be fast and creating files falls under the repository, so you create an issue and make Mike aware of it by mentioning it.
Mike in turn will investigate whether this is a general problem or one specific to GitLab.com, in collaboration with infrastructure and others and schedule any necessary changes for an upcoming release.
#productchat channels for questions that don't seem appropriate to use the issue tracker or more generic chat channels for.
Everyone at GitLab is involved with the product. It's the reason why we are working together.
With every release of GitLab, we want to achieve each of the following goals.
The product team is responsible for iteration on most of GitLab's products and projects:
This includes the entire stack and all its facets. The product team needs to prioritize and weigh bugs, features, regressions, performance, but also architectural changes and other changes required for ensuring GitLab is excellent.
GitLab is designed and developed in a unique way.
The direction for the GitLab product is spelled out on the Direction page. This document provides lessons and heuristics on how to design changes and new features. Our iterative process is demonstrated in a blog post.
Reduce every change proposal to its very minimally viable form. This allows us to ship almost anything within a single release, get immediate feedback and avoid deep investments in ideas that might not work. Other advantages:
Despite its minimal form, the change
Prefer choices that are well thought out, based on current best practices. Avoid unnecessary configuration.
For example, when considering adding a checkbox or two radio boxes, think really hard what users really want. Most of the time, you'll find you really only need one solution, so remove the option. When two possible choices really are necessary, the best or most common one should be default, and the other one should be possible. If the non-default choices are significantly less common, then consider taking them out of the main workflow for making decisions such as putting them behind an Advanced configuration tab.
Every configuration in GitLab multiplies its complexity, which means the application is harder to use, harder to develop, and less friendly to its users.
Making features configurable is easy and lazy. It's a natural reaction to propose a big change to be configurable, as you worry it'll negatively affect certain users. However, by making a feature configurable, you've now created two problems.
Work on solutions that work for everyone, that replace all previous solutions.
Sometimes configuration is inevitable or preferable. GitLab should work perfectly right out of the box for most users. Your configuration can't make that experience worse and should always get out of the way of the user.
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 behavior. For this reason, adding a configuration to be able to disable this permanently (be that in template or instance-wide), is something that should be avoided.
Encourage favorable behaviors by limiting configuration.
In addition to encouraging behavior by limiting the ability to toggle features, when introducing new features default to turning things ON if they are configurable at all.
Avoiding configurations is not always possible. When we do have to make this choice, the second order of preference is to configure something in the GitLab interface. Only as a last resort should a configuration appear in file (
There are two major configuration files available in GitLab. It should be avoided to add new configurations to either.
gitlab.ymlis 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.rbis the configuration file of Omnibus-GitLab. It acts not only as an abstraction of the configuration of
gitlab.ymlfor GitLab-Rails, but also the source for all configurations for services included and managed within the Omnibus-GitLab. Newly introduced services might need to be configured here.
When you do have to add new configurations, do not add new default values. Make sure features, services turn on by default and only in the case of disabling a user should be required to add a line to either of these files.
Many crazy, over-ambitious ideas just sound like they are impossible because no one else is doing them.
Because we have amazing engineers and a culture of shipping a minimally viable change, we are able to do a lot more 'impossible' things than other people.
That's why we're shipping merge conflict resolution, why we shipped built-in CI before anyone else did it, why we built a better static pages solution, and why we're able to compete.
Doing something simple in GitLab should be simple and require no human cpu-cycles to do so. Things that are simple now, should be simple in two and ten years.
This sounds obvious, but messing with Flow is easily done. In most cases, flow is disrupted by adding another action, another click.
For instance: You want users to be made aware of the rules of a project. Your proposal is a little popup that shows the rules before they create an issue. This means that every time that someone creates an issue they need to click once before resuming their normal action. This is unacceptable. A better solution is to add a link to the issue that points the user to this.
It's very hard to maintain flow with a lot of configurations and options. In cases where you want to enforce certain behaviour, the most obvious step is to add another step or action. This can be avoided by making the action work in parallel (like a link in the issue), encouraging rather than enforcing certain behaviours.
We don't want users to be able to construct workflows that break GitLab or make it work in unpredictable ways.
Balancing our great ambition with our dedication to customer success is tough. Add in a growing number of dedicated teams focusing on areas of the product, and it becomes challenging to make sure everything we work on is truly the right thing to work on, right now. To help with that, it's good to keep a few things in mind. To ask a few questions to keep us all aligned.
At a high level, you can think of aligning along these dimensions (not necessarily in priority order):
To make it concrete with an example, the CI/CD team might ask:
Naming new features is notoriously hard and sensitive to many opinions. It's highly recommend to start with discussing this as early as possible.
When naming something, the name should clearly express what the feature is. Follow usability heuristics when in doubt.
If you follow the guidelines above, you won't be writing long, detailed specs for a part of the product for the next year. So how should you be spending your time?
Invest the majority of your time in understanding the problem deeply (say 70%). Then spend 10% of your time writing the spec for only the first iteration and handling comments, while the remaining 20% you work on promoting it.
A problem you understand well will always have a (seemingly) simple or obvious solution. Reduce it to its simplest form (see above) and only ship that.
Once you've shipped your solution, both you and the community will have a much better idea on what can be improved and what should be prioritized for future iterations.
As a PM you're the person that has to kick-off new initiatives. You're not responsible for shipping something on time, but you are responsible for taking action and setting the direction. Be active everywhere, over-communicate and sell the things you think are important to the rest of the team and community.
As a PM you don't own the product: ask other people for feedback and give team members and the community the space to suggest and create without your direct intervention. It's your job to make sure something is decided and planned, not to come up with every idea or change.
The best way to understand the pain of the users is to go through what we ask them to do while setting up or using GitLab. As a PM, you should go through every feature, at the minimum the ones you are responsible for. All of them. That includes features that are not in GitLab's UI directly but require server configuration. If you, as a PM, can't understand the documentation or struggle to install something, who else would even bother to do it? Going through this is not only beneficial to understand what the pain points are, it will also tell you what you can enhance, from a better flow to a better documentation.
Most of GitLab is configured through the file
gitlab.rb. It's tempting to add a new parameter in this file - it's easy, fast to do, and won't require to add a new UI to allow the configuration of this new setting. However, changing this file requires you to reconfigure GitLab. To do that, you have to login to your server and type in commands to reconfigure your instance. Possibly, multiple times if you have more than one server.
This is not something that we can ask our customers to do. Only by using your own product and features, will you realize that some practices should be avoided if you can.
Almost everything that we do is documented in an issue.
Performance is a priority for GitLab. If you want to create a performance issue:
When relevant, you can include a wireframe in your issues in order to illustrate your point. You don't need to include wireframes per se - our UX/design team can help us on that matter. Simply ping them if you need their help. We like Balsamiq for its simplicity and its sketch-y approach. If you don't have inspiration, you can also paste screenshots of similar features in other products.
Meta is a label assigned to issues that contain a large list of todos. If you are familiar with the Agile methodology, it's similar to an epic. At GitLab we have a short release cycle: the 22nd of every month. In some cases we won't be able to tackle all the tasks of a meta issue in a single release - this is why we centralize all the things that we need to do in a meta issue, then break it down to issues small enough that they will fit into one release. Meta issues generate most of the time lots of comments and passionate discussions. As a consequence, they always lead to something great.
Note: smaller tasks that are part of a meta issue are sometimes also labeled
meta. That's because they are part of a meta topic, and thus get the meta label.
A general guideline is that an issue should only span one release. If we know an issue is going to span multiple releases, split it up in multiple issues.
Meta/epic issues are the exception to this rule, but should be kept to a minimum and only serve to guide broader subjects, not a single feature over multiple releases. This to make sure we stick to our values of the minimally viable change.
The above means that feature issues should be closed after a first iteration whenever possible. We'll know more in the future and this keeps remaining issues short and actionable.
In addition, it's almost never a bad idea to throw away an original plan and start fresh. Try to do this more often that you're comfortable. Close the issue and create a new one.
When you don't have specific tasks assigned, you should work on issues that are labeled
Product work, in both EE and CE projects. These are issues that need our attention the most.
Issues are scheduled into a milestone (the upcoming release), worked on by engineering and design, and then shipped to production. This timeline is relevant to the release shipped in month
M with milestone
M-1, 4th: Release scope is established | In scope issues marked with milestone
missues are updated with docs starter blurb | Release post (WIP merge request) created with
missues and docs starter blurbs
M-1, 8th (or next business day): Kickoff call with WIP release post
M, 7th: Completed
missues with docs have been merged into master | Unstarted or unfinished
missues are de-scoped from
mbeing removed from them
Mrelease post due dates
M, 22nd: Release shipped to production | Release post published
Note that elease timelines are overlapping. For example, when a release is shipped to production on the 22nd, the scope for the following release has already been established earlier in that same month.
An in scope issue already has a docs starter blurb (written by the PM) by the time engineers start development. Engineers should create and merge in the updated docs as part of completing an issue by the 7th. PMs revise the starter docs blurbs in the release post appropriately before the release post is published.
We schedule issues month to month. But PMs plan a few releases in advance and have a high-level idea of which issues will likely be scheduled. PMs will label these issues with the
coming soon label. This is a signal for all stakeholders that these are candidates, but not guaranteeing scheduling in a particular release, or even at all. The
coming soon label will be removed from an issue by a PM when it is scheduled for a release, or if it is no longer a candidate for an upcoming release. In addition, PMs will also label any of these issues with the
UX label if they require attention from the UX team. The combination of these two labels in an issue helps the UX team prioritize design work on a given issue, before it is scheduled for a release (wherein the engineering team works on it). Refer to the UX Workflow for further details.
We only ship in a Minimally Viable Product mode. Here are some guidelines about it:
Before shipping a new or updated feature, you are responsible for its evangelization, both internally and externally. When something is released, the following teams need to be aware of it as they will all need to do something about it:
You can promote your work in several ways:
To promote a major new feature internally, you can ask to host a GitLab University, a company wide demo session. This is a great opportunity to make sure every one is on the same page.
Major features deserve proper attention from product and marketing. With a proper rollout, we'll have ample marketing opportunities and receive more feedback ahead, during and after the release.
Here is the ideal rollout schedule. For each step, there is the indication about who is responsible for it.
Rejecting a feature request or a merge request is not an easy thing. People can feel quite protective of their ideas. They might have invested a lot of time and energy in writing those ideas. You can be tempted to accept a feature only to avoid hurting the people who thought of it. Worst, if you reject an idea too harshly, you might discourage other people to contribute, which is something we want to avoid.
However, as the number of issues and merge requests grow more and more, we should be diligent about rejecting features we are sure will not do. It's better for everyone: for the product team so we don't maintain a huge backlog of things we will not do anyway, and for the users who won't have to wait for our feedback indefinitely.
Note: it's fine to not respond to issues that we think have potential until they gather momentum.
Feature requests and merge requests can be rejected for the following reasons:
Don't forget to thank the authors for the time and effort taken to submit the feature request/merge request. In all cases and without exception, you should be nice and polite when interacting with users and customers.
As a PM you're expected to:
It's important to get direct feedback from our customers on things we've built, are building or should be building.
As a PM you should have regular meetings with customers that are using the things you've been working on and with customers that are not - in order to get an idea of why they're not switching to our solution.
To setup a customer meeting, identify what you're interested in discovering and prepare appropriately.
You can find information about how customers are using GitLab through sales and version.gitlab.com. Sales and support should also be able to bring you into contact with a customer.
There is no formal internal process to schedule a customer meeting, if that need arises, we can formulate one.
During the meeting, spend most of your time listening and obtaining information. It's not your job to sell GitLab, but it should be obvious when it's the time to tell more about our products.
After the meeting, make sure all your notes and feedback lands in issues.
There are two EE tiers: Starter and Premium.
EE Starter features are more relevant for organizations that have more than 100 potential users.
EE Premium features are more relevant for organizations that have more than 750 potential users.
Deciding on whether something should be a Premium feature or just a EE-only feature can be tough. In doubt, make it a Premium feature, that's a reversible option, whereas the alternative is not.
When talking about why a certain change is limited to Enterprise Edition in public, mention the stewardship paragraph in the about page directly and link to it.
All EES and EEP features should:
EE usage: dev.gitlab.org account
Grafana: Google gitlab.com account
Kibana: dev.gitlab.org account
LogTrail: dev.gitlab.org account
Piwik: GitLab 1Password account
S3stat: GitLab 1Password account
Sentry: dev.gitlab.org account
As PM we need to constantly write about the features we ship: in a blog post, internally to promote something, in emails sent to customers.
While we want every PM to have his unique voice and style, there are some guidelines that one should take into account when writing about features. Let's highlight them with a concrete example, Preventing Secrets in your repositories, that we've shipped in 8.12.
It's a bad idea to commit secrets (such as keys and certificates) to your repositories: they'll be cloned to the machines of anyone that has access to the repository, only one of which has to be insecure for the information to be compromised. Yet it happens quite easily. You write
git commit -am 'quickfix' && git pushand suddenly you've committed files that were meant to stay local!
GitLab now has a new push rule that will prevent commits with secrets from entering the repository.
Just check the checkbox and GitLab will prevent common unsafe files such as .pem and .key from being committed.
For every monthly release, there is a blog post announcing features. The blog post should contain anything exciting or disruptive. We want to help people understand exciting features (which are often new), and increase adoption. Disruptive features may change workflows or even introduce unavoidable inconveniences. We want to anticipate questions and avoid confusion by communicating these changes through the blog post. Smaller tweaks and bug fixes don't necessarily need to be mentioned, but if interesting, can be included at the bottom of the post.