U.S. Geological Survey Manual
U.S. Geological Survey Instructional Memorandum
No: IM OSQI 2016-01
Issuance Date: October 31, 2016
Expiration Date: Retain Until Suspended
Subject: Review and Approval of Software for Release
1. Purpose and Scope.
A. This Instructional Memorandum (IM) establishes the requirements for reviewing, approving, releasing, sharing, and documenting U.S. Geological Survey (USGS) software intended for release (referred to as “software releases” throughout this policy). Software is a set of instructions suitable for processing by a computer in the form of source code or executable code regardless of intended platform (Web server, mobile device, supercomputer, and others). Examples of a software release include computational models, applications for mobile devices, data processing applications, scientific programming scripts and workflows, code libraries, and algorithms. Software can be interpretive or noninterpretive.
B. The IM also provides guidelines toward implementing the 2013 Office of Science Policy and Technology directive on increasing access to the results of scientific research, the 2016 Federal Source Code Policy, and the USGS Fundamental Science Practices. USGS 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 made available publicly at no cost and in the public domain. Not all USGS software is suitable for release to the public, including software developed for use on internal Bureau systems or software that has privacy, confidentiality, licensing, security, or other constraints that would restrict release.
C. This IM applies to all software developed and released by or on behalf of the USGS that meets the criteria for software intended for public release (as described in section 1.B). This IM replaces the part of Survey Manual (SM) chapter SM 500.24 - Policy for Release of Computer Databases and Computer Programs, dated April 9, 1993, that addressed Computer Programs. This IM is interim policy to allow time needed for USGS science activities to fully implement the requirements herein and will be retained until superseded by a permanent SM policy chapter. Additional supporting guidance for the IM will be available on the USGS Fundamental Science Practices (FSP) Web site (https://www.usgs.gov/fsp/). Open discussion on the IM can take place via a USGS Software Best Practices GitHub space, and contributions to this space from USGS software developers, supervisors, approving officials, and others are encouraged.
A. Review and Approval. USGS releases both provisional (preliminary) and approved software. The basic requirements for review and approval of these two types of software are described in subsections 1 and 2 below. All software must include the appropriate disclaimer statement (refer to section 2.B), and all software must include sufficient code documentation (refer to 2.D) to promote usability. All software should include functional tests, which can sometimes be inherent in the software itself, and these practices should be employed where possible to aid review and help ensure veracity of the product.
(1) Provisional or Preliminary Software and Informal Sharing. Software is increasingly a part of sharing scientific ideas and analytical methods during the course of a project and as a regular part of the scientific workflow. Provisional or preliminary software that is pre-released via online code repositories is a common practice for collaboration and sharing with colleagues and peers from other institutions as a way to improve scientific outcomes. This collaborative, informal sharing of software, when it does not involve posting online to a publicly accessible code repository, can be done in accordance with requirements for safeguarding unpublished USGS information prior to release (SM 502.5). Release of in-progress, collaborative or informal sharing of software through a publicly accessible code repository requires Science Center level approval of the methods and practices used but does not require tracking through the Information Product Data System (IPDS). Review of preliminary or informally shared software is at the discretion of Science Center management.
(2) Approved Software. Approved software releases are considered USGS information products (SM 1100.1 and SM 502.4) and must be tracked through the IPDS. Approved software releases must comply with the appropriate approval authority level (section 2.A), according to whether the software release content is a new interpretive, previously published interpretive, or noninterpretive product (refer to SM 205.18). Additional guidance on these content types is available on the page Distinctions Between New Research or Interpretive Information Products and Previously Published or Noninterpretive Information Products. New interpretive software requires a minimum of two software reviews to ensure scientific veracity of the product as well as its functional validity. Previously released interpretive or noninterpretive software requires a minimum of one software review to ensure validity of the code.
B. Disclaimer Statements. All USGS software that is publicly released must be accompanied by either the approved software disclaimer statement or the provisional software disclaimer statement.
C. Software Updates. Much of the software that the USGS produces and releases will have updates that are released over time beyond the initial release. The level of review and approval needed may differ between the software’s initial release and the software update releases and is determined by whether or not the update represents a new interpretive, previously published interpretive, or a noninterpretive addition. Disclaimer statements must also be included when software updates are released to denote whether the update is for provisional or approved software.
D. Software Release Code Documentation (metadata). All USGS 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. 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. Updated software releases must include documentation describing changes in the update. Software developers are encouraged to use current best practices (for example USGS Software Best Practices GitHub) in providing documentation for the specific software technology or distribution platform used so that it is most relevant and accessible for users. Approved software releases must register basic citation information to obtain a Digital Object Identifier (DOI), specifying “software” as the resource type, to aid in proper citation and reference to specific versions.
E. Public Domain. Software releases developed by or on behalf of the USGS are the property of the Federal Government (unless specific stipulations are made in an agreement, contract, or grant award) and when released are to be made available in the public domain and free of copyright. Third-party copyrighted content may be included in USGS software (refer to SM 1100.6), and the copyrighted content must be clearly indicated with the associated copyright/license and attribution information. When an official license declaration is required or appropriate to include, the Creative Commons CC0 license may be used (currently CC0 1.0). Contributions of software components such as specific algorithms to existing software licensed through a third party are encouraged, but those contributions should be annotated as freely available in the public domain when possible. Any USGS compiled executable code should be accompanied by source code, but any compiled third-party software does not require distribution of source code.
F. 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.
G. Code Distribution. Software releases may be distributed via a third party, but the authoritative version of the approved software release and comparable information must be made publicly available through a U.S. Government platform (OMB Memorandum 10-23, Section 3).
H. Accessibility. All USGS software releases should avoid access barriers that prevent individuals with disabilities from using the software (SM 600.6).
I. Information Technology Security. USGS information technology systems security requirements must be followed (SM 600.5). Software developers should pay particular attention to separating configuration details such as security credentials from software 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.
J. Records Management and Preservation. Software releases and associated documentation constitute official records of the USGS and must be managed in accordance with USGS records management requirements (SM 431.1) and appropriate records disposition schedules or as appropriate to meet the National Archives and Records Administration (NARA) retention format requirements for permanent records, to comply with Federal Government Open Data and Open Access initiatives, and to support scientific reproducibility. As technological products subject to potentially rapid obsolescence, USGS software releases must be effectively managed to ensure long-term quality and integrity of scientific content.
3. Responsibilities. All those involved in any phase of the 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 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 software review, approval, and release. The OSQI and CSS collaborate with the ADs, RDs, and Science Center Directors in implementing Bureau-wide solutions that pertain to software used for scientific research. The OSQI is responsible for communicating and maintaining policy documents related to USGS software release.
C. Science Center Directors, Managers, Supervisors. Science Center Directors, managers (project and program), and supervisors consult and work with each other and the authors and developers they supervise as needed during the processes of development, review, approval, and release of software. Science Center Directors collaborate with their mission area ADs and RDs as necessary in determining actions to be taken to ensure that software upholds USGS standards for quality prior to release and that software is released through the appropriate venue.
D. Authors, Developers, and Reviewers. Authors, developers, and reviewers of USGS software are responsible for complying with this policy and other related FSP policy. Authors and developers consult with their Science Center Director and other approving officials during the development, review, and approval of software.
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 noninterpretive and not new interpretive software releases and oversight of provisional software and informal sharing when the sharing mechanism will involve posting to a publicly available Web site. BAOs in the OSQI are responsible for Bureau approval of new interpretive software releases. Approving Officials have latitude in determining what is needed to uphold USGS standards for software quality, including ensuring the necessary reviews are obtained and the method of release is appropriate.
/s/ Randall C. Orndorff October 31, 2016
Randall C. Orndorff Date
Acting Director, Office of Science Quality and Integrity
Return to Instructional Memoranda Page
Return to Survey Manual Home Page