Skip to content

Review of `USGS Git and Software Release Course`

Review of USGS Git and Software Release Course

Background information about the USGS software review process is here.

Project Overview

This repository (usgs-git-and-software-release-course) contains markdown files that are used to render the website for the USGS Git and Software Release Course. The repository structure is outlined below.

  • .gitlab/issue_templates
    • Directory containing example templates for software reviews
  • episodes
    • Directory where markdown files and images for the webpages are stored
  • instructors
  • learners
    • Contains markdown files for the learners such as how to start a discussion, the glossary, and setup instructions
  • learner-profiles
    • This contains the learner-profiles.md file, which is required to render the site but is not leveraged by the course
  • site
    • This contains the README.md file, which is required to render the site
  • The remaining files at the top level of the repository are administrative files for the project

Review Instructions

Please use the 1.0.0 branch starting at commit hash 588cad2e2facb0322526f3a67d6bd47252fb6277 for your review: Link. Comments can be added to this issue with links to the specific line in the code. Please see the Software Review for Reviewers episode for a detailed description of how to add comments to a review issue. Since we will have multiple reviewers, please indicate the episodes that you reviewed in a comment.

Please review the content of the markdown files and ensure that the information included is accurate. A security review has already been completed for each commit prior to the content being merged, so a full security review is not required as part of this review.

Review Checklist

Please check off boxes as you complete each check. If any issues are found for a given check, describe in comments below

Conflict of interest (COI)

  • I, Bojan Milinic, confirm that I have no COIs with reviewing this work, meaning that there is no relationship with the product or the product's authors or affiliated institutions that could influence or be perceived to influence the outcome of the review (if you are unsure whether you have a conflict, please speak to your supervisor before starting your review).

  • I, Brandon Serna, confirm that I have no COIs with reviewing this work, meaning that there is no relationship with the product or the product's authors or affiliated institutions that could influence or be perceived to influence the outcome of the review (if you are unsure whether you have a conflict, please speak to your supervisor before starting your review).

Adherence to Fundamental Science Practices

General checks

  • Repository: Check if the source code for this software is available
  • License: Check that the repository contains a plain-text LICENSE file
  • Disclaimer: Check that the repository has the USGS-required provisional Disclaimer
  • Contribution and authorship: Check that the submitting author made major contributions to the software
  • Contribution and authorship: Check that the full list of software authors seems appropriate and complete
  • Metadata: Check that the repository has a code.json file

Documentation

  • A statement of need or purpose: Check that the authors clearly state the scientific purpose or what problems the software is designed to solve
  • Community guidelines: Check that there are clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support. This information could be found in the README, CONTRIBUTING, or DESCRIPTION sections of the documentation.
  • References: When present, check that references in the text use the proper citation syntax, (for example, by using pandoc)

Functionality

  • Automated tests: Confirm that site is rendering without errors by viewing the Jobs page
  • Coding standards: Confirm that coding standards are appropriate
  • Accuracy: Confirm that the Git commands presented are accurate
  • Accuracy: Confirm that the policy requirements presented align with published policy

Review Comments

  • Add any review comments below as comments/threads.

Acknowledgements

This checklist combines elements of the rOpenSci review guidelines and the Journal of Open Source Science (JOSS) review checklist.

Edited by Madison L Langseth