Software Review for Authors

Last updated on 2025-11-24 | Edit this page

Estimated time: 45 minutes

Overview

Questions

  • How do I prepare my code for a software review?
  • What information do I need to provide to my reviewer(s)?
  • How should I reconcile reviewer comments?
  • How can I document the review to meet Fundamental Science Practices requirements?

Objectives

  • Create a release candidate branch in preparation for a software review.
  • Develop a GitLab merge request to facilitate the software review.
  • Reconcile reviewer comments by updating main branch and replying to comments in merge request.

This lesson will use breakout rooms to discuss lesson material. Inform learners so they may move to a more quiet or isolated area and be ready to speak during the discussion.

Software Review Overview

After you have completed your code development, added the required files to your repository, and are ready to publish your software product, you will need to request a review. As noted in the Policy episode, official USGS software information products must be reviewed and approved before they can be released. The review must include an administrative, code, and domain review. We will go into more depth on how to conduct these reviews in the next episode Software Review for Reviewers.

Release Candidate Branch

A release candidate branch should be created to help facilitate the review process. The release candidate branch should have the same name as the eventual release tag. For example, if you are preparing to release version 1.0.0 of your software product, the release candidate branch will be 1.0.0.

Open Git Bash (Windows) or Terminal (MacOS) and navigate to your local repository. Make sure you are in your main branch and it is up to date. We will use --ff-only to reject the pull request if there are any local commits that are not already on the remote.

BASH 

git switch main
git pull --ff-only origin main

Create an empty release candidate branch. We want the branch to be empty so that we can create a merge request to facilitate reviewer comments. The following command creates a new branch named 1.0.0 without any commit history. The --orphan flag is crucial here as it ensures the branch starts with no commits, making it an “orphan” branch. This is useful for creating a completely clean slate for your release candidate.

BASH 

git switch --orphan 1.0.0

If you have directories in your repository, Git may give you the following prompt:

OUTPUT 

Deletion of directory 'NAME_OF_DIR' failed. Should I try again? (y/n)

Type n for each directory to allow the continued creation of the orphan branch.

Normally, Git does not allow you to commit an empty branch (a branch with no files or changes). The --allow-empty flag allows you to create a commit even though there are no changes to commit. The -m 'Create Release Candidate Branch' part adds a commit message to this empty commit, which helps in identifying the purpose of this commit.

BASH 

git commit --allow-empty -m 'Create Release Candidate Branch'

Push the release candidate branch to the remote

BASH 

git push -u origin 1.0.0

GitLab Merge Request for Review

There is not a single prescribed way to perform a software review. In this lesson, we offer an example for how you can help a reviewer structure and document their review within a merge request.

We need to create a merge request to merge main into 1.0.0. Unlike in the Branching and Merging episode, do NOT click on the “Create merge request” button in the GitLab banner message. That button will create a merge request from 1.0.0 to main.

  1. Navigate to Merge requests in the GitLab side navigation and select New merge request: Screenshot of `Merge requests` in the side navigation and the `New merge request` button

  2. Select main as the source branch and 1.0.0 as the target branch: Screenshot of the New merge request source branch and target branch selection

  3. Give your merge request a meaningful title (e.g., Review of vampires-and-werewolves)

  4. Add a review template to the Description field. An example review template is available here. Feel free to add more checks or simplify the checks depending on your use case (example of simplified review template). Help your reviewer by only including checks that are relevant to your project. To copy from the template linked above, select Display source and then click the Copy file contents button.

Discussion

Update Your Merge Request

Think about a project that you have worked on in the past. Update your merge request description to help a hypothetical reviewer structure their review for that project. Make sure to include the following information:

  1. a brief description of the project and the repository structure
  2. special instructions for the reviewer
  3. a checklist of elements to review

With a partner or small group, discuss the following questions:

  1. Which parts of the review template did you keep for the project?
  2. What elements or checks would you add?
  3. Are there any parts of the template that you do not understand?

Reconcile Review

Once the reviewer(s) completes the review, you will need to reconcile the review. Make updates to your code to reconcile reviewer feedback. Refer to the Branching and Merging episode for a refresher.

When reconciling a review, you may be required to remove private and/or sensitive information that was mistakenly added to the repository history. This can be a challenge in a Git repository. First, you must rewrite the repository history; consider using a tool such as git-filter-repo. Once the local repository is cleaned up and the changes have been pushed to the remote location in GitLab (this will typically require a --force push), you should also run housekeeping on the remote repository.

To run housekeeping, navigate to your project on GitLab and go to the Settings -> General page and expand the Advanced section. Here you should Run housekeeping and Prune unreachable objects.

Screenshot of `Housekeeping` in the project advanced general settings.

Merge the changes into your main branch. These changes will automatically get included in your merge request.

Once you push the commit to GitLab, you can reference the commit hash for each change that you made in response to a reviewer’s comments and then resolve the comment thread.

Callout

Note that the referenced commit hash must be pushed to GitLab before you submit the comment, otherwise GitLab will not link the hash and it will look like gibberish text in the comment.

Once all changes are made, expand any collapsed threads on the merge request and print the final merge request documentation to PDF. Upload the PDF as the review and reconciliation documentation for the USGS Information Product Data System.

Depending on your Science Center’s review and approval process, you may merge main into your release candidate branch prior to receiving final approval from your Science Center. Alternatively, your Science Center approver may want to Approve the merge request in GitLab.

Callout

You may want to include a link to the original merge request in the review artifact that is loaded into the USGS Information Product Data System. Please remember that the workflow presented in this and the next episode is just one of many ways to complete a software review and reconciliation. Please check with your Science Center leadership to see if they have different requirements.

Key Points
  • A release candidate branch is named with the version number for the anticipated software information product release
  • A GitLab merge request provides structure for reviewers and makes it easier for them to conduct a review
  • A PDF of the final merge request documentation can serve as the review and reconciliation documentation in the USGS Information Product Data System