Skip to main content

How to Structure a Merge Request

Introduction​

This tutorial is for frontend developers working in our GitLab + Jira environment. It explains how to properly name your branches and format merge requests (MRs) for clarity, consistency, and ease of review.

By following this guide, you'll ensure your work is:

  • Easy to understand at a glance
  • Linked automatically to the correct Jira ticket
  • Clear about what changed and why

This tutorial covers:

  • Branch naming conventions
  • How to format MRs for different types of changes
  • When to include images or videos

Step 1: Name your branch correctly​

Branch naming matters, both for automation and for team clarity.

Use this pattern:

<ticket-type>/<project-key>-<ticket-number>-<description>

Examples:

  • task/CRM-1048-add-user-dropdown
  • bugfix/APP-232-fix-dropdown-spacing
  • chore/DSGN-99-update-color-tokens

Ticket type prefixes​

PrefixWhen to use
feat/New features or enhancements
fix/Bug fixes
docs/Documentation updates
refactor/refactors
style/Design updates or UI redesigns
info

Use lowercase letters and separate words in the description with hyphens (-). Avoid underscores or camelCase.

Also make sure to:

  • Include the Jira ticket number and project key

Step 2: Format your MR using the default template​

When you open a new merge request, a template will be pre-filled for you. Fill it out clearly and completely — this improves code review, QA testing, and Jira traceability.

1. Title​

MR titles are important for automation and Jira ticket linking.

Use this format: <type>:<project-key>-<ticket-number> <short description>

Examples:

  • feat: CRM-1048 add user dropdown menu
  • fix: APP-232 correct dropdown spacing issue
info

Read through our Semantic Release documentation to learn more.

To trigger a major release in Semantic Release, include this in the commit body or footer:

BREAKING CHANGE: <describe what changed and what action is required>

2. General​

Provide a short summary of what the MR does (1–3 sentences). Focus on the what and why.

Example:

  • Adds support for grouped dropdown items in the UI
  • Refactors calendar week calculation logic
  • Updates to the latest wl-ui-kit version

3. Affected features​

List all major areas, components, or files this MR impacts.

Example:

  1. DropdownMenu component
  2. Calendar utils
  3. User settings panel

4. Things that should be tested additionally​

Highlight any scenarios that need extra attention during QA.

Example:

  1. Mobile responsiveness for new dropdown
  2. Week number edge cases (e.g. first/last week of year)
  3. Interaction with legacy components

5. Remarks​

Use this section for any final notes to reviewers, such as:

  • Before/after screenshots or videos if UI changed
  • Known limitations or TODOs
  • Reason for any unusual decisions

Final Checklist​

Before submitting your MR, double-check the following:

  • Branch name follows the correct format: <ticket-type>/<project-key>-<ticket-number>-<description>
  • MR title follows the correct format: <type>:<project-key>-<ticket-number> <short description>
  • The template is fully filled out

Further reading​