This page outlines the guidelines for Product Designers when reviewing merge requests (MRs), also called “UX reviews” or “Product Design MR reviews”.
Almost all merge requests (MRs) change the UX in one way or another, but Product Designers are only required to review and approve MRs that include user-facing changes. Per the approval guidelines, “user-facing changes include both visual changes (regardless of how minor) and changes to the rendered DOM that impact how a screen reader may announce the content.”
MRs with only backend changes sometimes affect the UX (for example, performance changes, sorting of lists, etc.), but you are not required to review them unless they fall under the definition of “user-facing changes”.
To help triage, be aware of all MRs in your stage group and ask engineers about which MRs could affect the UX and how. Product Designers often give constructive feedback on any kind of MR, including MRs that seem to not affect the UX, so use your best judgment when deciding which MRs you should review.
The GitLab Roulette will randomly suggest a designer to review. These MRs should have a well-documented design solution. Your role as a reviewer is to ensure the solution is developed as intended. After you've completed your review, cc the design DRI of the group for awareness. Additionally, if you have further feedback on a particular UX solution, open a follow-up issue and mention the design DRI.
@ mention
the design DRI to ensure requirements are met. The design DRI should then notify the suggested UX reviewer to complete the MR review when ready.
~"Internal hackathon"
. The design solution is likely being solved at the time of development.Community submitted MRs require more context to review and are assigned to the design DRI of the group it impacts (What if a team doesn't have a designer?). All UX-related community contributions will generate a Slack message in the #ux-community-contributions
channel and will be manually assigned until we automate the process.
Single Engineer Group (SEG) MRs often require more active collaboration and additional context on the work. UX-related MRs created from a SEG should be reviewed by the design DRI of the group it impacts (What if a team doesn't have a designer?).
MRs created by the UX Paper Cuts team will be handled by the UX Paper Cuts team. If one of the two designers are OOO, then the team will utilize the GitLab Roulette to help distribute MR reviews across the Product Design subdepartment.
In cases where there is no design DRI to review the MR, you can assign it to Pedro Moreira da Silva (@pedroms
), who's covering for teams without a designer.
For general guidance for teams without a designer, see Product Processes.
MR review requests are the number one priority for Product Designers. Respond to them per our review-response Service-Level Objective.
Balancing MR reviews with other priorities is a challenge, as they can be unpredictable. To avoid disruptions and context-switching, we suggest you block some time every day to review MRs (for example, 30 minutes or 1 hour per day).
If you're struggling with MR reviews, remember to manage expectations with MR authors and let your manager know right away so they can help you.
Before taking up a review, make an estimation of your capacity keeping in mind any upcoming time off. If you are unsure of completing the review before leaving for a time off, spin the roulette again to assign the review to a different designer and set the appropriate GitLab or Slack status to avoid Danger bot assigning you to more merge requests reviews.
Community contributions are not assigned for reviews through Danger Bot. Work with your manager to communicate and negotiate with the merge request author if your capacity is limited, or in case of upcoming time off.
In general, follow the Code Review guidelines (it's a long document, but please read all of it). Exceptions to those guidelines are noted below.
~"UX"
label may not have a design DRI or proposed designs associated with the change. In these cases, it is important to get as much context as you can about the change. If you are unsure how the changes impact other areas of the product, consider bringing in other designers and your design manager to help evaluate the impact of the proposal.Always review the MR in a live environment, so that you can experience the changes as our users will and review them thoroughly. To choose the most appropriate method to preview the MR and get started, see Review, test, and contribute. If you get stuck, don't struggle on your own, check our help section.
Some MRs have additional set up requirements.
Checkout the branch in the MR and open rails console using bin/rails console
.
1. Edit compute minutes
ApplicationSetting.current.update(shared_runners_minutes: 400)
project = Project.find(20)
root_namespace = project.root_namespace
namespace_usage = Ci::Minutes::NamespaceMonthlyUsage.find_or_create_current(namespace_id: root_namespace.id)
Ci::Minutes::NamespaceMonthlyUsage.update_counters(namespace_usage, amount_used: 100, shared_runners_duration: 100)
project_usage = Ci::Minutes::ProjectMonthlyUsage.find_or_create_current(project_id: project)
Ci::Minutes::ProjectMonthlyUsage.update_counters(project_usage, amount_used: 100, shared_runners_duration: 100)
Type :wq
to exit the log lines. Do not exit the rails console.
2. Add helper method to rails console
def increase_ci_usage(project:, date:, amount_used:, shared_runners_duration:)
date = date.utc.beginning_of_month
project_usage = Ci::Minutes::ProjectMonthlyUsage.where(date: date).safe_find_or_create_by(project_id: project.id)
Ci::Minutes::ProjectMonthlyUsage.update_counters(project_usage, amount_used: amount_used, shared_runners_duration: shared_runners_duration)
root_namespace = project.root_namespace
namespace_usage = Ci::Minutes::NamespaceMonthlyUsage.where(date: date).safe_find_or_create_by(namespace_id: root_namespace.id)
Ci::Minutes::NamespaceMonthlyUsage.update_counters(namespace_usage, amount_used: amount_used, shared_runners_duration: shared_runners_duration)
end
3. Use helper method
increase_ci_usage(project: project, date: 1.month.ago, amount_used: 10, shared_runners_duration: 20)
The usage quota page should now reflect the changes data.
GITLAB_QA_ACCESS_TOKEN=XXXXXXXXXX GITLAB_URL="https://gitlab.com" bundle exec rake vulnerabilities:setup\[<Project_Id>,<Vulnerability_Count>\] --trace
from the gitlab/qa
directory. Make sure to replace the placeholders in the script with your local access token, project ID, and desired number of vulnerabilities. An example of this might be GITLAB_QA_ACCESS_TOKEN=asdfASDF1234- GITLAB_URL="http://localhost:3000/" bundle exec rake vulnerabilities:setup\[25,10] --trace
incoming_email
, service_desk_email
and MailRoom. These MRs can't be reviewed on GitPod and need a working GDK. Follow the set up instructions in the GDK docs or this video walkthrough.If you find yourself struggling to get your environment set up, try reaching out to the design DRI for help with the specific testing requirements. If you're still having difficulties after an hour or so, it's perfectly acceptable to hand the MR over to the design DRI for review completion. If you have time it might be worthwhile to shadow the design DRI to watch and learn how they complete the MR review.
| This MR | Expected |
|-------------|-------------|
| Image/video | Image/video |
UX debt
(learn more about this label in how we use labels).The Product Design merge request (MR) review volume is tracked as a Key Performance Indicator (KPI) of the UX department.