Basic GitLab merge request workflow¶

Dataset updates in the ANC are handled through GitLab issues and merge requests. This workflow makes proposed changes visible, keeps a record of what was changed and why, and allows Data Stewards to review updates before they become part of the dataset.

For most users, the important idea is simple: each dataset update should start with an issue, and the actual changes should be made through a merge request linked to that issue. A merge request creates a separate working branch for the proposed changes, so that the main dataset version is not changed directly.

Step 1: Create an issue¶

Whenever changes are required in the data repository, create an issue describing the proposed changes.

To create an issue:

1. Navigate to your dataset project in the ANC GitLab.
2. In the left sidebar, select Plan > Work items, and then, in the upper-right corner, select New item.
3. From the Type dropdown list, select Issue if it is not already selected.
4. Complete the fields:
   • Title: Briefly describe what needs to be done.
   • Description: Provide a detailed description and relevant context for the proposed updates.
   • Assignee: Select the person responsible for maintaining this issue.
5. Select Create Issue.

Step 2: Create a merge request¶

After creating an issue, create a merge request from that issue.

When you create a merge request from an issue, GitLab creates a new branch(1) and a merge request(2).

To create a merge request:, navigate to your issue and click on Create merge request button on the right-handed side.

1. Navigate to your issue. In the left sidebar, select Plan > Work items, then filter by Type = Issue, and select your issue.
2. Go to the bottom of the issue description.
3. Select Create merge request.

4. On the dialog:

   • Keep Target branch set to main.
   • Review the suggested Source branch name. The branch name should be available. If the branch name is already taken, or you need a different branch name, rename it.

   Avoid duplicate branches

   Before clicking Create merge request, check whether a branch or merge request already exists for this issue. GitLab creates the branch immediately after you click Create merge request on the dialog. If you leave the next page without creating the merge request, the branch may still exist. Creating another merge request from the same issue can then result in duplicate branches.

   • Select Create merge request.

5. In the new window, complete the fields:

   • Description: Provide a summary of the changes planned for this merge request. Keep the line with Closes #<issue id>; it will automatically close the issue for which this merge request was created.
   • Assignee: Select the person responsible for completing this merge request.
   • Leave all other fields with their default values.
6. Select Create merge request.

Step 3: Work on the requested changes¶

You can now start working on the requested changes. Depending on the type of change, you can either:

• work remotely in the browser
• work locally on your computer

Step 4: Review changes¶

To view all changes made in a merge request:

1. Navigate to your merge request. In the left sidebar, select Code > Merge requests and your merge request.
2. Select Changes tab. In this view, all modified files and their changes can be inspected.

Step 5: Request review and merge of changes¶

After all changes described in the issue have been implemented, request a review from your Data Steward:

1. Navigate to your merge request. In the left sidebar, select Code > Merge requests, and then select your merge request.
2. Optional. If changes are complex, summarize them in the merge request description field. You can edit the description by selecting Edit in the upper-right corner of your merge request view.
3. In the right sidebar, in the Reviewer section, select Edit and choose the responsible Data Steward.

The Data Steward will be notified about your request and review the changes. If the changes are approved, the Data Steward will merge them into the main branch of the dataset repository.