IM OSQI 2019-01, Review and Approval of Scientific Software for Release
Issuance Date: 10/02/19
Expiration Date: Retain Until Cancelled
Instruction: This Survey Manual (SM) Instructional Memorandum (IM) replaces IM OSQI 2016-01, Review and Approval of Software for Release, dated October 31, 2016.
1. Purpose and Scope.
A. This policy establishes the requirements for documenting, reviewing, approving, and releasing U.S. Geological Survey (USGS) scientific software only to assure integrity and high quality of scientific information products and science activities.
B. This IM applies to all scientific software developed and released by or on behalf of the Bureau that meets the USGS criteria for software intended for public release as described in sections 6 and 7.
2. Background.
A. This IM provides guidelines toward implementing the 2016 Federal Source Code Policy and complying with USGS Fundamental Science Practices (FSP). USGS scientific software intended for public release includes any custom-developed code yielding scientific results, thereby facilitating a clear scientific workflow of analysis, scientific integrity, and reproducibility. USGS software releases are considered to be public domain assets and are generally made available free of restrictions. Some USGS software, however, such as software developed for use on Bureau systems or software that has privacy, confidentiality, licensing, security, or other constraints that would restrict release, is not suitable for release to the public.
B. USGS releases both provisional or preliminary and approved software. Software development, review, and approval practices provide the opportunity for different types of functional tests, which can sometimes be inherent in the software itself, and these tests should be performed, where possible, to aid review and help ensure the veracity of the software product. Approved software releases are considered USGS scientific information products as defined in SM 502.1, Fundamental Science Practices: Foundation Policy. The review and approval process for approved scientific software releases (refer to SM 502.4, Fundamental Science Practices: Review, Approval, and Release of Information Products) must be tracked through the internal USGS Information Product Data System (IPDS).
3. References
A. Federal Source Code Policy: Achieving Efficiency, Transparency, and Innovation through Reusable and Open Source Software
B. Improving Implementation of the Information Quality Act (Office of Management and Budget (OMB) memorandum M-19-15, April 24, 2019)
C. SM 600.5, Information Technology Systems Security - General Requirements
D. SM 502.1, Fundamental Science Practices (FSP) Foundation Policy
E. SM 502.4, FSP: Review, Approval, and Release of Information Products:
F. SM 502.5, FSP: Safeguarding Unpublished U.S. Geological Survey Data, Information, and Associated Scientific Materials
G. SM 1100.6, Use of Copyrighted Material in USGS Information Products
H. SM 600.6, Implementation and Administration of Section 508 of the Rehabilitation Act
I. SM 431.1, Records Management Roles and Responsibilities
4. Definitions.
A. Source Code. Computer commands written in a computer programming language that is meant to be read by people. As such, source code is a higher-level representation of computer commands and, therefore, must be assembled or compiled before a computer can execute it as a program.
B. Software. Refers to (1) computer programs that comprise a series of instructions, rules, routines, or statements, regardless of the media in which recorded, that allow or cause a computer to perform a specific operation or series of operations; and (2) recorded information comprising source code listings, design details, algorithms, processes, flow charts, formulas, and related material that would enable the computer program to be produced, created, or compiled. Software does not include computer databases or computer software documentation. Software is considered noninterpretive information.
C. Scientific Software. Software containing source code implementing scientific algorithms or producing scientific data. It may include any custom developed code yielding scientific results, thereby facilitating a clear scientific workflow of analysis, scientific integrity, and reproducibility.
D. Documentation. Documentation can range from a readme file and embedded comments for a simple script to a separate publication for a new complex scientific model referenced in the embedded code documentation.
E. Provisional or Preliminary Software. Scientific software that has yet to be approved as a USGS information product. Throughout this document, “provisional” is used to describe provisional or preliminary software. Provisional scientific software is subject to change.
F. Approved Software. Scientific software that has been approved by the Bureau for release.
G. Software Release. Approved scientific software that has been released as a USGS information product or provisional software that has been made available for limited accessibility and sharing in collaborative arrangements.
5. Policy.
A. Scientific software intended for approval and release as a USGS scientific information product (refer to SM 502.1) must comply with the appropriate USGS FSP requirements including those described in this IM, SM 502.4, and other applicable FSP policy. The review and approval process for these scientific software releases must be tracked through the IPDS.
B. Review. Scientific software is subject to two types of review. A software code review of the scientific software package (including code, documentation, tests, licenses, metadata), which requires some software expertise, and a domain review of the entire package relative to the science or application, requiring domain expertise. All scientific software, regardless of whether it is intended for release as provisional software or as an approved information product, should include a minimal software code review to ensure that personal, private, or otherwise sensitive information will not be made publicly available. In some cases, a single reviewer may have the code expertise and the domain/application expertise to perform both reviews. A single reviewer may also have the expertise to perform a review for the software release as well as any other related reviews (e.g., data review). Software developers should provide reviewer(s) with sufficient documentation so that the reviewers are able to verify that the review requirements are met. Additional guidance on the software code and domain reviews is as follows:
(1) Code Review: A technical expert is expected to perform a review of the code to verify that the software follows up-to-date best-practices for software development including assurance that personal, private, or otherwise sensitive information will not be made publicly available.
(2) Domain Review: A domain/application expert is expected to verify that the output of the software is scientifically sound/accurate.
C. Approval. Science Center Directors have delegated authority to approve USGS scientific software and, at their discretion, may request approval by a Bureau Approving Official (BAO) in the Office of Science Quality and Integrity (OSQI). Approved software must have undergone the review described in section 5.B. Until approved, scientific software is provisional and subject to revision.
D. Disclaimer. Scientific software releases must be accompanied by the appropriate disclaimer statement. Where applicable, other disclaimer statements such as those regarding non-endorsement of commercial products or use of copyrighted material should be included.
E. Documentation. Scientific software releases must be accompanied by code documentation to enable others to use and understand how the software is intended to work, including reference configuration details and data where applicable. The level of code documentation must be appropriate for the scope and purpose of the software being released. Versioned updates to approved software releases must include documentation describing the changes associated with the update.
F. Persistency. Approved scientific software releases must have basic citation information registered to receive a Digital Object Identifier (DOI) from the USGS registration agent, specifying “software” as the resource type, to aid in proper citation and reference to specific versions. These releases also must be accompanied by a recommended citation.
G. Availability. Approved scientific software releases are made available at no cost to the public and are managed through a “.gov” website (i.e., code.usgs.gov) ensuring their long-term preservation, discoverability, accessibility, and usability. The releases may be distributed via a third party, but the authoritative version of the approved scientific software release and comparable information must be made publicly available (refer to the OMB Memorandum 10-23, Section 3).
H. Records Management and Preservation. Approved scientific software releases and associated documentation constitute Federal records of the USGS and must be managed in accordance with applicable USGS records management requirements (refer to SM 431.1). If deemed permanent records, they must meet the National Archives and Records Administration (NARA) retention format requirements for permanent records; comply with Federal Government Open Data and Open Access initiatives; and support scientific reproducibility. As a technological product subject to potentially rapid obsolescence, USGS scientific software releases must be effectively managed to ensure long-term quality and integrity of scientific content.
I. Public Domain. Scientific software releases developed by a USGS employee in their official capacity or on behalf of the USGS are considered public domain unless specific stipulations are made in an agreement, contract, or grant award. If copyrighted content is included in USGS software (refer to SM 1100.6), this content must be used with written permission and be clearly indicated with the associated copyright/license and attribution information. USGS contributions of software components such as specific algorithms to existing software licensed through a third party are encouraged; however, when possible, those contributions should be annotated as freely available in the public domain. Any USGS compiled executable code should be accompanied by source code. The USGS encourages, but does not require distribution of source code for third-party compiled software. Requirements for proprietary software prepared by the USGS or received from other sources described in SM 502.5 must be followed.
J. License Compliance. USGS software developers must adhere to all license requirements, including commercial and open-source license restrictions. For example, many license agreements require submitting addendums and code changes to the originating project before distribution is permitted. Consult a Department of the Interior Solicitor’s Office representative when considering including or relying upon third-party materials in USGS scientific software.
K. Accessibility. Scientific software releases should avoid access barriers that prevent individuals with disabilities from using the software (USGS Accessibility).
L. Information Technology Security. Security requirements for USGS information technology systems must be followed (refer to SM 600.5). Software developers should pay particular attention to separating configuration details such as security credentials from source code to avoid unintentional breach of security restrictions, introduction of denial of service vectors through data access routines, and security risks introduced through the use of third-party libraries.
M. Frequently asked questions and other guidance and procedures that support this scientific software release IM policy are available from the public FSP website and the USGS Software Management website.
6. Provisional Scientific Software Release. Scientific software is increasingly a part of sharing ideas and analytical methods during the course of a USGS project and as a regular part of the scientific workflow. Developing provisional software openly via online code repositories is a common practice for collaboration and sharing with colleagues and peers from other institutions, as these efforts can be a way to improve scientific outcomes. Release of in-progress scientific software for collaborative or informal sharing through a publicly accessible code repository requires Science Center level approval of the methods and practices used and assurance that personal, private, or otherwise sensitive information is not shared, but does not require tracking through the IPDS or approval as an information product. Collaborative and informal sharing of software not involving posting online to a publicly accessible code repository can be done in accordance with the requirements for safeguarding unpublished USGS information prior to release (refer to SM 502.5). Provisional scientific software that is released must include the appropriate disclaimer statement (refer to section 5.D.), as well as sufficient code documentation to promote usability as described in section 5.E.
7. Approved Scientific Software Release. Scientific software intended for approval and release as a USGS information product (refer to SM 502.1) is subject to USGS review, approval, and release requirements described in this policy and, as applicable, in SM 502.4.
8. Requirements for Versioned Updates to Approved Scientific Software Releases. Scientific software releases are commonly updated over time. The level of review and approval needed for updated versions may differ from that of the initial release and is at the discretion of the Science Center Director or their designee. Disclaimer statements must also be included with the updated version to denote whether the update is provisional or an approved software version.
9. Responsibilities. All those involved in any phase of the scientific software development, review, approval, and release process are responsible for complying with this policy. In addition, specific responsibilities include:
A. Associate Directors and Regional Directors. Associate Directors (ADs) and Regional Directors (RDs) coordinate with Science Center Directors to ensure appropriate stewardship of the software developed in their respective mission and regional areas.
B. Office of Science Quality and Integrity and Core Science Systems. The OSQI and Core Science Systems (CSS) are responsible for jointly developing USGS scientific software release policy and collaborating on the development of related guidance and procedures. The OSQI and CSS coordinate with the ADs, RDs, and other USGS mission area and office staff to provide advice, procedures, and guidance regarding processes for scientific software review, approval, and release. The OSQI and CSS collaborate with the ADs, RDs, and Science Center Directors in implementing and communicating Bureau-wide solutions that pertain to scientific software used for scientific research. The OSQI is responsible for maintaining this scientific software policy.
C. Science Center Directors, Managers, Supervisors. Science Center Directors, project and program managers, and supervisors consult and work with one another and the authors and developers they supervise, throughout the processes of development, review, approval, and release of scientific software. Science Center Directors collaborate with ADs and RDs to determine necessary actions for ensuring that scientific software upholds USGS standards for quality prior to release and that scientific software is released through the appropriate venue.
D. Authors, Developers, and Reviewers. Authors, developers, and reviewers of USGS scientific software are responsible for complying with this policy and other related FSP policy. Authors and developers consult with their Science Center Director and approving officials during the development, review, and approval of scientific software. Authors ensure the methods used to create the software, if derived through an interpretive process, are described fully in an associated peer-reviewed information product.
E. Approving Officials. Approving officials include Science Center Directors (or their designees) and BAOs in the OSQI. Science Center Directors are responsible for approval of scientific software releases, including provisional software. Science Center Directors may request the scientific software approval to be elevated to BAOs. Approving Officials have latitude in determining what is needed to uphold USGS standards for scientific software quality, including ensuring the necessary reviews are obtained and the release method is appropriate.
F. Records Officer. The Records Officer in the USGS Office of Enterprise Information ensures bureauwide policies, standards, and procedures, including records schedules are in place to provide guidance on creating accurate and complete records with regard to scientific software in accordance with applicable USGS and NARA records management requirements.
/s/ Katherine M. McCulloch 10/02/2019
__________________________________________ _______________
Katherine M. McCulloch Date
Associate Director for Administration