2021-01-03 14:25:43 +05:30
---
type: reference, dev
stage: none
group: Development
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-03 14:25:43 +05:30
---
2019-12-04 20:38:33 +05:30
# Merge requests workflow
2018-11-20 20:47:30 +05:30
2019-07-07 11:18:12 +05:30
We welcome merge requests from everyone, with fixes and improvements
to GitLab code, tests, and documentation. The issues that are specifically suitable
for community contributions are listed with the [`Accepting merge requests` ](issue_workflow.md#label-for-community-contributors )
label, but you are free to contribute to any issue you want.
2021-10-27 15:23:28 +05:30
If an issue is marked for the current milestone at any time, even
2019-07-07 11:18:12 +05:30
when you are working on it, a GitLab Inc. team member may take over the merge request
2018-11-20 20:47:30 +05:30
in order to ensure the work is finished before the release date.
2019-07-07 11:18:12 +05:30
If you want to add a new feature that is not labeled, it is best to first create
an issue (if there isn't one already) and leave a comment asking for it
2021-11-18 22:05:49 +05:30
to be marked as `Accepting merge requests` . See the [feature proposals ](issue_workflow.md#feature-proposals )
section.
2018-11-20 20:47:30 +05:30
2019-07-07 11:18:12 +05:30
Merge requests should be submitted to the appropriate project at GitLab.com, for example
2020-03-13 15:44:24 +05:30
[GitLab ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests ),
2021-10-27 15:23:28 +05:30
[GitLab Runner ](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests ), or
[Omnibus GitLab ](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests ).
2018-11-20 20:47:30 +05:30
If you are new to GitLab development (or web development in general), see the
2020-05-24 23:13:21 +05:30
[how to contribute ](index.md#how-to-contribute ) section to get started with
2018-11-20 20:47:30 +05:30
some potentially easy issues.
2019-07-07 11:18:12 +05:30
To start developing GitLab, download the [GitLab Development Kit ](https://gitlab.com/gitlab-org/gitlab-development-kit )
2021-09-30 23:02:18 +05:30
and see the [Development section ](../../index.md ) for the required guidelines.
2018-11-20 20:47:30 +05:30
2018-12-05 23:21:45 +05:30
## Merge request guidelines
2018-11-20 20:47:30 +05:30
2019-07-07 11:18:12 +05:30
If you find an issue, please submit a merge request with a fix or improvement, if
you can, and include tests. If you don't know how to fix the issue but can write a test
that exposes the issue, we will accept that as well. In general, bug fixes that
include a regression test are merged quickly, while new features without proper
tests might be slower to receive feedback. The workflow to make a merge
2018-11-20 20:47:30 +05:30
request is as follows:
2019-12-26 22:10:19 +05:30
1. [Fork ](../../user/project/repository/forking_workflow.md ) the project into
2019-07-07 11:18:12 +05:30
your personal namespace (or group) on GitLab.com.
2021-09-04 01:27:46 +05:30
1. Create a feature branch in your fork (don't work off your [default branch ](../../user/project/repository/branches/default.md )).
2019-07-07 11:18:12 +05:30
1. Write [tests ](../rake_tasks.md#run-tests ) and code.
2021-09-04 01:27:46 +05:30
1. [Ensure a changelog is created ](../changelog.md ).
2018-11-20 20:47:30 +05:30
1. If you are writing documentation, make sure to follow the
2019-07-07 11:18:12 +05:30
[documentation guidelines ](../documentation/index.md ).
1. Follow the [commit messages guidelines ](#commit-messages-guidelines ).
1. If you have multiple commits, combine them into a few logically organized
commits by [squashing them ](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing ),
but do not change the commit history if you're working on shared branches though.
1. Push the commit(s) to your working branch in your fork.
2021-09-04 01:27:46 +05:30
1. Submit a merge request (MR) to the `main` branch in the main GitLab project.
2020-04-22 19:07:51 +05:30
1. Your merge request needs at least 1 approval, but depending on your changes
you might need additional approvals. Refer to the [Approval guidelines ](../code_review.md#approval-guidelines ).
2019-07-07 11:18:12 +05:30
1. You don't have to select any specific approvers, but you can if you really want
specific people to approve your merge request.
1. The MR title should describe the change you want to make.
1. The MR description should give a reason for your change.
1. If you are contributing code, fill in the description according to the default
template already provided in the "Description" field.
2018-11-20 20:47:30 +05:30
1. If you are contributing documentation, choose `Documentation` from the
2019-07-07 11:18:12 +05:30
"Choose a template" menu and fill in the description according to the template.
2021-03-11 19:13:27 +05:30
1. Use the syntax `Solves #XXX` , `Closes #XXX` , or `Refs #XXX` to mention the issue(s) your merge
request addresses. Referenced issues do not [close automatically ](../../user/project/issues/managing_issues.md#closing-issues-automatically ).
You must close them manually once the merge request is merged.
2021-04-17 20:07:23 +05:30
1. The MR must include *Before* and *After* screenshots if UI changes are made.
2021-10-27 15:23:28 +05:30
1. Include any steps or setup required to ensure reviewers can view the changes you've made (for example, include any information about feature flags).
2020-04-22 19:07:51 +05:30
1. If you're allowed to, set a relevant milestone and [labels ](issue_workflow.md ).
1. UI changes should use available components from the GitLab Design System,
2021-04-17 20:07:23 +05:30
[Pajamas ](https://design.gitlab.com/ ).
2019-07-07 11:18:12 +05:30
1. If the MR changes CSS classes, please include the list of affected pages, which
can be found by running `grep css-class ./app -R` .
1. If your MR touches code that executes shell commands, reads or opens files, or
2018-11-20 20:47:30 +05:30
handles paths to files on disk, make sure it adheres to the
[shell command guidelines ](../shell_commands.md )
2021-06-08 01:23:25 +05:30
1. If your code needs to handle file storage, see the [uploads documentation ](../uploads.md ).
2018-11-20 20:47:30 +05:30
1. If your merge request adds one or more migrations, make sure to execute all
migrations on a fresh database before the MR is reviewed. If the review leads
2019-07-07 11:18:12 +05:30
to large changes in the MR, execute the migrations again once the review is complete.
1. Write tests for more complex migrations.
1. Merge requests **must** adhere to the [merge request performance guidelines ](../merge_request_performance_guidelines.md ).
1. For tests that use Capybara, read
2019-12-21 20:55:43 +05:30
[how to write reliable, asynchronous integration tests ](https://thoughtbot.com/blog/write-reliable-asynchronous-integration-tests-with-capybara ).
2019-03-02 22:35:43 +05:30
1. If your merge request introduces changes that require additional steps when
installing GitLab from source, add them to `doc/install/installation.md` in
the same merge request.
2019-07-07 11:18:12 +05:30
1. If your merge request introduces changes that require additional steps when
upgrading GitLab from source, add them to
`doc/update/upgrading_from_source.md` in the same merge request. If these
instructions are specific to a version, add them to the "Version specific
upgrading instructions" section.
2020-04-22 19:07:51 +05:30
1. Read and adhere to
[The responsibility of the merge request author ](../code_review.md#the-responsibility-of-the-merge-request-author ).
1. Read and follow
[Having your merge request reviewed ](../code_review.md#having-your-merge-request-reviewed ).
2019-07-07 11:18:12 +05:30
If you would like quick feedback on your merge request feel free to mention someone
from the [core team ](https://about.gitlab.com/community/core-team/ ) or one of the
2019-12-21 20:55:43 +05:30
[merge request coaches ](https://about.gitlab.com/company/team/ ). When having your code reviewed
2019-07-07 11:18:12 +05:30
and when reviewing merge requests, please keep the [code review guidelines ](../code_review.md )
2019-10-12 21:52:04 +05:30
in mind. And if your code also makes changes to the database, or does expensive queries,
check the [database review guidelines ](../database_review.md ).
2019-07-07 11:18:12 +05:30
### Keep it simple
*Live by smaller iterations.* Please keep the amount of changes in a single MR **as small as possible** .
If you want to contribute a large feature, think very carefully about what the
[minimum viable change ](https://about.gitlab.com/handbook/product/#the-minimally-viable-change )
is. Can you split the functionality into two smaller MRs? Can you submit only the
backend/API code? Can you start with a very simple UI? Can you do just a part of the
refactor?
Small MRs which are more easily reviewed, lead to higher code quality which is
more important to GitLab than having a minimal commit log. The smaller an MR is,
the more likely it will be merged quickly. After that you can send more MRs to
enhance and expand the feature. The [How to get faster PR reviews ](https://github.com/kubernetes/kubernetes/blob/release-1.5/docs/devel/faster_reviews.md )
document from the Kubernetes team also has some great points regarding this.
### Commit messages guidelines
2021-01-29 00:20:46 +05:30
Commit messages should follow the guidelines below, for reasons explained by Chris Beams in [How to Write a Git Commit Message ](https://chris.beams.io/posts/git-commit/ ):
2019-07-07 11:18:12 +05:30
2021-01-29 00:20:46 +05:30
- The commit subject and body must be separated by a blank line.
2019-07-07 11:18:12 +05:30
- The commit subject must start with a capital letter.
2021-01-29 00:20:46 +05:30
- The commit subject must not be longer than 72 characters.
2019-07-07 11:18:12 +05:30
- The commit subject must not end with a period.
- The commit body must not contain more than 72 characters per line.
- The commit subject or body must not contain Emojis.
2021-04-29 21:17:54 +05:30
- Commits that change 30 or more lines across at least 3 files should
describe these changes in the commit body.
2019-07-07 11:18:12 +05:30
- Use issues and merge requests' full URLs instead of short references,
2019-09-30 21:07:59 +05:30
as they are displayed as plain text outside of GitLab.
2021-01-29 00:20:46 +05:30
- The merge request should not contain more than 10 commit messages.
- The commit subject should contain at least 3 words.
**Important notes:**
2021-09-04 01:27:46 +05:30
- If the guidelines are not met, the MR may not pass the [Danger checks ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/danger/commit_messages/Dangerfile ).
2021-01-29 00:20:46 +05:30
- Consider enabling [Squash and merge ](../../user/project/merge_requests/squash_and_merge.md#squash-and-merge )
if your merge request includes "Applied suggestion to X files" commits, so that Danger can ignore those.
- The prefixes in the form of `[prefix]` and `prefix:` are allowed (they can be all lowercase, as long
as the message itself is capitalized). For instance, `danger: Improve Danger behavior` and
`[API] Improve the labels endpoint` are valid commit messages.
#### Why these standards matter
1. Consistent commit messages that follow these guidelines make the history more readable.
2021-03-11 19:13:27 +05:30
1. Concise standard commit messages helps to identify [breaking changes ](index.md#breaking-changes ) for a deployment or ~"master:broken" quicker when
2021-01-29 00:20:46 +05:30
reviewing commits between two points in time.
2019-07-07 11:18:12 +05:30
2021-01-29 00:20:46 +05:30
#### Commit message template
2019-05-30 16:15:17 +05:30
2019-10-12 21:52:04 +05:30
Example commit message template that can be used on your machine that embodies the above (guide for [how to apply template ](https://codeinthehole.com/tips/a-useful-template-for-commit-messages/ )):
2020-05-24 23:13:21 +05:30
```plaintext
2021-09-30 23:02:18 +05:30
# (If applied, this commit will...) <subject> (Max 72 characters)
# |<---- Using a Maximum Of 72 Characters ---->|
2019-10-12 21:52:04 +05:30
# Explain why this change is being made
# |<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->|
# Provide links or keys to any relevant tickets, articles or other resources
# Use issues and merge requests' full URLs instead of short references,
# as they are displayed as plain text outside of GitLab
# --- COMMIT END ---
# --------------------
# Remember to
# Capitalize the subject line
# Use the imperative mood in the subject line
# Do not end the subject line with a period
# Subject must contain at least 3 words
# Separate subject from body with a blank line
2021-04-29 21:17:54 +05:30
# Commits that change 30 or more lines across at least 3 files should
2019-10-12 21:52:04 +05:30
# describe these changes in the commit body
# Do not use Emojis
# Use the body to explain what and why vs. how
# Can use multiple lines with "-" for bullet points in body
# For more information: https://chris.beams.io/posts/git-commit/
# --------------------
```
2019-05-30 16:15:17 +05:30
## Contribution acceptance criteria
2019-07-07 11:18:12 +05:30
To make sure that your merge request can be approved, please ensure that it meets
the contribution acceptance criteria below:
1. The change is as small as possible.
2018-11-20 20:47:30 +05:30
1. Include proper tests and make all tests pass (unless it contains a test
exposing a bug in existing code). Every new class should have corresponding
unit tests, even if the class is exercised at a higher level, such as a feature test.
2019-07-07 11:18:12 +05:30
- If a failing CI build seems to be unrelated to your contribution, you can try
2021-09-04 01:27:46 +05:30
restarting the failing CI job, rebasing from `main` to bring in updates that
2019-07-07 11:18:12 +05:30
may resolve the failure, or if it has not been fixed yet, ask a developer to
help you fix the test.
2019-07-31 22:56:46 +05:30
1. The MR initially contains a few logically organized commits.
2019-07-07 11:18:12 +05:30
1. The changes can merge without problems. If not, you should rebase if you're the
2021-09-04 01:27:46 +05:30
only one working on your feature branch, otherwise merge `main` .
2019-07-07 11:18:12 +05:30
1. Only one specific issue is fixed or one specific feature is implemented. Do not
combine things; send separate merge requests for each issue or feature.
2021-10-27 15:23:28 +05:30
1. Migrations should do only one thing (for example, create a table, move data to a new
2019-07-07 11:18:12 +05:30
table, or remove an old table) to aid retrying on failure.
1. Contains functionality that other users will benefit from.
1. Doesn't add configuration options or settings options since they complicate making
and testing future changes.
1. Changes do not degrade performance:
- Avoid repeated polling of endpoints that require a significant amount of overhead.
- Check for N+1 queries via the SQL log or [`QueryRecorder` ](../merge_request_performance_guidelines.md ).
2021-03-11 19:13:27 +05:30
- Avoid repeated access of the file system.
2019-07-07 11:18:12 +05:30
- Use [polling with ETag caching ](../polling.md ) if needed to support real-time features.
2021-10-27 15:23:28 +05:30
1. If the merge request adds any new libraries (like gems or JavaScript libraries),
2019-07-07 11:18:12 +05:30
they should conform to our [Licensing guidelines ](../licensing.md ). See those
instructions for help if the "license-finder" test fails with a
`Dependencies that need approval` error. Also, make the reviewer aware of the new
library and explain why you need it.
2021-02-22 17:27:13 +05:30
1. The merge request meets the GitLab [definition of done ](#definition-of-done ), below.
2018-12-13 13:39:08 +05:30
2018-11-20 20:47:30 +05:30
## Definition of done
2021-11-11 11:23:49 +05:30
If you contribute to GitLab, please know that changes involve more than just
2019-07-07 11:18:12 +05:30
code. We use the following [definition of done ](https://www.agilealliance.org/glossary/definition-of-done ).
2021-11-11 11:23:49 +05:30
To reach the definition of done, the merge request must create no regressions and meet all these criteria:
- Verified as working in production on GitLab.com.
- Verified as working for self-managed instances.
If a regression occurs, we prefer you revert the change. We break the definition of done into two phases: [MR Merge ](#mr-merge ) and [Production use ](#production-use ).
Your contribution is *incomplete* until you have made sure it meets all of these
2019-07-07 11:18:12 +05:30
requirements.
2021-11-11 11:23:49 +05:30
### MR Merge
2019-07-07 11:18:12 +05:30
1. Clear description explaining the relevancy of the contribution.
1. Working and clean code that is commented where needed.
1. [Unit, integration, and system tests ](../testing_guide/index.md ) that all pass
on the CI server.
2019-12-21 20:55:43 +05:30
1. Regressions and bugs are covered with tests that reduce the risk of the issue happening
again.
2019-12-26 22:10:19 +05:30
1. [Performance guidelines ](../merge_request_performance_guidelines.md ) have been followed.
2020-04-08 14:13:33 +05:30
1. [Secure coding guidelines ](https://gitlab.com/gitlab-com/gl-security/security-guidelines ) have been followed.
2019-07-07 11:18:12 +05:30
1. [Documented ](../documentation/index.md ) in the `/doc` directory.
1. [Changelog entry added ](../changelog.md ), if necessary.
2021-11-11 11:23:49 +05:30
1. Reviewed by relevant reviewers, and all concerns are addressed for Availability, Regressions, and Security. Documentation reviews should take place as soon as possible, but they should not block a merge request.
1. The [MR acceptance checklist ](../code_review.md#acceptance-checklist ) has been checked as confirmed in the MR.
2020-06-23 00:09:42 +05:30
1. Create an issue in the [infrastructure issue tracker ](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues ) to inform the Infrastructure department when your contribution is changing default settings or introduces a new setting, if relevant.
2019-07-07 11:18:12 +05:30
1. [Black-box tests/end-to-end tests ](../testing_guide/testing_levels.md#black-box-tests-at-the-system-level-aka-end-to-end-tests )
added if required. Please contact [the quality team ](https://about.gitlab.com/handbook/engineering/quality/#teams )
with any questions.
2021-11-11 11:23:49 +05:30
1. The change is tested in a review app where possible and if appropriate.
2021-04-29 21:17:54 +05:30
1. The new feature does not degrade the user experience of the product.
2021-11-11 11:23:49 +05:30
1. The change is evaluated to [limit the impact of far-reaching work ](https://about.gitlab.com/handbook/engineering/development/#reducing-the-impact-of-far-reaching-work ).
2021-11-18 22:05:49 +05:30
1. An agreed-upon [rollout plan ](https://about.gitlab.com/handbook/engineering/development/processes/rollout-plans/ ).
2021-11-11 11:23:49 +05:30
1. Merged by a project maintainer.
### Production use
1. Confirmed to be working in staging before implementing the change in production, where possible.
1. Confirmed to be working in the production with no new [Sentry ](https://about.gitlab.com/handbook/engineering/#sentry ) errors after the contribution is deployed.
2021-11-18 22:05:49 +05:30
1. Confirmed that the [rollout plan ](https://about.gitlab.com/handbook/engineering/development/processes/rollout-plans ) has been completed.
2021-11-11 11:23:49 +05:30
1. If there is a performance risk in the change, I have analyzed the performance of the system before and after the change.
1. *If the merge request uses feature flags, per-project or per-group enablement, and a staged rollout:*
- Confirmed to be working on GitLab projects.
- Confirmed to be working at each stage for all projects added.
1. Added to the [release post ](https://about.gitlab.com/handbook/marketing/blog/release-posts/ ),
if relevant.
1. Added to [the website ](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml ), if relevant.
2019-07-07 11:18:12 +05:30
2021-06-08 01:23:25 +05:30
Contributions do not require approval from the [Product team ](https://about.gitlab.com/handbook/product/product-processes/#gitlab-pms-arent-the-arbiters-of-community-contributions ).
2019-07-07 11:18:12 +05:30
## Dependencies
2018-11-20 20:47:30 +05:30
If you add a dependency in GitLab (such as an operating system package) please
2019-07-07 11:18:12 +05:30
consider updating the following, and note the applicability of each in your merge
request:
1. Note the addition in the [release blog post ](https://about.gitlab.com/handbook/marketing/blog/release-posts/ )
(create one if it doesn't exist yet).
1. [The upgrade guide ](../../update/upgrading_from_source.md ).
1. The [GitLab Installation Guide ](../../install/installation.md#1-packages-and-dependencies ).
1. The [GitLab Development Kit ](https://gitlab.com/gitlab-org/gitlab-development-kit ).
2021-09-04 01:27:46 +05:30
1. The [CI environment preparation ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/prepare_build.sh ).
2019-07-07 11:18:12 +05:30
1. The [Omnibus package creator ](https://gitlab.com/gitlab-org/omnibus-gitlab ).
2020-11-24 15:15:51 +05:30
1. The [Cloud Native GitLab Dockerfiles ](https://gitlab.com/gitlab-org/build/CNG )
2020-01-01 13:55:28 +05:30
2020-05-24 23:13:21 +05:30
## Incremental improvements
2020-01-01 13:55:28 +05:30
We allow engineering time to fix small problems (with or without an
issue) that are incremental improvements, such as:
2021-10-27 15:23:28 +05:30
1. Unprioritized bug fixes (for example, [Banner alerting of project move is
2020-03-13 15:44:24 +05:30
showing up everywhere](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18985))
2020-01-01 13:55:28 +05:30
1. Documentation improvements
1. Rubocop or Code Quality improvements
Tag a merge request with ~"Stuff that should Just Work" to track work in
this area.