Software Management

Additional Guidance on Review and Approval of Scientific Software

This page contains additional best practices related only to Scientific Software; authors of Scientific Software should refer to all of the content contained on this website in addition to the information below as a guide.

Scientific software is a discrete package of computer code and documentation that contains source code implementing scientific algorithms and/or producing scientific data. A scientific software product may also be integral to or part of another USGS scientific information product or series publication (for example a USGS data release, an Open-File Report or Techniques and Methods series product), or an outside publication such as a journal article (Refer to Software IM).

For support and questions about how to use Git to meet the requirements for Scientific Software, contact GS Help Git (gs_help_git@usgs.gov)

Lifecycle Stages of Scientific Software

Code writing is often an iterative process and your Scientific Software source code will likely fall into all of the categories below at some point in the process. Here are some helpful tips about Git and lifecycle stages of scientific software (Refer to Develop).

Pre-release Development

This source code can exist in folders on local workstations, user account namespace on any Git hosting platform, or in any internal or private USGS GitLab project.

Public

Private

  • USGS OpenSource GitLab Code.usgs.gov personal repositories are ALWAYS private, and cannot be made public
  • Example: https://code.usgs.gov/{user}/{project}.git

Where {user} is your user account name and {project} is the name of the software project repository. These are your own and no restrictions are placed on them.

Preliminary / Provisional Release

This source code can exist in the publicly accessible USGS organization on any Git platform. This code may be initiated as preliminary in a public Git hosting or may be migrated from a private pre-release development software project. Code migrated from a pre-release development software project must receive an administrative security review and Center Director approval prior to migration (Refer to Review).

Public

Official Software Release

The official (Authoritative) release of this source code must exist on USGS OpenSource GitLab. These projects are marked by Git repository tags indicating scientific software repositories that have gone through the required reviews and received approval for release as an official USGS Software Release product (Refer to Review).

Public

Review with Git

Equally important to performing software code and subject-matter expert reviews (Refer to Review) is documenting the review and reconciliation process in your Git repository. Documenting the review process in Git always follows a similar process, however this process varies slightly depending on the current project state and software stage.

Pre-Release → Provisional Release

This review occurs prior to migrating pre-release software into a public repository on the USGS OpenSource GitLab.

  • Put the software in a version control repository accessible by the intended reviewer.

  • Create an issue in the project named Software Release Reviews requesting a review of  the software.

    • Include a link to where the software is accessible.

    • Add a label to the issue indicating the type of review being requested.

  • Wait for the reviewer to approve the changes.

    • This may involve iteratively fixing issues the reviewer identifies.

Updating Existing Provisional Release

Every change to a public repository in Git must receive at least an administrative security review (See Review). This can be done using pull requests. The following steps assume you are following the integration manager workflow.

  • Submit a pull request from your user fork of the USGS repository back to the primary USGS repository

    • Assign (or request) a reviewer to the pull request

  • Wait for the reviewer to approve the changes

    • This may involve iteratively fixing issues the reviewer identifies

  • Merge (or better, have the reviewer merge) the changes into the USGS repository

Pre-Release or Preliminary Release → Official Release

Approved software requires proper tagging. Reference the following steps.

  • Create a release candidate reconciliation branch

    • Using the Semantic Versioning specification this may be something like: git checkout -b vMAJOR.MINOR.PATCH-rc1-reconciliation

  • Create a release candidate tag

    • Using the Semantic Versioning specification this may be something like: git tag -am 'vMAJOR.MINOR.PATCH-rc1' vMAJOR.MINOR.PATCH-rc1

  • Create an issue on the project issues page requesting the appropriate level of review be performed

    • Provide a link to the release candidate tag

  • Wait for reviewer(s) to approve the changes

This may involve iteratively fixing issues the reviewer identifies  by making commits back to the release candidate branch

Approval Requirements of Scientific Software

In addition to the Metadata, Licenses, and Disclaimer requirements (Refer to Distribute), Scientific Software is also required to have the following:

IPDS Record

To obtain approval, Scientific Software must be approved at the Science Center level using the USGS Information Product Data System (IPDS). For product type select “Software Release”.

  • Not applicable to Provisional Software

Center Director Approval

All Scientific Software needs formal Center Director approval documented in IPDS. Peer reviews must be completed in IPDS prior to submission to Center Directors. Provisional or preliminary software is subject to revision and often released prior to formal approval as a USGS scientific information product in order to support collaborative software development with colleagues and partners from outside entities, however it must still be approved by a Science Center Director before any type of public release occurs.

Digital Object Identifiers

Software releases from the USGS must be assigned a digital object identifier (DOI) in the 10.5066 prefix once approved for release. DOIs must be obtained through the USGS Digital Object Identifier (DOI) Creation Tool. While many fields in the DOI Creation Tool reference data only, the context is interchangeable with software. Refer to the guides below.

  • Not applicable to Provisional Software

Create a new DOI record. Complete the following fields:

  1. Title - Title of the Scientific Software product for release.

  2. USGS Data Source - The USGS science center or program responsible for managing the Scientific Software.

  3. Release through ScienceBase - Select “No”. The authoritative (reference) version for all Scientific Software must be maintained in a repository on the USGS OpenSource GitLab.

Required Information Screen. Complete the following fields:

  • Publication Year - Calendar year that USGS released the Scientific Software product.

  • Creator(s) / Author(s) - All authors/ code contributors to the Scientific Software product.

  • Location URL - Web address for the source code repository of the Scientific Software product on the USGS OpenSource GitLab.

  • IPDS Number(s) - Scientific Software products must be tracked in IPDS, provide the IPDS number.

  • Resource Type - Software release products must be assigned a meaningful resource type in the DOI metadata such as software, model, workflow, or another appropriate term. Refer to image below.

 

Disclaimers

Add the approved software disclaimer text from the USGS FSP website.

Distribute Software with Git

Follow the steps below to indicate that your code has been approved or is provisional.

Provisional

  • Create a release tag in the repository

  • Follow the steps for creating releases on GitHub

  • You must mark the release as pre-release

Approved

  • Merge the release candidate reconciliation branch back into the master branch

  • Update the release candidate reconciliation branch DISCLAIMER.md file...

  • Create a release tag using the reconciled release candidate branch as a basis and follow the steps for creating releases on GitHub

  • You do not need to mark the release as pre-release