Merge Request Reviews

Guidelines for Product Designers when reviewing merge requests.

Overview

This page outlines detailed guidelines for different ways of reviewing merge requests (MRs) for “UX reviews” or “Product Design MR reviews”. For step by step guidance of the full process go to the Product Design MR reviews page.

Review, test, and contribute

There are several methods for you to review, test, and contribute changes to the app, user documentation, Pajamas, GitLab UI or company handbook.

We encourage MR authors to add screenshots or videos of their changes. However as they don’t cover all review aspects (for example, hover states, small viewports, accessibility, and so on.), you cannot rely on them exclusively and should always review the MR in a live environment.

The most common methods to review the MR in a live environment are:

  • Gitpod (Get started and Help): Pre-configured cloud environment that quickly provides a clean and immediately usable app, by just clicking on a link. Can be used to run GitLab instances (using GDK, see below), user documentation, Pajamas, or company handbook.
  • GitLab Development Kit (GDK) (Get started and Help): It’s how we install and maintain GitLab instances on our local machines. However, some technical knowledge is needed, its speed depends on your local machine, and it’s quite easy for the GDK to become “broken” when it’s updated.
  • Review Apps (Get started): Unique links specifically created for each MR to preview their changes. Ideal for documentation changes (Pajamas or company handbook). Unfortunately, previewing a GitLab instance is very limited compared to other methods (improvements epic).
  • Sync with author: Although we have a bias towards asynchronous communication, sometimes it’s more productive to have a one-on-one sync with the MR author. Can be especially helpful if changes are hard to test or reproduce.
Comparison table to choose most appropriate method
Gitpod (cloud) GDK (local) Review App Sync with author
First start* 🏃‍♀️ Fast (<5 min) 🐢 Very slow (30+ min) GitLab (>30 min)
Docs (>20 min)
Pajamas (~10 min)
Handbook (~10 min)		 🏃‍♀️ Fast (few mins)
Restarts 🏃‍♀️ Fast (<2 min) 🤷 Depends† 🚀 Very fast (secs) 🏃‍♀️ Fast (few mins)
Make changes ✅ ✅ ❌ ✅
Preview/test ✅ ✅ ✅ ✅
Save state§ ✅ ✅ ✅ N/A
Toggle feature flags ✅ ✅ ✅ ✅
Test data ✅ ✅ ✅ N/A

*: The time needed to preview changes for the first time. Depending on the method it includes steps like installation, build, deployment, etc.
†: When using a local GDK, the time it takes to restart it depends heavily on your local machine specifications.
§: Ability to save the current environment state, including its data, license information, feature flags (if applicable), etc.
: Only applicable for GitLab instances. Test data includes pre-created users, projects, branches, issues, merge requests, epics, etc.

Contributing

GitLab is a complex platform that helps teams shorten cycle times, reduce costs, stregthen security, and increase developer productivity. In order to make the DevOps lifecycle more approachable for all users, it is essential that each member of the Product Design department has general knowledge of Git and DevOps flows by frequently using the various features across the product.

The Product Design department builds confidence in these areas by using the product in a live environment and contributing small fixes to the various projects that make up GitLab, including the app, user documentation, Pajamas, and GitLab UI. Designers are not expected to be full stack developers, but we do expect designers to grow their basic development skills to build empathy and understanding for the workflows our users experience on a daily basis.

Additionally, building these skills has the added benefit of empowering designers to directly make small, meaningful changes to the product. Migrating components or updating UI copy, for example, improves the consistency, visual design, and accessibility of the app.

Gitpod

To use Gitpod you must create a Gitpod account (free) and connect it to your GitLab account. If you launch Gitpod from any project on GitLab.com your accounts are automatically connected (see links below). If for some reason that doesn’t work, see how to manually connect your GitLab.com account.

GDK

Review Apps

You can enable a feature flag by sending an API request to the review app using a tool such as curl or Postman.

Help!

If you get stuck using any of these methods, follow the tips below in order. Don’t struggle on your own and, when in doubt, ping a UX member to facilitate finding the right help.

  1. If using GDK (locally or in Gitpod), first try to troubleshoot it yourself, but don’t hesitate to reach out for help (see points below) when you’re unsure about the problem.
  2. Gitpod
    1. Ask for help in the #gitpod-gdk Slack channel.
    2. Reach out to a UX help volunteer: Marcel van Remmerden (add yourself!)
  3. GDK
    1. Review the getting help.
    2. Ask for help in the #gdk Slack channel.
    3. Reach out to a UX help volunteer: Taurie Davis, Sunjung Park (add yourself!)
Last modified November 15, 2023: Fix markdown and image issues in UX (bed95a10)
View page source - Edit this page - please contribute. Creative Commons License