-
Notifications
You must be signed in to change notification settings - Fork 23
/
Copy pathcontributing.qmd
104 lines (58 loc) · 5.57 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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
---
title: Get Involved
---
## Introduction
We encourage contributions to this guide. The guide's goal is to provide documentation on the best practices for the current state-of-the-art cloud-optimized formats. These formats are evolving, and so will the guide.
## Pre-requisites
If you wish to preview the site locally, install [quarto](https://quarto.org/). You will also need to be familiar with [quarto markdown](https://quarto.org/docs/authoring/markdown-basics.html).
## Contribution Workflow
Due to previews only working from branches within the repository and not external forks (see: [#74](https://github.com/cloudnativegeo/cloud-optimized-geospatial-formats-guide/issues/74)), all PRs should target staging. More specifically, the contribution workflow follows these steps:
1. PR is made with `staging` as target.
2. Maintainer will merge the PR to staging and then open a PR to main (build preview will run).
3. Maintainers merge to main which triggers the production deployment.
The process is not ideal, and we are open to suggestions on how to improve upon it. The main constraint is the [`pr-preview-action`](https://github.com/rossjrw/pr-preview-action) not supporting previews on external contributions.
## Communication Channels
Discussions can occur in [GitHub Discussions](https://github.com/cloudnativegeo/cloud-optimized-geospatial-formats-guide/discussions) and issues can be raised at [GitHub Issues](https://github.com/cloudnativegeo/cloud-optimized-geospatial-formats-guide/issues).
- **GitHub Discussions**: Ideal for questions, feature requests, or general conversations about the project. Use this space for collaborative discussions or if you're unsure where to start.
- **GitHub Issues**: Use this for reporting bugs, suggesting enhancements, or other tasks that require tracking and possibly code changes.
## Core Principles
1. This guide intends to be opinionated but acknowledges no one-size-fits-all solution.
2. This guide should provide the best information and guidance available but acknowledge that experts develop many existing resources. Those resources should be linked as appropriate.
## Additional Criteria
- All examples should use open data. If an example uses data from NASA Earthdata, it must include an example of providing credentials ([Earthdata registration](https://urs.earthdata.nasa.gov/users/new) is available to anyone).
- Landing pages with no code should use [quarto markdown (`.qmd`)](https://quarto.org/docs/authoring/markdown-basics.html).
- Pages with executable code should be [Jupyter Notebooks (`.ipynb`)](https://ipython.org/notebook.html).
## Code of Conduct
- Be inclusive, respectful, and understanding of others' backgrounds and contexts.
- Look for and foster diverse perspectives.
- If you experience any harmful behavior, please get in touch with [Aimee](mailto:[email protected]) or [Alex](mailto:[email protected]).
## Bug Reporting & Feature Requests
Before submitting a bug report or a feature request, please start a [GitHub Discussion](https://github.com/cloudnativegeo/cloud-optimized-geospatial-formats-guide/discussions) to see if the issue has already been addressed or if it can be resolved through discussion.
### General Steps
1. Fork the repository.
2. Clone your fork locally.
3. Create a new branch for your changes.
4. Make your changes and use `quarto preview` to make sure they look good.
5. Open a pull request.
Once the pull request is opened, and the GitHub `preview.yml` workflow runs ("Deploy PR previews"), you should have a preview available for review at `https://guide.cloudnativegeo.org/pr-preview/pr-<YOUR-PR-NUMBER-HERE>`. A bot will comment on your PR when the PR preview is ready.
### Specific Contributions
#### 1. Adding a New Format
Follow the steps outlined in the General Steps, then:
1. Create a folder with the format's name and, within that folder, an `intro.qmd`.
2. Link to the `intro.qmd` page in the `index.qmd` (the **Welcome** page) file and `_quarto.yml` table of contents.
#### 2. Modify or Add to an Existing Format
Feel free to modify or add to existing content if you think it could be improved.
#### 3. Adding a Cookbook
Cookbooks should address common questions and present solutions for cloud-optimized access and visualization. To create a cookbook, either add a notebook directly to this repository in the cookbooks directory OR use an external link and add it to cookbooks/index.qmd.
#### 4. (Optional) Update Slides
If you have made substantive changes, consider updating the [Overview Slides](./overview.qmd). These slides are generated using [Quarto and Reveal.js](https://quarto.org/docs/presentations/revealjs/) so can be updated with markdown syntax.
#### 5. Add Yourself to the List of Authors
Add yourself to the list of authors on the [Welcome](./index.qmd#authors) page.
#### 6. Final Steps Before Merging
Once your PR is approved and all checks have passed, a project maintainer will merge your changes into the main repository.
## Licensing
This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit [http://creativecommons.org/licenses/by/4.0/](http://creativecommons.org/licenses/by/4.0/). For attribution requirements, please look at the [license terms](http://creativecommons.org/licenses/by/4.0/).
Preferred citation: `Barciauskas, A et al. 2023. Cloud Optimized Geospatial Formats Guide. CC-By-4.0`.
## Contact
For questions on how to contribute, start a discussion in the [GitHub Discussions](https://github.com/cloudnativegeo/cloud-optimized-geospatial-formats-guide/discussions) section.
{{< include _thankyous.qmd >}}