Forking Workflow

If you’re planning on a software release, then you should use a forking workflow to manage your software reviews and development. This page provides an overview of this workflow, and the following pages provide step-by-step instructions for implementing this workflow in Gitlab.

Forks

A forking workflow uses two mirrored repositories to manage your code. One repository (the official or upstream repository) is located at code.usgs.gov/ghsc/lhp. This is the official source for the code. Critically, the upstream repository should ONLY contain code that has been reviewed.

The second repository, your personal repository, is where you will develop your code. This will be located in your user namespace, something like code.usgs.gov/ghsc/users/your-user-name. This personal repository is known as a fork.

You can have multiple forks of a project (if you are working with collaborators), but there will only ever be one upstream.

Merge Requests

You should use merge requests to track reviews and move code to the upstream repository. Conceptually, a merge request is a point when you add code from a fork to the upstream repository. The code in a merge request must be reviewed before it can be added to the upstream, and this is how you ensure that the upstream only contains reviewed code.

Merge requests are archived when you complete them, and this maintains a permanent record of all your code’s reviews. This archive will be useful later when you are ready to release the code.

If your personal repository has multiple branches, you can merge code from any branch to the upstream. However, you should almost always merge code into the main branch of the upstream.

Development Branches

In practice, it’s usually a good idea to leave the main branch of your fork alone. Instead, do your development on other branches, and merge those into the upstream. Then, update the main branch of your fork to match the upstream.

After updating, you can make new development branches from the updated main branch of your fork.

This practice will help you avoid merge conflicts - errors that can arise when the same line receives different changes in different branches. By maintaining the main branch as a mirror of the upstream, you always have a clean main branch to use as a template for new branches.

Review Branches

When writing code, it’s common to make many commits as you edit and save your work. This is a good practice, and is recommended for all projects. When using this workflow, it’s common for a merge request to contain tens or even hundreds of small commits. However, this can hinder the code review process, as security reviews are required to examine every new commit in a merge request, rather than just the final version of the code. Fortunately, there’s an easy solution.

If your development branch contains more than a few commits, then you should use a review branch to consolidate your updates into a single commit for the reviewer. You can make a review branch by first creating a new branch from main. Then, copy the final code from your development branch into the review branch with a single commit. Finally, create the merge request using the review branch, rather than the development branch. This way, the merge request contains the finalized code, but only includes a single commit for the reviewer. This significantly reduces the work for your reviewer and can greatly speed up the review process.