Software Review for Authors

Last updated on 2025-05-22 | Edit this page

Estimated time: 30 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.
  • Update the DISCLAIMER.md to the approved language.
  • Develop a GitLab issue to facilitate the software review.
  • Reconcile reviewer comments by updating and rebasing code.

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 a release candidate branch

BASH 

git switch -c 1.0.0

Push the release candidate branch to the remote

BASH 

git push -u origin 1.0.0

Disclaimer

Once you have created the release candidate branch, you should update the DISCLAIMER.md from provisional to approved in the release candidate branch only. In the main branch, this file can continue to reflect the provisional wording. Language for approved software can be found in section 5 of the FSP Guidance on Disclaimer Statements Allowed in USGS Science Information Products

Please note that the release candidate branch should not be merged back in the main branch at any point. During the review process and up until publication, changes can be promoted from the main branch into the release candidate branch via a rebase (described below).

GitLab Issue 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.

Create a GitLab Review Issue

The screenshot below will look different if someone has already created an issue before. It will likely be worth commenting on this so people are not confused.

Screenshot of the Issues menu item and Issues page in GitLab

Example review issue templates are available: - Traditional Software Product Review Template - Scientific Software Product Review Template (e.g., code repository used in the publication of a report or manuscript that addresses a research question).

Include the following information in your issue:

  • a brief description of the project and the repository structure
  • special instructions for the reviewer
  • a checklist of elements to review

The checklist provided in the review issue template linked above may have checks that are not applicable to your project. Help your reviewer by only including checks that are relevant to your project. The next episode will outline the review process from the perspective of the reviewer.

Create a Review Issue

  1. Create an issue in your repository to help your reviewer(s) structure their review. You may choose to setup issue templates in your repository and include a review template as demonstrated within this project and documented on the GitLab Description Templates page. Alternatively, you can just copy the markdown from the example template linked above and paste it into a new issue.

  2. Think about a project that you have worked on in the past. With a partner or small group, discuss the following questions:

    1. Which parts of the review template would 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. Create a separate branch or multiple branches to make any necessary code changes based on the reviewer’s feedback.

Merge the changes into your main branch and then rebase into your release candidate branch. Rebasing is the process of adding a series of commits to a new base commit, which provides a cleaner git commit history than merging (click here to learn more about when to rebase instead of merge). It will look like this:

BASH 

git switch main
git pull --f-only origin main
git switch 1.0.0
git rebase main
git push origin 1.0.0

You can reference the commit hash for each change that you made in response to the 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 and your release candidate branch is up to date, close the review issue and state the commit hash on which it ended.

Print the final review issue to PDF and upload the PDF as the review and reconciliation documentation for the USGS Information Product Data System.

Callout

You may want to include a link to the original issue 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
  • Once you have a release candidate branch, update the DISCLAIMER.md
  • A GitLab review issue provides structure for reviewers and makes it easier for them to conduct a review
  • A PDF of the final review issue can serve as the review and reconciliation documentation in the USGS Information Product Data System