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.
@ mentionthe design DRI to ensure requirements are met. The design DRI should then notify the suggested UX reviewer to complete the MR review when ready.
Community submitted MRs require more context to review and are assigned to the design DRI of the group it impacts. 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.
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.
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.
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 Preview, test, and contribute. If you get stuck, don't struggle on your own, check our help section.
Some MRs have additional set up requirements.
To generate project vulnerabilities, execute
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
To populate a merge request with vulnerabilities, follow these steps.
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.