-
Notifications
You must be signed in to change notification settings - Fork 6
/
contributing.qmd
24 lines (15 loc) · 4.42 KB
/
contributing.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Contributing {.unnumbered}
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 help develop these documents please contact the maintainers and working group leads listed on the [About](about.qmd) page, or reach out to EDI at [info@edirepository.org](mailto:info@edirepository.org>). 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 the in-development, "next version" of the documents. These documents contain new content or changes submitted by, or under review by the community. Documents in this branch are published in website format to Netlify. After a review and approval process 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 and they are not 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](https://quarto.org/docs/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](https://github.com/EDIorg/data-package-best-practices/issues/new/choose) 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](https://github.blog/developer-skills/github/beginners-guide-to-github-creating-a-pull-request/) 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](about.qmd) page or <info@edirepository.org>.
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](about.qmd) 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](https://quarto.org/docs/publishing/github-pages.html#github-action)). The prerelease site, derived from the `prerelease` branch, is published to Netlify ([Quarto documentation](https://quarto.org/docs/publishing/netlify.html#github-action)). The GitHub Actions publishing workflow for both branches is specified in the [`.github/workflows/publish.yml`](.github/workflows/publish.yml) file, which was modeled in part on the [Quarto website version](https://github.com/quarto-dev/quarto-web/blob/main/.github/workflows/publish.yml). When changes are pushed to either branch, please verify that the GitHub action completed and the website and all documents were built as expected.