-
Notifications
You must be signed in to change notification settings - Fork 0
/
contributing.qmd
92 lines (52 loc) · 4.83 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
---
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).
## 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 >}}