Provisional release
-
Develop source code using a repository in one of the accepted USGS Git hosting options. -
Repository must exist within a group/team namespace within the appropriate hierarchy (e.g., https://code.usgs.gov/WIM/repo-name). It may not exist in your personal namespace. -
Versioned updates of software must include description of the changes associated with the update. -
Include a README.md file (instructions). -
Include a code.json file (instructions). -
Include a LICENSE.md file (instructions). -
Include a DISCLAIMER.md file with content for a provisional release (instructions). -
If the repository contains any test datasets, ensure that they are appropriately documented. -
Determine the name of your eventual Release Candidate branch. It should be named using Semantic Versioning principles (e.g., 1.1.1
). -
Update these fields in the code.json of the main
ormaster
branch:-
version
: Should match name of the eventual Release Candidate branch with no preceding letters (e.g., "1.1.1") -
status
: Change the value, if it should be different from themain
ormaster
branch. -
permissions.licenses.URL
: Link to the LICENSE.md file stored in the project on the eventual Release Candidate branch. Must use the raw variant of the file (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/raw/1.1.1/LICENSE.md"). -
downloadURL
: Link to download a ZIP archive of the project source code on the eventual Release Candidate branch (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/archive/1.1.1/ChannelWeighting-1.1.1.zip"). -
disclaimerURL
: Link to the DISCLAIMER.md file stored in the project on the eventual Release Candidate branch. Must use the raw variant of the file (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/raw/1.1.1/DISCLAIMER.md"). -
metadataLastUpdated
: Change to current date.
-
-
From your main
ormaster
branch, create the Release Candidate branch. -
In the Release Candidate branch, update the metadataLastUpdated
field in the code.json to the current date. -
In the Release Candidate branch, update the DISCLAIMER.md file with contents for an official release. -
Create an Information Product Data System (IPDS) record (instructions). -
Assign a Digital Object Identifier (DOI) using the USGS Digital Object Identifier (DOI) Creation Tool (instructions). -
In the Release Candidate branch, update these items in the README.md: -
Update the citation to use the DOI URL. -
Add the IPDS number.
-
-
In the repository settings, ensure the repository is visible to all peer reviewers, the supervisor, and the Bureau Approving Official (BAO). -
Upload original manuscript (zipped version of repository) to IPDS record. -
Complete the "Request Peer Review" routing step in IPDS. -
The supervisor will complete the "Accept for Peer Review" routing step in IPDS. -
Complete an Administrative Security Review (instructions). -
Complete a Code Review (instructions). -
Complete a Domain Review (instructions). -
Address all comments from peer review. -
Upload peer review documentation, peer review reconciliation documentation, and an updated manuscript to IPDS record. -
Complete the "Reconcile Peer Review" routing step in IPDS. -
The supervisor will provide a review. -
Address comments from supervisory review. -
Upload supervisory review documentation, supervisory review reconciliation documentation, and an updated manuscript to IPDS record. When the supervisor is satisfied, they will complete the "Supervisory Review" routing step in IPDS. -
The BAO will provide a review. -
Address comments from BOA review. -
Upload BAO review documentation, BAO review reconciliation documentation and an updated manuscript to IPDS record. When the BAO is satisfied, they will complete the "Bureau Approval" step. -
Visit the Software Management repository and follow the steps to initiate a request for an official release. Once your release has been approved, the repository becomes public. -
Create a tag based on the Release Candidate branch. The name of the tag should be the same as the Release Candidate branch name. -
Publish the DOI in the USGS Digital Object Identifier (DOI) Creation Tool by clicking the "Publish Approved Release to DataCite" button. -
Review all tabs of the IPDS record and ensure all information is complete and accurate. -
Complete the "Dissemination" routing step in IPDS. -
(Optional) Submit publication to the Midcontinent Region Highlights. Form to submit highlights is located here.
Recommendations
-
Repository URL should be all lower-case with words separated by hyphens. -
Create an issue with checklist in your repository to facilitate the publication process. For record-keeping, attach all the documents that are uploaded to IPDS to this issue. -
Write your code such that unit tests can be performed to provide technical reviewers and yourself with a thorough and granular method to review the functionality of the code at any time. See USGS Testing and Automation page. -
Do not include content about disclaimers or licenses in the README.md. Instead, link to the DISCLAIMER.md or LICENSE.md in the README.md. -
Include and use a CHANGELOG.md file at the project root. -
Include a CONTRIBUTING.md file at the project root.
File Information
README.md
A README.md file should be located at the top level of the project. Both casing and file extension are important. It should be in markdown format to ensure it renders properly.
Requirements:
-
Title -
Description of software -
Installation instructions -
Instructions on how to use the software -
Citation: e.g., Medenblik, A.S., Siefken, S.A., Wavra, H.N., and Stephenson, A.J., 2022, StreamStats Channel Weighting Services, U.S. Geological Survey Software Release, https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting.
for the main/master branch orMedenblik, A.S., Siefken, S.A., Wavra, H.N., and Stephenson, A.J., 2022, StreamStats Channel Weighting Services, U.S. Geological Survey Software Release, https://doi.org/10.5066/P9D7MEB1.
for the Release Candidate branch -
IPDS number (for the Release Candidate branch only) -
Citations of relevant publications, data releases, or interpretive or new methods used in the software
Recommendations:
-
Links to additional detailed information such as DISCLAIMER.md, LICENSE.md, documentation, user guide, related manuscript(s), etc. -
If you plan to have multiple versions of the software and you want to make it clear to users that other versions are available, include a link from the top of your readme to the Releases page in GitLab. For example: "A newer version of this software may be available. See https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/releases to view all releases."
code.json
Project metadata are stored maintained in a code.json file located at the top level of the project. This file is in JSON format. Its top-level element should be the releases array as defined in the code.json schema. An example code.json template file is provided to help get you started. Additional information about individual fields:
-
name
: Should be a short, human-readable name for the project. This should match the value provided when creating the project in GitLab/GitHub. -
organization
: Must always be "U.S. Geological Survey". Casing and punctuation are important. -
description
: This may be a longer description of the project. It should be no more than 1-2 sentences. Verbose descriptions may exist in the README.md file. -
version
: This should be a semantic version number for the release (e.g., "1.0.0"). This should not include a leading v (i.e., "v1.0.0") or other identifier. After release, a Git tag should be created for the indicated release. -
status
: Must be one of these values: "Ideation", "Development", "Alpha", "Beta", "Release Candidate", "Production", "Archival". -
permissions.license.name
: If using the default template provided, this should be "Public Domain, CC0-1.0". Otherwise, it should be the name of the selected license. -
permissions.license.URL
: Link to the LICENSE.md file stored in the project. Must use the raw variant of the file (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/raw/master/LICENSE.md" for the main/master branch or "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/raw/1.1.1/LICENSE.md" for the Release Candidate branch). -
homepageURL
: Link to the publicly accessible project homepage. It may be a link to the project on GitLab/GitHub or a project home page elsewhere on the usgs.gov website. -
downloadURL
: Link to download a ZIP archive of the project source code (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/archive/master/ChannelWeighting-master.zip" for the main/master branch or "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/archive/1.1.1/ChannelWeighting-1.1.1.zip" for the Release Candidate branch). -
disclaimerURL
: Link to the DISCLAIMER.md file stored in the project. Must use the raw variant of the file (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/raw/master/DISCLAIMER.md" for the main/master branch or "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/raw/1.1.1/DISCLAIMER.md" for the Release Candidate branch). -
repositoryURL
: Link to this project on GitLab/GitHub. Must include the .git extension (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting.git"). -
tags
: An array of topical/domain tags relevant to the project. Add this tag with your DOI:"doi|https://doi.org/XX.XXXX/XXXXXXXX"
. If the project leverages or is related to AI/ML in any way, this array must include the tag "usgartificial-intelligence". This tag is short for U.S. Government Artificial Intelligence (i.e., do not use "usgs-artificial-intelligence"). -
languages
: An array of the programming languages used within this project. -
date.metadataLastUpdated:
An ISO datestamp of when the code.json file was last modified. Be sure to update this value whenever you modify anything in this file. - See the official code.gov metadata schema for details about additional fields.
Note that the top-level element in this file is an array. This means it may contain more than one release object for your project; for example, if this project has been under development for a long time, there may be multiple released versions. In this case, release objects should be ordered with the most recently released version appearing first, and so-on in reverse chronological order. For example:
[
{
// ... release 3.0.0, status Development
},
{
// ... release 2.0.0, status Production
},
{
// ... release 1.0.0, status Archival
}
]
This metadata evolves over time. In the example above, the release tag for version 1.0.0 would only include metadata for that release and it would likely have a status of Production. Then in the release tag for version 2.0.0, two release objects would exist in the array; first would be 2.0.0 with status Production and second would appear 1.0.0 with status Archival, and so on...
LICENSE.md
An appropriate open-source license must be included in a LICENSE.md file located at the top level of the project. Both casing and file extension are important.
Selecting the appropriate license may depend on the project, its provenance, its dependencies, or other factors. A default starting point is provided but may not be appropriate in all cases. If you are not sure which license to select, please consult with the Office of the Solicitor for legal guidance.
DISCLAIMER.md
A Fundamental Science Practices (FSP) disclaimer must be included in a DISCLAIMER.md file located at the top level of the project. Both casing and file extension are important.
Use this content for a provisional release and this content for an official release.
IPDS Process
- Visit the IPDS website.
- Click "New Product Record".
- Enter the required information and any other relevant information. This information can be edited later. Hints:
- Cost Center: Typically "Upper Midwest Water Science Center"
- USGS Region: Typically "Midcontinent Region"
- If you do not have an ORCID, visit the ORCID website to create one. If you already have an ORCID but can't remember it, try visiting your staff profile (e.g., https://www.usgs.gov/staff-profiles/hans-w-vraga) and see if it is in the sidebar.
- Click "Save".
- Click the "Authors" tab. Click "Edit" and add all authors.
- Click the "Reviewers" tab. Click "Edit" and all all reviewers.
- Click the "Bibliodata" tab. Click "Edit" and add all relevant information. Hints:
- Published URL: link to the Release Candidate branch of the repository (e.g., https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/tree/1.1.1)
- Digital Object Identifier: DOI URL provided by the USGS Digital Object Identifier (DOI) Creation Tool
- Interpretive Publication: DOI URL of any accompanying publications
- Click the "Documents" tab. When you are ready to add a document, click "Edit" and then "Upload". Choose the file and click "OK". Edit the "Name" of the file if desired. Copy the "Name" of the file for the "Title". Select the "Document Type" (see descriptions below). The "Description" is optional but is a helpful place to add any relevant URLs. Throughout the review process, you will need to provide the following documents:
- Author's original manuscript: Zipped up version of repository prior to any reviews. It is helpful to provide a link to this branch in the "Description" field.
- Peer review: Document that describes the findings of peer review. You can upload one document for all three review types or three separate documents. This document can be in the form of a memo, GitLab/GitHub issues, etc.
- Peer review reconciliation: Document that describes how you addressed the findings of all reviews. This document can be in the form of a memo, GitLab/GitHub Merge Requests, etc.
- Final manuscript for Bureau approval: Zipped up version of repository after all reviews. It is helpful to provide a link to this branch in the "Description" field.
- Other: You must include documents that describe additional reviews and review reconciliation that come from from the supervisor or Bureau Approving Official (BAO) reviews.
- Click the "Notes" tab. Click "Edit" and "new note". Write a note: e.g., "URL for software release: https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/tree/1.1.1" and click "Save".
- Click the "Routing" tab. Click the "Request Peer Review" link to initiate the IPDS routing process. Description of the routing steps:
- Request Peer Review: The senior USGS author finishes fine-tuning the software repository, uploads the zipped up version of the repository to the IPDS record, and discusses potential reviewers with their supervisor.
- Accept for Peer Review: The supervisor confirms that the selected peer reviewers are adequate, determines the need for courtesy review, and considers whether the software should be considered influential scientific information or highly influential scientific assessments.
- Reconcile Peer Review: The senior USGS author uploads peer review documentation to IPDS, addresses (reconciles) peer review comments, uploads peer review reconciliation documentation to IPDS, and uploads the updated version of the software repository to IPDS.
- Supervisory Approval: The supervisor ensures the author had adequately addressed peer review and prepared a suitable final draft of the software, informs the Center Director if the software might be sensitive or controversial, and identifies any internal or external groups or agencies that might have a particular or immediate interest in the software.
- Bureau Approval: The Bureau Approving Official (Center Director or delegated official) confirms that the appropriate officials have been notified for potentially policy-sensitive or high-visibility software and confirms that the appropriate review, approval, and release requirements are followed to ensure meeting USGS science quality standards.
- Dissemination: The senior USGS author completes this step when the IPDS bibliographic metadata is complete, the DOI has been published, and the software has been publicly released.
DOI Process
- Visit the USGS Digital Object Identifier (DOI) Creation Tool.
- Log in. If your AD username does not work, try using your email address.
- Click "Create DOI".
- Enter the title of the software (should be the same title as your GitLab/GitHub project).
- Select the USGS science center or program responsible for managing the software.
- Select "No" for the question "Will these data be released through the formal ScienceBase Data Release process?"
- Click "Reserve my DOI".
- In the "Who can manage this DOI?" section, add the co-authors and other applicable personnel.
- Click the "Required Information" tab.
- In the "Publication Year" section, add the calendar year in which the software will be published.
- In the "Creator(s) / Author(s)" section, add all the authors.
- In the "Location URL" section, add the link to the Release Candidate branch of the repository (e.g., "https://code.usgs.gov/StreamStats/web-services-and-apis/ChannelWeighting/-/tree/1.1.1")
- In the "Resource Type", select the appropriate category.
- In the "IPDS Number(s) for this Data Product Release" section, add the IPDS number.
- In the "Link this data release DOI to the DOI of the primary USGS-authored publication" section, add the DOI URL or IPDS number of any associated publications, if applicable.
- Click the "Supplemental Information" tab.
- Add any relevant supplemental information.
- Click "Save Unpublished Record".
- When the software has received Bureau Approval in IPDS, click the "Publish Approved Release to DataCite" button to make the DOI public.
Reviews
See the USGS Types of Software Review page for more information.
Identify qualified reviewers for each review type below. One reviewer can complete more than one review type. Create issues and labels for each review type and assign the reviewer to the issue.
Administrative Security Review
All software must have an administrative security review before it is made publicly available by any method. This type of review ensures personal, private, or otherwise sensitive information is not included in the repository. Types of sensitive information include:
- Personally identifiable information (PII)
- Absolute file system paths
- Internal server host names or IP addresses
- Usernames/passwords
Administrative security reviews may be performed by any trusted person; the reviewer does not necessarily need a strong scientific or programming background. When migrating an existing project into any non-private Git repository, it is important to remember that the entire project history needs to be reviewed if that history is to be maintained after migration.
If you see any issues, please create new issues and add the "security review" label.