Skip to content

Commit 6f079fd

Browse files
committed
Add more guidance on PRs and previews
1 parent cdc271c commit 6f079fd

File tree

1 file changed

+6
-2
lines changed

1 file changed

+6
-2
lines changed

portal/cookbook-guide.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ These instructions assume that your goal is to contribute a new Cookbook to the
1616
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.
1717
```
1818

19+
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".
20+
1921
## Data access
2022

2123
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:
@@ -167,7 +169,7 @@ The link to your published book will then be displayed on the home page of the r
167169
```{Note}
168170
If you have transfered your repository to the ProjectPythia organization and also made a personal fork, the publishing pipeline automation will _only run on the upstream fork on the ProjectPythia organization_ so there's only one copy of the "published" book.
169171
170-
It's possible to enable the workflows on your personal fork, but usually unneccesary if you preview your work via Pull Requests (see below).
172+
It's possible to enable the workflows on your personal fork, but usually unneccesary if you preview your work via Pull Requests (see next section)!
171173
```
172174

173175
### Pull Requests and previews
@@ -176,9 +178,11 @@ Collaboration on Cookbooks is best done via [Pull Requests](https://foundations.
176178

177179
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.
178180

181+
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.
182+
179183
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._
180184

181-
Every new push to the PR branch will trigger another rebuild, and an updated preview. The preview will be deleted if and when the PR is closed or merged.
185+
Not satisfied? Keep making changes! Every new push to the feature branch on your personal fork will trigger another rebuild, and an updated preview. The preview will be deleted if and when the PR is closed or merged.
182186

183187
### Building on the Pythia Binder
184188

0 commit comments

Comments
 (0)