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. You will also need to be familiar with quarto markdown.

Communication Channels

Discussions can occur in GitHub Discussions and issues can be raised at GitHub 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

This guide intends to be opinionated but acknowledges no one-size-fits-all solution.
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 is available to anyone).
Landing pages with no code should use quarto markdown (.qmd).
Pages with executable code should be Jupyter Notebooks (.ipynb).

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 or Alex.

Bug Reporting & Feature Requests

Before submitting a bug report or a feature request, please start a GitHub Discussion to see if the issue has already been addressed or if it can be resolved through discussion.

General Steps

Fork the repository.
Clone your fork locally.
Create a new branch for your changes.
Make your changes and use quarto preview to make sure they look good.
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:

Create a folder with the format’s name and, within that folder, an intro.qmd.
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. These slides are generated using Quarto and Reveal.js 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 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/. For attribution requirements, please look at the license terms.

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 section.

Our Supporters

Thank you to our supporters

This guide has been made possible through the support of: