+ + ← Back to Quickstart Guide + +
+ Project Pythia Cookbooks are collections of more advanced and domain-specific example -workflows building on top of [Pythia Foundations](https://foundations.projectpythia.org/landing-page.html). +workflows building on top of [Pythia Foundations](https://foundations.projectpythia.org/). They are [geoscience](https://en.wikipedia.org/wiki/Earth_science)-focused and should direct the reader towards the Foundations material for any required background knowledge. @@ -18,7 +24,7 @@ Using the Pythia Cookbook template to create reproducible documents housed elsew 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". -## Data access +## A. Data Access Before developing your cookbook, you should consider how it will access the data you plan to use. In loose order of preference, we recommend the following: @@ -27,62 +33,30 @@ Before developing your cookbook, you should consider how it will access the data 1. Discuss your larger data storage needs with the Pythia team. We are currently experimenting with cloud object storage for Cookbooks via NSF JetStream2. 1. Provide the tools and/or clear documentation for accessing the data that you have stored somewhere else -## Use the template +## 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. On the [Cookbook Template repository](https://github.com/ProjectPythia/cookbook-template), click "Use this template → Create a new repository" +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. 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 -1. Create the repository. Your browser will be directed to the newly created repository under your GitHub account -1. Under Settings → Pages, ensure that GitHub Pages is enabled by checking that `Branch` is set to "gh-pages", and the folder set to "gh-pages/(root)". If it is not, change the Branch from "None" to "gh-pages/(root)" and click "Save" -1. Under Settings → Actions → General, make sure that "Read and write permissions" is selected.
+1. Give your repository a descriptive name followed by `-cookbook` (e.g., `hydrology-cookbook`, `hpc-cookbook`, `cesm-cookbook`) and a description.
+1. Create the repository. Your browser will be directed to the newly created repository under your GitHub account.
+1. Under Settings → Pages, ensure that GitHub Pages is enabled by checking that `Branch` is set to "gh-pages", and the folder set to "gh-pages/(root)". If it is not, change the Branch from "None" to "gh-pages/(root)" and click "Save".
+1. Under Settings → Actions → General, make sure that "Read and write permissions" is selected.
-Your cookbook is now ready to have content added!
+
```{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).
```
-## Transfer your cookbook repo to the ProjectPythia organization
-
-In order for your Cookbook to be included in the Gallery, the source repository needs to be housed within the [Project Pythia GitHub organization](https://github.com/ProjectPythia).
-
-You can keep your repository in your personal GitHub space while you're developing your content if that works better for you. Repository ownership can be transferred at any time.
-
-However, we recommend transferring to the Pythia organization early, for a few reasons:
-- Fewer settings to tweak later
-- Easier to get help from the Pythia infrastructure team
-- Encourages collaboration
-
-```{note}
-You're still in control! You will always retain write access to your Cookbook repository even after transfering ownership to the Pythia organization.
-
-Also, _don't worry about breaking anything!_ Your repo will not affect any other Project Pythia content until you initiate the request to list it on the [Cookbook Gallery](https://cookbooks.projectpythia.org) (see below...)
-```
-
-### Steps to transfer the repository
-
-1. [Contact the Pythia team via the Pangeo Discourse](https://discourse.pangeo.io/c/education/project-pythia/60) (or otherwise) to let us know about your cookbook.
-1. You will get an invitation to join the [ProjectPythia organization](https://github.com/ProjectPythia).
-1. Accept the GitHub invitation. _Welcome to the team!_
-1. Once you are a member of the organization, navigate to the Settings of your cookbook repository and scroll down to the **Danger Zone**.
-1. Click "Transfer".
-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).
-
-## Customize the paths in your repository
-
-Whether the repository lives in your personal GitHub space or on the ProjectPythia organization, there are several paths and links in the repository code that need to be updated to reflect the current home of your cookbook source. This step is necessary to ensure that the cookbook building and publishing infrastructure works as intended.
+Your cookbook is now ready to have content added!
-Fortunately this is quick and easy. Just run our custom GitHub action called `trigger-replace-links`: Navigate to "Actions" → "trigger-replace-links" → "Run workflow".
-## Set up the computational environment
+## 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.
-### Customizing your environment file
+### Customizing Your Conda Environment
1. Within `environment.yml` (in the root of the repository), change `name` from `cookbook-dev` to `+ + Full Cookbook Contributor's Guide → + +
+ + +--- +## Create Repository Using Template + +1. Navigate to [projectpythia/cookbook-template](https://github.com/projectpythia/cookbook-template) +2. Click **"Use This Template"** → **"Create a new repository"** + +### On the next page: +- Check **"Include all branches"** +- You are the **owner** +- Create your repository name (should end with `-cookbook`) +- Select to keep it **Public** +- Then click **"Create repository"** + + +--- + +## Update Content + +Follow [Git/GitHub best practices](https://foundations.projectpythia.org/foundations/getting-started-github.html) with your collaborators: + +- Add content with your scientific insight as `.ipynb` files in the `notebooks/` folder +- Update `environment.yml` to include all necessary packages +- Update your **thumbnail** to visually represent your work +- Update `README.md` to reflect: + - Title + - Description + - Motivation + - Authors + - Content structure + +- Update `myst.yml` with: + - Title + - GitHub link + - Table of contents (`toc`) + - Jupyter → Binder → Repo links + +- Update `CITATION.cff` with: + - Authors’ names, ORCID, website, and affiliation + - Title + - Abstract + +- Update `_gallery_info.yml` with: + - "packages" and "domains" tags + - the correct filepath for your thumbnail + +--- + +## Ready to Publish? + +1. Make sure you’re added to the `ProjectPythia` organization +2. From **repository settings**, transfer the repo to the `ProjectPythia` organization +3. Open a PR editing `cookbook_gallery.txt` with your repo name in the [Cookbook Gallery Repository](https://github.com/projectpythia/cookbook-gallery) +4. Await review +5. Someone from the Pythia team will publish a **citable release** From 54560e106d20c561ef99632e2946f8c55771b3c6 Mon Sep 17 00:00:00 2001 From: Julia Kent <46687291+jukent@users.noreply.github.com> Date: Thu, 26 Jun 2025 11:53:54 -0600 Subject: [PATCH 2/4] active language --- CONTRIBUTING.md | 5 ++--- myst.yml | 2 +- ...pythia-contributing.md => contributing.md} | 21 +++++++++---------- 3 files changed, 13 insertions(+), 15 deletions(-) rename portal/{pythia-contributing.md => contributing.md} (96%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4f5981b0..7d3ed1427 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,7 @@ -# Pythia Portal contributor's guide +# Contributing to the Project Pythia Portal This document contains information specific to contributing to the -Project Pythia Portal. Please first refer to [Pythia Contributor's -Guide](https://projectpythia.org/pythia-contributing.html) for overall +Project Pythia Portal. Please first refer to [Guide for Contributing to Project Pythia](https://projectpythia.org/contributing.html) for overall contribution guidelines (such as detailed description of Project Pythia structure, forking, repository cloning, branching, etc.). diff --git a/myst.yml b/myst.yml index 5f3be0c64..79c700bcd 100644 --- a/myst.yml +++ b/myst.yml @@ -17,7 +17,7 @@ project: - title: Blog children: - pattern: portal/posts/*.md - - file: portal/pythia-contributing.md + - file: portal/contributing.md - file: portal/cookbook-guide.md - file: portal/quick-cookbook-guide.md - file: portal/metrics.md diff --git a/portal/pythia-contributing.md b/portal/contributing.md similarity index 96% rename from portal/pythia-contributing.md rename to portal/contributing.md index 09a0baf51..1cffc928a 100644 --- a/portal/pythia-contributing.md +++ b/portal/contributing.md @@ -1,4 +1,4 @@ -# Project Pythia Contributor's Guide +# Contributing to Project Pythia ```{note} This the top-level guide for Project Pythia and a great starting point for getting involved! @@ -10,7 +10,7 @@ and [contributing new Cookbooks](https://projectpythia.org/cookbook-guide.html). ## Overview -Welcome! This is the main contributors guide for Project Pythia. +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 @@ -18,8 +18,7 @@ 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 project, and where you can find additional information. In many -cases pertinent details may be found in repository-specific -contributors guides **that should always be consulted in addition +cases pertinent details may be found in repository-specific guides **that should always be consulted in addition to this guide**. More on this topic later. ## The many ways to contribute @@ -72,7 +71,7 @@ is a collection of material that the Pythia team believes is essential knowledge for geoscientists to effectively use the Scientific Python Ecosystem. The Pythia Foundations content is hosted on a separate [GitHub repo](https://github.com/ProjectPythia/pythia-foundations), -and contributors should consult the contributor’s guide there for +and contributors should consult the [Contributing to Foundations](https://foundations.projectpythia.org/appendix/how-to-contribute) guide there for information specific to Foundations. However, adding new, or changing existing Foundations content requires contributors to be familiar with a few technologies and workflows, described in Advanced @@ -88,7 +87,7 @@ specific problem. Typically, a cookbook references material presented elsewhere in Project Pythia, such as [Pythia Foundations](https://foundations.projectpythia.org). Each Cookbook is hosted in a separate GitHub repo under the umbrella [Project Pythia organization](https://github.com/ProjectPythia). -Contributors should consult the [Cookbook-specific Contributor's guide](/cookbook-guide). +Contributors should consult the [Contributing a New Cookbook](/cookbook-guide) guide. ### Pythia Portal @@ -114,10 +113,10 @@ process of setting up GitHub/Git, installing and configuring conda, and submitting a PR. Note, while this information is common to all Pythia repositories, repo-specific information might be required. -In all cases contributors should consult the repo-specific contributor’s +In all cases contributors should consult the repo-specific contribution guide for their target repository. -Repo-specific guides can be found in the file named `CONTRIBUTING.md`, located in the top level directory of each repository, or by clicking on the menu item labeled “Contributor’s Guide” found in the rendered content generated by each repository. +Repo-specific guides can be found in the file named `CONTRIBUTING.md`, located in the top level directory of most repositories, or by clicking on the appropriately named menu item on each site. Note that the "Contributing a new Cookbook" guide is found in the Pythia portal (rather than in any one specific Cookbook). Lastly, much of this information has been co-opted from the [GeoCAT project](https://geocat.ucar.edu). @@ -221,12 +220,12 @@ desktop or laptop. Before using your conda environment to work on Pythia content, you'll need to perform an addtional one-time setup that is specific to each Pythia repo. After the one-time configuration is complete you will need to "activate" a repo-specific environment whenever -you wish to use it. Consult the repo-specific contributor’s guide +you wish to use it. Consult the repo-specific contribution guide for information on “Building the site”, and follow the steps described therein. ```{note} -Repository-specific contributor's +Repository-specific contribution information can always be accessed by navigating your web browser to the appropriate Project Pythia GitHub repository, [here](https://github.com/ProjectPythia/pythia-foundations) for @@ -337,7 +336,7 @@ back to the Pythia repository you will need to submit a Pull Request ### Make your local changes At this point you should be able to make your desired changes to -the local copies of your files. **Always consult the repo-specific contributor’s +the local copies of your files. **Always consult the repo-specific contribution guide for information specific to the repo you are working on.** ### Submit a Pull Request (PR) From 7d2f8cc610d64baeda8abe9e5774b426d8bee33c Mon Sep 17 00:00:00 2001 From: Julia Kent <46687291+jukent@users.noreply.github.com> Date: Thu, 26 Jun 2025 12:05:19 -0600 Subject: [PATCH 3/4] active language --- portal/quick-cookbook-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/portal/quick-cookbook-guide.md b/portal/quick-cookbook-guide.md index af159f477..3401f43c3 100644 --- a/portal/quick-cookbook-guide.md +++ b/portal/quick-cookbook-guide.md @@ -1,9 +1,9 @@ -# Quick Cookbook Contributing Guide +# Quick Guide to Contributing a New Cookbook -For a more detailed, step-by-step contributor guide, see the **Full Cookbook Contributor's Guide** +This document is designed be lightweight. For more detailed, step-by-step instuctions, see the **Full Guide for Cookbook Guide**- Full Cookbook Contributor's Guide → + Contributing a New Cookbook →
From 503767cc20966b532e6eb948e35be324953f1d11 Mon Sep 17 00:00:00 2001 From: Julia Kent <46687291+jukent@users.noreply.github.com> Date: Thu, 26 Jun 2025 12:07:40 -0600 Subject: [PATCH 4/4] zenodo admin --- portal/cookbook-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/portal/cookbook-guide.md b/portal/cookbook-guide.md index 75f30a992..86422c88d 100644 --- a/portal/cookbook-guide.md +++ b/portal/cookbook-guide.md @@ -1,4 +1,4 @@ -# Cookbook Contributor's Guide +# Contributing a New Cookbook