Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Contributing to the Project Pythia Portal

This document contains information specific to contributing to the
Project Pythia Portal. Please first refer to [Guide for Contributing to Project Pythia](https://projectpythia.org/contributing.html) for overall
Project Pythia Portal. Please first refer to [Guide for Contributing to Project Pythia](https://projectpythia.org/contributing) for overall
contribution guidelines (such as detailed description of Project
Pythia structure, forking, repository cloning, branching, etc.).

Expand Down
10 changes: 5 additions & 5 deletions portal/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@
This the top-level guide for Project Pythia and a great starting point for getting involved!

We also have specific guides for
[contributing to Pythia Foundations](https://foundations.projectpythia.org/appendix/how-to-contribute.html)
and [contributing new Cookbooks](https://projectpythia.org/cookbook-guide.html).
[contributing to Pythia Foundations](https://foundations.projectpythia.org/appendix/how-to-contribute)
and [contributing new Cookbooks](https://projectpythia.org/cookbook-guide).
```

## Overview

Welcome! This is the main guide for contributing to Project Pythia.
Project Pythia is an open community, and all contributions are
welcome following our [Code of
Conduct](https://projectpythia.org/code_of_conduct.html). All
Conduct](https://projectpythia.org/code_of_conduct). All
of the content for Project Pythia is hosted on GitHub in a number
of different public repositories. From this document you can learn
about the many ways that you can contribute to this community
Expand All @@ -37,7 +37,7 @@ forum](https://discourse.pangeo.io/c/education/project-pythia/).
### Add content to the Resource Gallery

The Project [Pythia Resource
Gallery](https://projectpythia.org/resource-gallery.html) contains a
Gallery](https://projectpythia.org/resource-gallery) contains a
collection of links to useful resources that were created and are
hosted outside of Project Pythia. Some examples include: documentation
and tutorials for iconic packages such as Matplotlib, Cartopy, and
Expand Down Expand Up @@ -233,7 +233,7 @@ example, and clicking on the file named `CONTRIBUTING.md`
```

More information on installing and using conda may be found
[here](https://foundations.projectpythia.org/foundations/conda.html).
[here](https://foundations.projectpythia.org/foundations/conda).

### Forking a repo

Expand Down
16 changes: 8 additions & 8 deletions portal/cookbook-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ These instructions assume that your goal is to contribute a new Cookbook to the
Using the Pythia Cookbook template to create reproducible documents housed elsewhere is definitely possible! But we don't focus on that use case in this guide.
```

If you're not looking to create a _new_ Cookbook, but rather looking for guidance on contributing to _existing_ Cookbooks, first make sure you're comfortable with the [GitHub forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows.html#forking-workflow), then take a look at the section below on "Pull Requests and previews".
If you're not looking to create a _new_ Cookbook, but rather looking for guidance on contributing to _existing_ Cookbooks, first make sure you're comfortable with the [GitHub forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows#forking-workflow), then take a look at the section below on "Pull Requests and previews".

## A. Data access and storage considerations for Cookbooks

Expand Down Expand Up @@ -50,7 +50,7 @@ For many concepts, we encourage writing self-contained functions to generate sim

## B. Create a Repository From the Cookbook Template

1. If you don't already have a GitHub account, create one by following the [Getting Started with GitHub guide](https://foundations.projectpythia.org/foundations/getting-started-github.html).
1. If you don't already have a GitHub account, create one by following the [Getting Started with GitHub guide](https://foundations.projectpythia.org/foundations/getting-started-github).
1. On the [Cookbook Template repository](https://github.com/ProjectPythia/cookbook-template), click "Use this template → Create a new repository".
1. Choose "Include all branches".
1. Give your repository a descriptive name followed by `-cookbook` (e.g., `hydrology-cookbook`, `hpc-cookbook`, `cesm-cookbook`) and a description.
Expand All @@ -61,20 +61,20 @@ For many concepts, we encourage writing self-contained functions to generate sim
<img width="901" alt="Screenshot 2023-01-13 at 3 12 47 PM" src="https://user-images.githubusercontent.com/26660300/212428991-cd0ae2f0-73ca-40d8-b983-f122359463aa.png">

```{note}
In the rest of this guide, we assume that you are familiar with the basics of using git and GitHub. If not, we strongly recommend reading through our [GitHub tutorials in Foundations](https://foundations.projectpythia.org/foundations/getting-started-github.html).
In the rest of this guide, we assume that you are familiar with the basics of using git and GitHub. If not, we strongly recommend reading through our [GitHub tutorials in Foundations](https://foundations.projectpythia.org/foundations/getting-started-github.
```

Your cookbook is now ready to have content added!


## C. Set up the Computational Environment

You'll most likely want to do your edits in a [local clone of the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking.html) on your laptop or wherever your are running your notebooks.
You'll most likely want to do your edits in a [local clone of the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking) on your laptop or wherever your are running your notebooks.

### Customizing Your Conda Environment

1. Within `environment.yml` (in the root of the repository), change `name` from `cookbook-dev` to `<your-cookbook-name>-dev` (e.g. `cesm-cookbook-dev`) and add all required libraries and other dependencies under `dependencies:`. Commit the changes.
1. Create the [conda environment](https://foundations.projectpythia.org/foundations/conda.html) with `conda env create -f environment.yml`. If it crashes, try running `conda config --set channel_priority strict`
1. Create the [conda environment](https://foundations.projectpythia.org/foundations/conda) with `conda env create -f environment.yml`. If it crashes, try running `conda config --set channel_priority strict`
1. Activate your environment with `conda activate <env-name>`

You're now ready to create and run awesome notebooks.
Expand Down Expand Up @@ -188,7 +188,7 @@ Also, _don't worry about breaking anything!_ Your repo will not affect any other
1. Select or type "ProjectPythia", confirm, and transfer.
1. When prompted about which teams to give access to, select "core". _This will enable the Pythia maintenance team to have full access to your repository._

Once you have successfully transferred the repository, you'll most likely want to make a [personal fork and a local clone of the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking.html) so that you can continue to develop and collaborate on the Cookbook via the [forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows.html#forking-workflow).
Once you have successfully transferred the repository, you'll most likely want to make a [personal fork and a local clone of the repository](https://foundations.projectpythia.org/foundations/github/github-cloning-forking) so that you can continue to develop and collaborate on the Cookbook via the [forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows#forking-workflow).


## G. Deploying your Cookbook
Expand Down Expand Up @@ -226,11 +226,11 @@ It's possible to enable the workflows on your personal fork, but usually unneces

### Pull Requests and previews

Collaboration on Cookbooks is best done via [Pull Requests](https://foundations.projectpythia.org/foundations/github/github-pull-request.html). Every PR on a Cookbook repository will trigger a "Preview" version of our publishing pipeline. The entire book is re-built from the updated source and the preview site is hosted at a temporary online location. This way, the team can safely see what the end product will look like after the PR is merged.
Collaboration on Cookbooks is best done via [Pull Requests](https://foundations.projectpythia.org/foundations/github/github-pull-request). Every PR on a Cookbook repository will trigger a "Preview" version of our publishing pipeline. The entire book is re-built from the updated source and the preview site is hosted at a temporary online location. This way, the team can safely see what the end product will look like after the PR is merged.

The only difference between the "preview" pipeline and the regular publishing pipeline is the URL to which the rendered website is deployed. A temporary preview location is used, leaving the main book untouched until the PR is merged.

To propose changes to a Cookbook, or even just to test something out temporarily, follow the [forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows.html#forking-workflow): make changes on a feature branch of your personal fork, and open a Pull Request from that branch to the main branch of the upstream fork. This will trigger the preview.
To propose changes to a Cookbook, or even just to test something out temporarily, follow the [forking workflow](https://foundations.projectpythia.org/foundations/github/github-workflows#forking-workflow): make changes on a feature branch of your personal fork, and open a Pull Request from that branch to the main branch of the upstream fork. This will trigger the preview.

A link to the preview will appear as a comment on the Pull Request once the publishing actions are complete. _If the link shows up but you get a 404 error when you click on it the first time, just wait a few minutes! There are some lags before the preview is fully deployed._

Expand Down
6 changes: 3 additions & 3 deletions portal/cookbook-tasklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Once we've marked this entire checklist, [click here to open an issue on Project

---

- [ ] **Confirm you’ve followed the entire Project Pythia [Cookbook Guide](https://projectpythia.org/cookbook-guide.html)**.
Take note especially of the [Develop your cookbook](https://projectpythia.org/cookbook-guide.html#develop-your-cookbook), [Authorship and the CITATION.cff file](https://projectpythia.org/cookbook-guide.html#authorship-and-the-citation-cff-file), and [Gallery tags](https://projectpythia.org/cookbook-guide.html#gallery-tags) sections. **Save the [Generate a DOI](https://projectpythia.org/cookbook-guide.html#generate-a-doi) step as the last step of this checklist.**
- [ ] **Confirm you’ve followed the entire Project Pythia [Cookbook Guide](https://projectpythia.org/cookbook-guide)**.
Take note especially of the [Develop your cookbook](https://projectpythia.org/cookbook-guide/#d-develop-your-cookbook), [Authorship and the CITATION.cff file](https://projectpythia.org/cookbook-guide/#e-making-your-cookbook-findable-and-citable), and [Gallery tags](https://projectpythia.org/cookbook-guide/#id-2-tag-your-cookbook) sections. **Save the [Generate a DOI](https://projectpythia.org/cookbook-guide#generate-a-doi) step as the last step of this checklist.**
- [ ] **Confirm that the individual notebooks within your Cookbook adhere to the [notebook template](https://github.com/ProjectPythia/cookbook-template/blob/main/notebooks/notebook-template.ipynb)**.
If the template does not fit your Cookbook’s needs, that’s fine too! Simply let us know here in this issue.
- [ ] **Finalize your Cookbook repository name.**
Expand Down Expand Up @@ -42,7 +42,7 @@ This can be seen in individual Pull Requests as green checkmarks ✅ for importa
- [ ] **Identify a Maintainer team via GitHub handle(s) in this thread.**
This can be one or more people with availability to check in on this Cookbook, issue fixes to broken content, or with a vision for the future development of the Cookbook. This is typically (but not necessarily) one of the primary authors of the Cookbook.
- [ ] **Link your Cookbook repo to Zenodo for DOI generation**
Follow steps 1-4 under [Generate a DOI](https://projectpythia.org/cookbook-guide.html#generate-a-doi) in the Cookbook Guide. Return here for instructions on step 5, and your final step:
Follow steps 1-4 under [Generate a DOI](https://projectpythia.org/cookbook-guide/#id-1-credit-yourself) in the Cookbook Guide. Return here for instructions on step 5, and your final step:
- [ ] **Release your Cookbook!**
- On the right-hand sidebar for your Cookbook repository, click “Create a new release”. If you don’t see this button, you may need to click on the “Releases” header first and “Create” or “Draft” a new release.
![GitHub Repository sidebar section titled "Releases"](https://raw.github.com/ProjectPythia/projectpythia.github.io/main/portal/_static/images/4-releases.png "Releases")
Expand Down
2 changes: 1 addition & 1 deletion portal/posts/2025/new-cookbooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -204,4 +204,4 @@ This Cookbook covers how to work with wavelets in Python. Wavelets are a powerfu

Do you have some feedback or ideaa for a new Cookbook project? Unsure how to get started? We'd love to hear from you at any of our [open meetings](https://projectpythia.org/#monthly-pythia-meetings), through the [Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/), or via any of our social media. Join us at our next Cook-off 2025!

Take a look at our [guide for Cookbook contributors](https://projectpythia.org/cookbook-guide.html).
Take a look at our [guide for Cookbook contributors](https://projectpythia.org/cookbook-guide).
2 changes: 1 addition & 1 deletion portal/quick-cookbook-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ This document is designed be lightweight. For more detailed, step-by-step instuc

## Update Content

Follow [Git/GitHub best practices](https://foundations.projectpythia.org/foundations/getting-started-github.html) with your collaborators:
Follow [Git/GitHub best practices](https://foundations.projectpythia.org/foundations/getting-started-github) with your collaborators:

- Add content with your scientific insight as `.ipynb` files in the `notebooks/` folder
- Update `environment.yml` to include all necessary packages
Expand Down