In this document, you will find our suggested template for creating a GitHub repository README.md file that describes data and metadata reporting formats. README files are written in the markdown language and when they are rendered on GitHub or in a GitBook, they are easily readable as a web page. This site provide a helpful guide for the type of coding that can be done in markdown: https://commonmark.org/help/
The suggestions in this template are based on a systematic review we conducted of 32 GitHub repositories that are used for managing data standard and reporting format documentation.
We have written this document so that you can easily copy and paste this template into your own README file by:
- Clicking the
rawbutton at the top right of this page - Copy and paste the text that appears into your own file on GitHub and make sure the new file ends in
.md - Replace the text under each heading (indicated by
##) to describe your reporting format.
Provide the name of your reporting format in the heading above, and we suggest you add a short (3 or 4 sentence) overview of the motivation for creating the data reporting format.
Your README.md file should contain a short description of your repository. This can be placed either directly under the title of your README file as we wrote the few sentences above or you can write a description under an "About" heading like we have included here. This is also a good place to link out to additional supporting documentation on other non-github websites.
The getting started section of your repository is like a table of contents that lists out a concise version of the most important documents and templates a reader can expect to find in your repository. You do not need to link to every document in your GitHub repository, but you should link to the most essential documents, so that visitors can locate and access them quickly.
Provide details in this section that lets readers know how to suggest modifications to your repository. We recommend that you give a direct link to your GitHub issues page. We also suggest that you set up issue templates, so that when users submit a GitHub issue, they do so in a format you specify. Examples of issue templates can be found here.
There are many options for choosing a usage license. GitHub has put together a helpful guide on repository licensing: https://choosealicense.com/ If you eventually upload your repository as a complete data package to the ESS-DIVE data repository, the data package will have either a CC BY 4.0 or a CC BY 1.0 and you should indicate that license here.
If your contribution to the ESS-DIVE Community Space was supported by ESS-DIVE funding please use the following acknowledgment:
ESS-DIVE is funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research, Climate and Environmental Science Division, Data Management program under contract number DE-AC02-05CH11231.
If your contribution used NERSC resources:
ESS-DIVE uses resources of the National Energy Research Scientific Computing Center (NERSC), a DOE Office of Science User Facility operated under Contract No. DE-AC02-05CH11231.
Often, you will upload a finalized version of the content you store in the GitHub Community Space to the ESS-DIVE repository. We ask that you provide a citation to that ESS-DIVE package here in your README file and include the DOI for that citation.
If you have published an article or conference paper that is associated with your contribution to this community space, you can also provide the citation for that here.
This section is for other references that you cite within the README page.