Administrative Review
The administrative review checks that your project meets various legal, security, and administrative requirements prior to release. Conducting this review is one of the final steps before releasing code. This review may be conducted by any trusted individual.
Items in this review include:
README
The top-level of the project must contain a file named README.md (the case and file extension must match exactly). The file must be written in MarkDown format. The README should contain introductory information about the project (title, description, citation, recommended use, etc). It should also include links to additional detailed information, such as license information, documentation, installation instructions, user guide, related manuscript(s), etc.
The README should contain a section labeled “Summary” or “Purpose” or “Abstract”. This section may be as short or long as the author desires, but should contain enough information for an interested person to understand the project’s intended purpose. Essentially, this should help someone unfamiliar with the software to decide whether the software is suitable for their purposes.
The README should also contain a “Suggested Citation” section. The citation should follow the format:
Author1, A., Author2, B., Author3, C., project-slug - A one-line description (tagline) for the project, version X.Y.Z: U.S. Geological Survey software release, https://doi.org/the-doi-for-the-release
replacing the author names, project slug, tagline, version tag, and DOI with the actual values for your project.
License
The project’s license must be disclosed in a top-level file named LICENSE.md (case and extension must match exactly). The project must use an open source license. You can find resources for selecting a license here: Open Source Licenses.
Disclaimer
The project must contain the FSP provisional disclaimer in a top-level file named DISCLAIMER.md (case and extension must match exactly). The contents of this file must be exactly the following text:
Disclaimer
==========
This software is preliminary or provisional and is subject to revision. It is
being provided to meet the need for timely best science. The software has not
received final approval by the U.S. Geological Survey (USGS). No warranty,
expressed or implied, is made by the USGS or the U.S. Government as to the
functionality of the software and related material nor shall the fact of release
constitute any such warranty. The software is provided on the condition that
neither the USGS nor the U.S. Government shall be held liable for any damages
resulting from the authorized or unauthorized use of the software.
Security
The entire commit history cannot contain any security issues. If you have been following this guide, you should have completed a series of incremental security reviews, one per merge request.
If this is the case, you have already completed this step, and linking to the archived security reviews is sufficient. Otherwise, the reviewer will need to perform a security review for every new commit in the release.
Code Metadata
The project must include code metadata stored in a top-level file named code.json. Please see the code.json page for formatting instructions
Rubric
The following table provides the administrative review rubric:
Item |
Pass |
Fail |
|---|---|---|
Project includes a top-level file named |
README does not exist or does not sufficiently introduce the project. |
|
README is written in Gitlab-flavored MarkDown. |
README uses some other format. |
|
README contains a “Summary”, “Purpose”, or “Abstract” section explaining the project’s purpose. |
README is missing a summary section. |
|
README has a suggested citation section, formatted in the recommended style |
README is missing a citation section, or the citation is formatted incorrectly. |
|
Project includes a top-level file named |
|
|
Uses an open source license |
License is not open-source |
|
Includes a top-level file named |
Does not include disclaimer, or disclaimer uses different text. |
|
The commit history does not contain any security issues. |
The commit histroy contains security issues. |
|
Project contains a correctly formatted |
|
Gitlab How-To
You should implement the administrative review using a Gitlab issue thread. Navigate to the main page of the upstream repository. In the navigation sidebar, click the Plan menu and select the Issues button.
Show button
Click the New issue button. This will take you to a page for the issue. Set the title to Administrative Review and also include the release tag. The description should include the name of the reviewer.
Show Example
Next, add the Admin Review label to the issue. If you have not yet created these labels, you can do so by clicking the Create project label button in the dropdown box:
Show Example
Click the Create issue button, and direct your reviewer to the associated page. You and the reviewer should use the comment thread to document the review and reconciliation process. Once the review is reconciled, the reviewer should leave a comment explicitly stating that the repository has passed the administrative review. You may then click the Close issue button to resolve the review. This will archive the review in the closed issues for the repository.
Show Example
