Design Review Process

1. You are here:
2. Engineering
3. UX Department
4. Pajamas Design System
5. Design Review Process

Maintained by:

On this page

• On this page
• Overview
• Reviewer
• Maintainer
  • Maintainer types
  • How to become a maintainer
    • Trainee maintainer
      • Duration
  • Maintainer ratios
    • Current trainee maintainers

Overview

Design reviews are mandatory for every merge request in these projects:

1. design.gitlab.com
2. gitlab (merge requests that have the UX label)
3. gitlab-svgs
4. gitlab-ui

All designers are maintainers of the gitlab-design project. If you are interested in becoming a Maintainer of UI (.scss) for gitlab, and gitlab-ui projects, please follow the Engineering Review Workflow.

To perform a review, you should familiarize yourself with and follow our Code Review Guidelines, Design Contribution Guidelines, and the contribution guidelines for every aforementioned project.

You can find all design reviewers and maintainers by looking on the team page and filtering by UX Department or on the list of GitLab Engineering Projects, both of which are fed by data/team.yml file.

These guidelines describe who would need to review, approve, and merge your (or a community member's) merge request.

Reviewer

All GitLab designers can (and are encouraged to) perform design and code reviews on merge requests that impact product design. This includes contributions from GitLab Team Members and the wider GitLab community. If you want to review merge requests, you can wait until someone assigns you one, but you are also more than welcome to browse the list of open merge requests and leave any feedback or questions you may have.

Note that while all designers can review all merge requests, the ability to accept merge requests is restricted to maintainers.

Maintainer

Maintainers are GitLab designers who:

• Are experts at design and code review, including reviewing commit messages.
• Know the GitLab product, design guidelines, and code base very well.
• Are empowered to accept merge requests in one or several GitLab Engineering Projects.

Every project has at least one maintainer, but most have multiple, and some projects (like gitlab-ui and design.gitlab.com) have separate maintainers for design and frontend.

As with regular reviewers, design maintainers can be found on the team page or on the list of GitLab Engineering Projects.

Read more about what makes great maintainers in the Engineering Review Workflow.

Maintainer types

Design maintainers are divided into types of maintainership. This helps maintainers specialize, but more importantly, it helps speed up the process of becoming a maintainer, and with knowing who to ask for final acceptance of merge requests. New types can be created or existing ones refactored to accommodate the natural evolution of projects.

How to become a maintainer

We follow the same maintainer guidelines as our Engineering counterparts. Get familiar with those guidelines and how to become a maintainer in the Engineering Review Workflow.

Three key aspects of that process:

1. “Maintainer-level” merge requests: Candidates should have specific examples of recent “maintainer-level” merge requests. They can work on any kind of merge request, but “maintainer-level” ones are the focus of the maintainership. “Maintainer-level” merge requests are described in the Engineering Review Workflow.
2. Reviews or contributions: Contributing merge requests also counts. Whether merge requests are reviewed or contributed by a candidate, they should consistently make it through reviewer and/or maintainer review without significant required changes.
3. Traineeship optional: The trainee maintainer program (traineeship) supports reviewers in becoming maintainers, but the program is not a requirement. Designers that have been recenly involved in a fair amount of “maintainer-level” merge requests can become maintainers without the traineeship. Anyone can nominate oneself (or someone else) for maintainership, following the process described in the Engineering Review Workflow.

Trainee maintainer

We're not able to support more trainees at the moment. Even so, we still encourage people to nominate themselves if they're interested! We'll accomodate them once we have a Support Maintainer available for them.

We follow the same trainee maintainer program (traineeship) as our Engineering counterparts. Anyone may nominate themselves as a trainee by opening a tracking issue using the Trainee design maintainer template.

For the traineeship, a design maintainer is assigned as Support Maintainer to each trainee. The Support Maintainer will direct merge requests for review, give feedback on proposals, and discuss process or progress during 1:1 sessions. Trainees can always reach out to their managers or other maintainers for feedback and guidance separate from the dedicated Support Maintainer. We've also created a Pajamas UX maintainer review checklist to help guide trainee maintainers as they learn to review Pajamas MRs.

We try to keep a maximum of one trainee per maintainer, so that maintainers are not overloaded with their additional role as Support Maintainers and can provide adequate guidance. See our current trainee maintainers.

Duration

The traineeship is a long commitment, usually several months, and takes away time from other responsibilities. If you're interested in enrolling in this program, please talk with your manager and team before nominating yourself, as the traineeship is likely to impact your capacity.

There are two aspects that play a big part in the duration of the traineeship: the number of hours that are dedicated to it and the number of available merge requests for the trainee. When these two aspects oppose each other, the traineeship can take longer than expected:

1. Many hours, few merge requests: To increase the number of merge requests, the trainee can always make their own contributions. Reviewing merge requests from others is not the only way to become a maintainer. The trainee must be creative and try to work on “maintainer-level” merge requests as much as possible.
2. Few hours, many merge requests: Trying to review or contribute many merge requests in few hours can have a negative effect on quality. The trainee should focus on quality because that is what is evaluated. They should also follow our first-response Service-level Objective (SLO). If the trainee wants to speed up the traineeship, they should talk with their manager to find ways to balance their workload and free up more time for this program.

To help track progress, we encourage trainees to make the traineeship one of their personal OKRs.

Maintainer ratios

See the Pajamas maintainer ratio dashboard.

Current trainee maintainers