Effective development using Git

Now that we are using GitLab for our repositories, there are a number of useful features in git that we will begin to use more.

Branches

Branches are your friend.

Rather than commiting directly to `master`, you should develop on a branch. Feel free to push your branch to the repository on GitLab.

Commit early, commit often!  — but do it on a branch!

Merge to Master

Rather than pushing directly to master,

1. Create a branch and commit to that as needed.
2. Push the branch to origin on GitLab.
3. Create a merge request (see section below). The project owner will then review your changes and merge once ready.

Creating a merge request

When you have a branch that you feel is ready for review to be merged into master, create a merge request.

1. Log into GitLab
2. Select the project, and ensure that you have already pushed your branch.
3. On the left-side navigation menu, select `Merge Requests`
4. Click the `New Merge Request` button
5. Select the branch that you want to merge and choose the destination (master)
6. Fill in the name of the merge request (e.g., “Adding a regression test for feature XYZ”), and add a description of the work being merged in (particularly important for larger merges).
7. If you are not quite ready for the merge to happen, include a `WIP:` at the beginning of the title, which will disable the actual merge until it is removed.
8. Assign it to the project owner. If you don’t do this, the merge request might not get seen.

Why do it this way?

You may wonder why we don’t just commit directly to master as we have in the past.  Here are a few reasons:

• Branch merges can be reverted much more easily than a series of commits.  The record of development is a bit cleaner.
• It allows for a simple way to ‘peer review’ your commits prior to merge to master.  This helps with quality control.
• There are built-in features in GitLab that allow comments/dialog on specific portions of the branch.
• You can actually make (small) changes directly through gitlab and commit them in place on the branch!

Once you start doing this, I think that you will like it much more than the previous mode we operated in.

Who can merge to master?

That depends on the permissions for each user and for each project.  You can create `protected branches` in GitLab that only allow project administrators to modify those branches.  Many of our repositories will be using those for the master branch.