USGS-R Packages

• Critically important to a wide and general audience
• Published, peer-reviewed documentation on the package
• A statement of long-term support should be included in the README. This should communicate the source, timeline, and extent of support.

For example:

1. Source, e.g., "USGS Water Mission Area"
2. Timeline, e.g., "funding is stable through FY18 and is likely to be renewed into FY19 and beyond"
3. Extent, e.g., "funding is available for new features, with priorities determined by the development team"
• Reasonable effort to make prompt responses for the following:
• Bug fixes
• R version upgrades
• Upstream R-package dependency change
• User support and troubleshooting

We recommend that maintainers attempt to acknowledge bugs and other issues as soon as they are discovered via a standard public channel such as a GitHub Issue. Then, publicly track the work, giving estimates of time and effort along the way.

• An active USGS employee is designated as maintainer
• Development and maintenance of core packages should include a team of developers. Maintainers coordinate and lead the development team, but should not be the sole developer. This increases the Bus Factor ("many individuals know enough to carry on and the project could still succeed even in very adverse events").
• The package is well tested

For example, all critical functions should be tested for expected results using the testthat package. The coverage of testing can be measured using the coveralls or codecov services.

• The package should be tested on a continuous integration platform regularly. A few example continuous integration platform services are Travis CI, and AppVeyor
• All external functions have clear documentation and working examples

• The package is in active development and there is no guarantee of future behavior.
• An official disclaimer is shown on the README, and any vignette
• The package startup message needs to either include the above disclaimer, or link to this page:

.onAttach <- function(libname, pkgname) {
  packageStartupMessage(paste(strwrap(
  'USGS Research Package: 
  https://owi.usgs.gov/R/packages.html#research'),
  collapse='\n'))
}

Which will show the user:

library(toxEval)
USGS Research Package: 
https://owi.usgs.gov/R/packages.html#research

• The development of the package is being driven by a research topic, and should include input from both researchers and software developers.
• The end goal should be one or more peer-reviewed journal publications.
• A statement of support should be included in the README. This should communicate the source, timeline, and extent of support.

For example:

1. Source, e.g., "Water Mission Area"
2. Timeline, e.g., "funding is stable through FY17 and might be renewed into FY18 and beyond"
3. Extent, e.g., "funding is available for new features, with priorities determined by the development team" or "support is primarily for maintenance rather than new features" or "support covers maintenance and bug fixes, but we're awfully short on time for user questions, sorry"
• It is encouraged to include a "sunset" date in the README or package startup message.

.onAttach <- function(libname, pkgname) {
  packageStartupMessage(paste(strwrap(
  'USGS Research Package: 
https://owi.usgs.gov/R/packages.html#research
Funding for toxEval expires summer 2017, 
after which bug fixes & new features will be minimal'),
  collapse='\n'))
}

Which will show the user:

library(toxEval)
USGS Support Package: 
https://owi.usgs.gov/R/packages.html#support
Funding for toxEval expires summer 2017, 
after which bug fixes & new features will be minimal

• Emphasis should still be placed on testing key features and good documentation during development.
• Since the goal is a published article, the expectation should be that outside users will use this package to test the reproducibility of the primary author’s data analysis, as well as reproducing the analysis on new data.
• During development, the package version should remain below v1.0.0.

• The development of the package was completed with the publishing of a scientific, peer-reviewed journal or report
• A reproducible work-flow is included either within a vignette or via the final product (such as the journal article)
• There are no official expectations that bug fixes and R version upgrades will happen. The expectations need to be clearly communicated to the users
• The package maintainer should have an active email.
• The package version should be updated to v1.0.0 once a stable version is released.
• Once the final version is released, the maintainer should provide the output of devtools::session_info() for an archive of the environment in which the code was last tested and verified as stable.

• An active USGS employee is designated as maintainer. Development and maintenance of support packages should include a team of developers. Maintainers coordinate and lead the development team, but should not be the sole developer.
• The package is well tested

For example, all critical functions should be tested for expected results using the testthat package. The coverage of testing can be measured using the coveralls or codecov services.

• The package should be tested on a continuous integration platform regularly. A few example continuous integration platform services are Travis CI, and AppVeyor
• Key functions should have clear documentation and working examples.
• An official disclaimer is shown on the README, and any vignettes:
• The package startup message needs to either include the above disclaimer, or link to this page:

.onAttach <- function(libname, pkgname) {
  packageStartupMessage(paste(strwrap(
  'USGS Support Package: 
  https://owi.usgs.gov/R/packages.html#support'),
  collapse='\n'))
}

Which will show the user:

library(smwrGraphs)
USGS Support Package: 
https://owi.usgs.gov/R/packages.html#support

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.

Refer to https://www2.usgs.gov/fsp/fsp_disclaimers.asp for more information.