Contributing

The maintenance of this website and documentation it contains is coordinated by EDI, with major revisions and new contributions developed and approved through a community-oriented process. We welcome community contributions of any size, but for significant new content or revisions to existing guides we recommend first contacting the maintainers and working group leads listed on the About page, or reaching out to EDI at info@edirepository.org. Community working groups periodically convene to develop and draft changes to the guides, and getting involved in one of these efforts, or proposing your own, may be the best way to make big contributions.

Depending on the scale and who is involved, the path to contributing can vary. Below we describe our repository and several methods you or your group can use to contribute.

The repository

All website content and guides are stored in a GitHub repository and the revision process for the content is generally handled there through the publication stage. The repository has several branches, described below.

  • main: The main branch holds the current production version of the documents, which are published in website format, using GitHub Pages, under the “EDIorg” organization. All content in this branch has generally been edited and approved by the community, but the branch is not open to direct contributions from anyone but the project maintainers (no push access).
  • prerelease: The prerelease branch contains the in-development, “next version” of the documents that have been submitted by, or are under review by the community. Documents in this branch are published in website format to Netlify. After a community-based review and approval process, the maintainers merge new or edited content into the main branch. Some contributors, particularly those involved in community working groups, can request permission to push changes directly to the prerelease branch.
  • 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 and are not currently published in website form.

Contributing changes

The guides and other website content found here are written in a variant of Markdown, and saved as .qmd files. These .qmd files are rendered by the Quarto documentation system to create the guides in HTML (this website) and other useful formats including PDF and MS Word. To contribute new content, or edits to existing documents, we recommend using one of the three pathways described below.

1. File a GitHub issue

To suggest changes to the content or the website you may file an issue in the GitHub repository outlining your proposed changes. Please be descriptive about your issue and, for content revisions, reference the specific guide, chapter, and section you are referring to. Filing an issue begins a conversation with the maintainers and others in the community about whether and how to implement changes to the documents or website. For some types of issues (new content, extensive revisions) you may be invited to draft the contribution using one of the two other methods below.

This method is best for:

  • Smaller content contributions (typos, broken links, minor revisions)
  • New or external contributors not involved in working groups or site maintenance
  • Technical issues (not content-related) like document rendering or website navigation problems

2. Submit a pull request

You can contribute new content, or draft revisions to existing content, by submitting a pull request to the prerelease branch of the GitHub repository. These kinds of pull requests usually contain new .qmd files, or edits to the ones already in the repository (other pull requests might change metadata, website configurations, or things like that). The process for creating and submitting pull requests usually follows these steps:

  1. Contributors make a copy of this repository that they can edit locally (these copies are also called “clones” or “forks”). See the GitHub docs for details on how to do this.
  2. In the copied repository, edit the relevant Quarto markdown files until they are ready to contribute back to this repository. Follow the Quarto authoring guide for information on using the Quarto variant of markdown.
  3. When changes have been reviewed and are ready to submit, create a pull request from the copied repository to this GitHub repository. Again, follow the GitHub docs, or this GitHub tutorial for simple instructions and links to more resources.

Once the pull request is received, maintainers will review the changes before merging them into the prerelease branch for further community input. If multiple contributors are working together on pull requests, please coordinate to avoid multiple pull requests that edit the same content and overwrite one another.

This method is best for:

  • Large content, layout, or technical changes (chapter revisions, website restructuring)
  • Technically-savvy groups or contributors (or the technical lead of a working group)

3. Use a MS Word or Google document

For extensive editing of the guides, or editing in collaborative teams, it may be useful to export documents into a word-processor format (MS Word or Google Docs) and manage group contributions and feedback there. This is often the approach taken by community working groups who have significant revisions to make, or are developing all-new chapters or guides. Be aware that this method requires coordination with maintainers or working group leads, so please reach out to contacts listed on the About page.

Most guides on this website, including the EML Best Practices and Design for Special Cases guides, have an MS Word (.docx) formatted version already available, just look for the link in the upper right corner of the guide’s web pages to download it. Once a Word-formatted guide is downloaded, the likely next steps are to:

  1. Save the file with a timestamped filename like guide-eml-bp.2026-08-25.docx, or similar.
  2. If collaboratively editing in a group, upload to a cloud platform (e.g. Google Drive) so everyone in the group can access it.
    • Optionally, the group can convert the Word file to a native Google Docs format, which enables more collaboration features. If keeping as a Word file make sure to enable track changes anytime edits are happening outside the Google Drive.
  3. Make edits to the content until satisfied with the new or revised document.
  4. Once finished and ready for review the revised document must be converted to .qmd format. There are some tools available to convert MS Word and Google Docs to Markdown, or reach out to a maintainer or working group lead that can provide assistance with conversion.
  5. The revised document must now be merged into the content of the prerelease branch of the repository and website. Notify a maintainer or working group lead for assistance with this step.

This method is best for:

  • Larger content contributions (chapter or full-document revisions)
  • Groups with mixed technical (GitHub) abilities
  • Collaborative revisions where input from a broad community is required

Review and publication

Once changes are contributed to the prerelease branch of the repository using any of the methods above, they can be reviewed by maintainers and the larger community (EDI, LTER Network, EML users, repository communities, etc.). Upon community approval, the maintainers will merge the new changes into the production version of the guides and website (main branch) and then published.

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.