Creating merge requests

Making a Merge Request

Once you have pushed commits to a branch in an issue fork and believe the code is ready for review and testing, you can create a merge request. A merge request is a formal proposal to integrate your changes into the target branch of the main repository.

There are various ways to reach the "New merge request" form on GitLab at git.drupalcode.org. For example, you may be invited to make a merge request after pushing changes in GitLab's Web IDE. Here is one procedure to make a merge request from an issue page on Drupal.org:

1. Go to the issue page and locate the Issue fork section.
2. Find the branch you’ve been working on and click “Compare”. This will take you to the Compare revisions page on GitLab. It's a good idea to open the page in a new browser tab so you can refer back to the issue page.
3. If you aren’t already logged in, do so using the "Sign in" button at the top right.
4. Review your changes. When you are ready, click the "Create merge request" button.

Filling out the "New merge request" page

When you reach the "New merge request" page, you'll need to complete the following fields and options. There are a lot of options on this form, but many of them can be left unchanged.

1. Source and target branches
   • From: Verify that the source branch (e.g., issue/media_entity_remote_image-3500941) is correct. This is the branch in your fork containing the changes.
   • Into: Confirm that the target branch (e.g., project/media_entity_remote_image:8.x-1.x) is the correct branch in the main repository. Use the Change branches link if adjustments are needed.
2. Title (required)

   Provide a concise, descriptive title summarizing the purpose of the merge request.

   Format the title as: Issue #issue_number: brief_description.

   Example: Issue #3467675: Make URL field required by default.

3. Mark as draft

   Use this option if the merge request is still a work-in-progress and not ready for review. Drafts cannot be merged until marked as ready. Default: unchecked.

4. Description

   The "Choose a template" menu can be ignored. By default, the description is simply "Closes #issue_number", but you should provide a detailed explanation of the changes made in this merge request. Include:

   • A brief summary of the problem being solved.
   • Key changes or features introduced.
   • Any known limitations or follow-up work needed.

   Use the available Markdown formatting for clarity, such as headings, bullet points, or code blocks.

5. Assignees

   If you wish to specifically assign one or more specific maintainers to merge the request, you can choose them from this menu. Generally you can leave it unassigned. Maintainers should be notified about merge requests anyway. Default: "Unassigned".

6. Reviewers

   Add one or more reviewers if specific individuals need to review the code. Leave blank if no specific reviewers are required. Default: "Unassigned".

   Additionally, you can click "Approval rules" to set specific requirements that must be met before the merge request is approved. This is usually not necessary.

7. Milestone

   If the merge request is tied to a specific milestone in the project, select it here. Otherwise, leave this field empty.

8. Labels

   This can be left blank, or you can add appropriate labels to categorize the merge request. This is not usually necessary as categorization of issues is handled on the issue's page on Drupal.org.

9. Merge request dependencies (optional)

   You can make this a dependent merge request by listing any other merge requests that must be merged before this one can proceed. This helps reviewers understand the dependency chain and ensures merges occur in the correct order.

   Format references as path/to/project!merge_request_id. For example:

   • media_entity_remote_image!123: Refers to merge request 123 in the media_entity_remote_image project.
   • core/drupal!5678: Refers to merge request 5678 in the core/drupal project.
10. Merge can start

    Here you can set a scheduled date for the merge to start, assuming that merge checks (tests, approvals etc.) pass. Leave as the default, "Anytime", if there is no reason for a delay.

11. Merge options
    • Delete source branch when merge request is accepted:

      Check this box to automatically delete the source branch after the merge is completed. This helps keep the repository clean unless the branch will be reused. Default: Unchecked.

    • Squash commits when merge request is accepted:

      Check this box to combine all commits in the merge request into a single commit. Squashing is recommended for a clean and readable project history. Default: Checked.

12. Contribution

    Allow commits from members who can merge to the target branch:

    This is recommended to allow maintainers to collaborate by pushing commits to your branch. Default: Checked.

When the form is complete, click "Create merge request" to submit the request. If the form is valid, you will be redirected to the overview page for the merge request. Here you can see if the merge request is ready to merge, has conflicts, or needs work.

If you now refresh the issue page on Drupal.org, you will see a link to the merge request in the source branch's section, for example "MR !24 mergeable".

Adding Commits to a Merge Request

When you create a merge request for a branch in a fork, it links that branch to a branch in the main repository. If you make additional commits to the same branch in that fork, these commits will automatically be included in the existing merge request.

Each new commit will:

• Trigger a new run of the automated tests.
• Generate a notice in the associated issue with:
  • A link to the updated merge request.
  • A link to compare the latest and previous revisions.

This seamless integration ensures that all changes are reflected in real-time within the merge request.