merge-request.md

title: How to create a merge request
summary: Explains a common method to create a merge request.
authors:
    - Maurice Zimmnau
date: 2024-09-25

How to create a merge request (MR)

You have already implemented an improvement to the current code base or intend to? Awesome 😎 Follow these steps to create a merge request (MR) from your forked repository:

• First, make sure you have read How to contribute to UNICADO
• Then, proceed with the steps below:

There are several ways to create a merge request within GitLab, which are explained in detail in the official GitLab docs.

However, we will highlight the workflow, we prefer - but feel free to make your own choice.

Preferred Merge Request Workflow for a Forked Repository

This is the first and preferred way to make a merge request, as it is similar to our previous UNICADO workflow. Let's assume you have forked( if you are not a direct member of UNICADO project) and cloned the Unicado Package repoistory and updated all it's submodules following Get Source Code. Open your preferred IDE (e.g., Visual Studio Code). Ensure that Git is integrated within your IDE. Most IDEs, such as VSCode, have built-in Git integration. Go to the sub module where you want to make the change. Create your own (local) branch, where you are developing a new feature / fixing bug / addong documentation. For a more detailed explanation of the steps mentioned below, watch the Merge Request Workflow video.

1. Configure Remotes:

Verify and set up remotes for your fork and the upstream repository:

git remote -v

Add the original UNICADO repository as the upstream remote:

git remote add upstream git@gitlab.com:unicado/unicado.git

2. Create a New Branch

Create a new branch from main to work on your feature or bug fix. The main branch contains the stable version of the code and ‘main’ is the default branch (i.e., the branch you check out when cloning the repository). Developers are not allowed to push directly to this branch. All changes must go through branch and a merge request process.

git checkout -b <new-branch-name>  # Create a new branch

Where is the branch where developers work on new features or bug fixes. Each developer creates their own branch from the main branch. After completing changes on the new branch, a Merge Request (MR) is created to merge the changes into the main branch. Once the MR is reviewed and approved, it gets merged into main.

Make sure your branch name follows this convention:

• feature/your-feature # Changes which brings in new feature
• bugfix/your-bugfix # Changes which fixes bug
• documentation/your_documentation #Changes which adapt existing documentation / Adding new documentation.

This ensures your branch can be pushed successfully.

3. Make Changes

Modify the submodule files as needed.

4. Stage and Commit Your Changes

After making your changes, stage them using the git add command:

git add .  # Stage all modified files

Next, commit your changes with a meaningful commit message:

Guidelines for a Good Commit Message

• Title: A short description of what the commit does (use present tense).
• Body: Explain why and how the change was made. Include any relevant details, such as specific files changed or issues addressed. Should be clear and concise. Use English language.
• Reference: Mention related issues or tickets (if applicable). Use the # to close and refer to issues.

Before committing, ensure that your code is working as expected by running local tests (such as static code analysis) and avoid committing code that is not functioning properly.

5. Push Changes to Your Fork

Push your branch to your forked repository on GitLab:

git push origin <new-branch-name>

If you are working on this branch locally, and it is not shared with remote ☁️, then you have to push it ⏫ to remote, first in order to create a merge request.

6. Create a Merge Request (MR) to the Original Repository

To propose your changes to the original UNICADO repository:

1. Go to the original UNICADO repository on GitLab.
2. Click Create Merge Request.
3. Set your forked repository's as the source branch and main in the original repository as the target branch.
4. Fill out the MR details:
   • Provide a clear title and description of your changes.
   • Use available MR templates for consistency.( You can choose one available from the available templates. These templates are saved in merge_request_templates folder inside .gitlab)
5. Add reviewers who will assess your changes (e.g., project maintainers). -Reviewers will leave comments or request changes. -Make the necessary updates locally, commit them, and push to the same branch. In case you need to commit adaptions, check the Guidelines for a Good Commit Message again!
6. After pushing your branch, the Continuous Integration (CI) pipeline will run automatically for the MR. CI checks ensure that your code meets the project’s quality standards and passes all tests.
   • Monitor Pipeline Status: Once your MR is created, GitLab will display the pipeline status in the MR. Look for ✅ (success) or ❌ (failure).
   • Fixing CI Failures: Open the pipeline logs to identify the issue. Fix the problem in your local branch. Commit and push the updates:

📝 As a reviewer, don't close the merge request. It will be closed automatically, when the merge is completed.

📝 Choose squash as merge strategy, to keep the git history streamlined

7. Approval, Merge and clean up

The reviewer(e.g., project maintainers) will merge your branch into the main branch. GitLab automatically deletes the source branch() if "Remove source branch" is selected during the merge. Additionally, you can close the related issue, which should have been resolved by the MR.

By following these steps, you ensure that your contributions are properly tracked, reviewed, and merged with minimal disruption to the project.

📝 You can also perform the git operations via your tool of choice, e.g. VSCode