Commonly Included Files

Last updated on 2025-05-22 | Edit this page

Estimated time: 10 minutes

Overview

Questions

  • What are some files which are usually included in USGS software projects, and what should their content be?

Objectives

  • Draw awareness to common “boilerplate” files which are usually included in software products.
  • Provide usable examples of each of these.

Disclaimers

All USGS software information products must contain appropriate disclaimers. This is unique among the files discussed here. While the others are strongly recommended, they are not required by Fundamental Science Practices (FSP).

The location of the disclaimer must be given as part of the code.json metadata which accompanies USGS software information products (see episode Creating Metadata).

The disclaimer used for open-source software projects must be different from the one used for official USGS software information Products.

Provisional disclaimers

The provisional disclaimer must remain in any branch or tag which does not represent an official USGS software information product. The official disclaimer may only be used in tags (or temporarily in release-candidate branches working towards a tag) that represent Official USGS Software Information Products.

For more information on this, see the Reviews for Authors lesson on preparing the release branch and the Publishing lesson on managing tags.

Open-source software projects

For an open-source software project, appropriate content for the DISCLAIMER.md may be found in section 11 of the FSP Guidance on Disclaimer Statements Allowed in USGS Science Information Products:

Official USGS Software Information Product

For an official USGS software information product, appropriate content for the DISCLAIMER.md may be found in section 5 of the FSP Guidance on Disclaimer Statements Allowed in USGS Science Information Products:

Readme

When included, a README.md file will be rendered to text on the GitLab page of its project. This file should give a human-readable description of the project. It can also contain details about how to use the project. It should also give pointers to other relevant information about the project, when that information is contained in other files. For example, there might be a “Contributing to this project” section which points to a CONTRIBUTING.md file, or an R library’s README.md might point users to that library’s vignettes.

For some examples of effective README files in USGS projects, see

Contributing

If you are willing to accept contributions from outside your team, you can include a CONTRIBUTING.md which explains your project’s policies and procedures for doing so. An example is below.

Customize the example for your project

Before using the example below, you would need to change [1] and [4] to appropriate URLs from your package repository, and choose appropriate URLs for [2] and [3] based on whether your project is on GitHub or GitLab.

MARKDOWN 

Contributing
============

Contributions are welcome from the community. Questions can be asked on the
[issues page][1]. Before creating a new issue, please take a moment to
search and make sure a similar issue does not already exist. If one does
exist, you can comment (most simply even with just a `:+1:`) to show your
support for that issue.

If you have direct contributions you would like considered for incorporation
into the project you can [fork this
repository](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#create-a-fork)
and [submit a merge
request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#when-you-work-in-a-fork)
for review. Please note that all contributions will be considered public domain
(see [license][2] for details).

[1]: Replace this text with the URL for your project's issues page
[2]: Replace this text with the URL for your project's license

Code of Conduct

This is a file, typically called CODE_OF_CONDUCT.md, that describes expected conduct from users contributing to the project. At a minimum this file must specify that all contributions to the project must abide by the USGS Code of Scientific Conduct. It is also appropriate for it to include further language specifying expectations for contributors’ behavior as part of the project’s community. A suitable example of such a file’s contents follows:

MARKDOWN 

# Contributor Code of Conduct

All contributions to- and interactions surrounding- this project will abide
by the [USGS Code of Scientific Conduct][1].

[1]: https://www2.usgs.gov/fsp/fsp_code_of_scientific_conduct.asp

We are committed to making participation in this project a harassment-free
experience for everyone, regardless of level of experience, gender, gender
identity and expression, sexual orientation, disability, personal
appearance, body size, race, ethnicity, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual
language or imagery, derogatory comments or personal attacks, trolling,
public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct. Project maintainers who do
not follow the Code of Conduct may be removed from the project team.

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by opening an issue or contacting one or more of the project
maintainers.

This Code of Conduct is adapted from the Contributor Covenant, version 1.0.0

Which file must be included in all USGS software repositories?

There are conventions for files included in software repositories that explain the purpose of the repository or how its team works. Many of these are recommended but optional. One, however, is mandatory. Which file is mandatory, and why?

The DISCLAIMER.md is mandatory in published USGS software repositories, because it is required by FSP.

Key Points

  • USGS software products typically contain “boilerplate” files.
  • Some of these files, like the DISCLAIMER.md, are mandatory and must be included in all USGS software products. Others are optional.
  • Examples of these files may be found in existing projects, or on this page.