Contributing Workflow

Git Branching

The gstlal team uses the standard git-branch-and-merge workflow, which has brief description at GitLab and a full description at BitBucket. As depicted below, the workflow involves the creation of new branches for changes, the review of those branches through the Merge Request process, and then the merging of the new changes into the main branch.

git-flow

Git Workflow

In general the steps for working with feature branches are:

  1. Create a new branch from master: git checkout -b feature-short-desc

  2. Edit code (and tests)

  3. Commit changes: git commit . -m "comment"

  4. Push branch: git push origin feature-short-desc

  5. Create merge request on GitLab

Merge Requests

Creating a Merge Request

Once you push feature branch, GitLab will prompt on gstlal repo home page. Click “Create Merge Request”, or you can also go to the branches page (Repository > Branches) and select “Merge Request” next to your branch.

mr-create

When creating a merge request:

  1. Add short, descriptive title

  2. Add description

    • (Uses markdown .md-file style)

    • Summary of additions / changes

    • Describe any tests run (other than CI)

  3. Click “Create Merge Request”

mr-create

Collaborating on merge requests

The Overview page give a general summary of the merge request, including:

  1. Link to other page to view changes in detail (read below)

  2. Code Review Request

  3. Test Suite Status

  4. Discussion History

  5. Commenting

mr-overview

Leaving a Review

The View Changes page gives a detailed look at the changes made on the feature branch, including:

  1. List of files changed

  2. Changes

    • Red = removed

    • Green = added

  3. Click to leave comment on line

  4. Choose “Start a review”

mr-changes

After review started:

  1. comment pending

  2. Submit review

mr-changes

Responding to Reviews

Reply to code review comments as needed Use “Start a review” to submit all replies at once

mr-changes

Resolve threads when discussion on a particular piece of code is complete

mr-changes

Merging the Merge Request

Merging:

  1. Check all tests passed

  2. Check all review comments resolved

  3. Check at least one review approval

  4. Before clicking “Merge”

    • Check “Delete source branch”

    • Check “Squash commits” if branch history not tidy

  5. Click “Merge”

  6. Celebrate

mr-merge