merge_request_workflow.md

type: reference, dev
stage: none
group: Development
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

Merge requests workflow

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 have the Seeking community contributions label, but you are free to contribute to any issue you want.

If an issue is marked for the current milestone at any time, even when you are working on it, a GitLab Inc. team member may take over the merge request to ensure the work is finished before the release date.

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 to be labeled as Seeking community contributions. See the feature proposals section.

Merge requests should be submitted to the appropriate project at GitLab.com, for example GitLab, GitLab Runner, or Omnibus GitLab.

If you are new to GitLab development (or web development in general), see the how to contribute section to get started with some potentially easy issues.

To start developing GitLab, download the GitLab Development Kit and see the Development section for the required guidelines.

Merge request guidelines for contributors

If you find an issue, please submit a merge request with a fix or improvement, if you can, and include tests.

NOTE: Consider placing your code behind a feature flag if you think it might affect production availability. Not sure? Read When to use feature flags.

If the change is non-trivial, we encourage you to start a discussion with a product manager or a member of the team. You can do this by tagging them in an MR before submitting the code for review. Talking to team members can be helpful when making design decisions. Communicating the intent behind your changes can also help expedite merge request reviews.

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. New features without proper tests might be slower to receive feedback.

To create a merge request:

1. Fork the project into your personal namespace (or group) on GitLab.com.
2. Create a feature branch in your fork (don't work off your default branch).
3. Follow the commit messages guidelines.
4. If you have multiple commits, combine them into a few logically organized commits.
5. Push the commits to your working branch in your fork.
6. Submit a merge request (MR) against the default branch of the upstream project.
7. The MR title should describe the change you want to make.
8. 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.
   2. If you are contributing documentation, choose Documentation from the "Choose a template" menu and fill in the description according to the template.
   3. Use the syntax Solves #XXX, Closes #XXX, or Refs #XXX to mention the issues your merge request addresses. Referenced issues do not close automatically. You must close them manually once the merge request is merged.
9. If you're allowed to, set a relevant milestone and labels. MR labels should generally match the corresponding issue (if there is one). The group label should reflect the group that executed or coached the work, not necessarily the group that owns the feature.
10. Read and adhere to The responsibility of the merge request author.
11. Read and follow Having your merge request reviewed.
12. Make sure the merge request meets the Definition of done.

If you would like quick feedback on your merge request feel free to mention someone from the core team or one of the merge request coaches. When having your code reviewed and when reviewing merge requests, please keep the code review guidelines in mind. And if your code also makes changes to the database, or does expensive queries, check the database review guidelines.

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 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 document from the Kubernetes team also has some great points regarding this.

Commit messages guidelines