Dataset Preparation Guides for the EDI Community (data-package-best-practices)

This repository contains a series of documents about preparing and publishing datasets in the environmental sciences and similar contexts. Topics include community-developed metadata standards, serialization and markup formatting guidelines, and best practices for the content of published research datasets. This documentation is maintained by the Environmental Data Initiative (EDI) and all content has been developed and written in collaboration with EDI's community of scientists, data managers, and repository users. Two versions of this content are published online:

• The current production version, derived from the main branch of the repository.
• A prerelease version containing new and in-development documents, derived from the prerelease branch.

The guide documents are published as a collection of Quarto books. Revisions and additions to these guides will occur using this repository, with periodic release and distribution of copies in print-ready formats (PDF, MS Word). For more on the history of this effort, and archived earlier editions of the guides, see the History page.

Contributing

The maintenance of this repository and development of the included documents is coordinated by EDI, with major updates and new content developed and approved through a community-oriented process. If you would like to contribute to these documents, please contact the maintainers and working group leads listed on the About page, or reach out to EDI at [email protected]. Some details on how contribution works are below.

Branches

• main: The main branch holds the current production version of the documents. Documents in this branch have generally been edited and approved by the community. They are published in website format with GitHub Pages, under the "EDIorg" organization.
• prerelease: The prerelease branch contains documents that are under development for publication in an upcoming release. These documents contain new content and revisions to existing documents that may be under review by the community. Documents in this branch are published in website format to Netlify. After review and approval, changes may be merged into main.
• feature or content branches: These may exist during the early development of new features or drafting of content. They will first be merged into the prerelease branch for review. No feature or content branches are currently published in website form.

Contributing changes

The guide documents and most website content are written in Quarto markdown, a variant of pandoc markdown, and saved as .qmd files. See the Quarto guide for information on how to author .qmd files. New content, or edits to existing documents, can be contributed in several possible ways:

1. To suggest a change you may file an issue in the GitHub repository outlining your proposed changes. This will begin a conversation with the maintainers and others in the community about whether and how to implement changes to the documents or website. You may be invited to draft the content changes (see the next item).
2. If you are ready to create a draft of the changes yourself, new .qmd files or edits to existing pages may be submitted as a pull request to the prerelease branch. See this GitHub tutorial for some simple instructions and links to more resources. Maintainers will review the changes before merging them into the prerelease branch for further community input.
3. In some cases, particularly if you are involved in a community working group, you may request permission to push changes directly to the prerelease branch. If you think this would be the best way to contribute your changes please contact the maintainers listed in the About page or [email protected].
4. Periodically, community working groups convene to develop and draft changes to these guides, and much of the writing, revising, and editing process takes place in formats outside this repository (Word or Google Docs). To get involved in one of these efforts and contribute changes that way, see the About page and contact working group leads, or propose your own working group to the community.

Once changes are moved into the prerelease branch, they will be reviewed by the the larger community (EDI, LTER Network, EML users, repository communities, etc.) and approved (or not) for inclusion in the production documents (main branch).

Publishing workflow

Both main and prerelease branches have GitHub Actions workflows configured to build and deploy their associated website any time new commits are pushed to that branch. The production site, derived from main, is published as a GitHub Pages site (Quarto documentation). The prerelease site, derived from the prerelease branch, is published to Netlify (Quarto documentation). The GitHub Actions publishing workflow for both branches is specified in the .github/workflows/publish.yml file, which was modeled in part on the Quarto website version. When changes are pushed to either branch, please verify that the GitHub Action completed and the website and all documents were built as expected.