Cookbook: review & update Contributing section

[stefaniebutland]

Review and update Contributing section.

Minimize duplication. Where possible, point to Approach Guide or Quarto website tutorial when info applies across multiple areas.

Notes from discussion w Julie Jun 22:

• Focus on the technical
• Are screenshots up to date? Things inright order?
• Note that Ziheng didn’t know how to contribute a notebook till he saw the Workflow section
• Where should it say “edit the _quarto.yml” to make it appear in nav bar
• First it should say “here’s how to contribute” - make it clear that anyone can contribute - here’s how, then Cookbook setup, Workflow; move Mentors lower
• Setup - is this the right order?
• Workflow - update Quarto intro text
• Do not worry about scope of cookbook - what we want and what we don’t want. This will come after retreat - come from the Mentors. Can add a section “Scope of cookbook - coming soon”

Audience:

Primary audience is NASA Mentors. This is why the Onboarding Mentors chapter currently comes first. This can be moved.

Write as if showing one of them and it will work for others too. People wondering how do I recall how to make a PR; someone who needs to learn GitHub now; needs a refresher; someone who has never used GitHub, Quarto, Hub…

Checklist

This list will be edited as tasks are defined.

First add:

• How to contribute a chapter
  • sparked by Ziheng Sun’s question:

  • is there a contributing guide we can follow to contribute notebooks to the tutorials? I am reading https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/ but it seems there is no clean path to follow. Came across this chapter which is hidden from the main page https://nasa-openscapes.github.io/earthdata-cloud-cookbook/contributing/workflow.html. I think it would help if there is a sentence in the contributing page like "Please click [Onboarding Members](link) to get started!"

  • Solution: add as level 2 header in Workflow, after Cookbook Practices, before Notebook Review
• How to review and merge a PR
  • combine with / edit Notebook Review
• Intro: don't add explicit TOC, but note folks can find How to contribute a chapter and How to review and merge a PR
• Point to Makhan’s tutorial setup with screenshots. Step 1. Login to the Hub is most helpful.
• Point to Julie’s video in Cookbook Setup: Part 3:2i2c JupyterHub (video) introduces a beginning GitHub workflow from our 2i2c JupyterHub.
• Do we already have “how to edit this page, click here to fix typo”?

Then:

• Add some orientation to intro of Contributing - teaches you the technical and social decision making/ philosophy.

• Workflow intro text - Prob can leave it for now. Julie’s good with the headings

• Maybe delete Virtual Envts
  This popout - Summary of GitHub and Quarto commands detailed below - is really good when quickly finding a command

• Notebook Review

  • Check what’s there -> Review with .qmds was Julie being opinionated. Either leave it….or …not?
  • The git button in JupyterHub is newish thanks to Eli; before then it was all cmd line. Julie wrote the above before the button was there

[stefaniebutland]

Contributing text written for perspective of a NASA Openscapes Mentor accessing Cookbook in Openscapes 2i2c JupyterHub

Assumptions

• review of pull request is required for merging

Questions

• can/should someone push to main to fix a typo or do they use pull request workflow?

The Doing

• What do I need to get started? This is in Cookbook Setup
  • GitHub and JupyterHub logins
  • info on how book is made e.g. Quarto
• How do I fix a typo?
  • work in GitHub browser, edit file, commit to a new branch, make pull request, (how/who to tag someone to review?)
• How do I edit a chapter?
  • work locally, in a branch, edit file, render to preview, commit
  • make pull request, get a review
• How do I add a new chapter?
  • level 2 header in Workflow, after Cookbook Practices, before Notebook Review
  • define chapter cause just adding a subsection doesn't require editing _quarto.yml
  • work locally, in a branch, create new chapter file, edit, render to preview, edit _quarto.yml to indicate where chapter will appear in nav bar, render to preview
  • make pull request, get a review
• How do I review and merge a pull request?
  • combine with / edit Notebook Review
  • 🤔 see Workflow: GitHub Workflow: Pull Request; seems like it goes there
  • I think we have videos for this: Julie & Cassie?, Stef & Julie

[stefaniebutland]

python with Quarto.

• Watch Reproducible Publications with Python and Quarto (Thomas Mock) (video 57min)
• read https://quarto.org/docs/get-started/hello/jupyter.html

[stefaniebutland]

• Define & explain how to differentiate what goes in /examples /external /tutorials folders

[stefaniebutland]

Documenting how to add a chapter or notebook

Got a little comfortable working in the Hub.

Figured out some first-principles: how to use the 2i2c Openscapes JupyterHub to clone Cookbook to my own "local" instead of inside shared folder, used guidance from Posit's Tutorial: Hello, Quarto with Jupyter and their hello.ipynb.

• created branch stef-learn
• uploaded hello.ipynb to external
• tested quarto render: output created .../site/external/hello.html but didn't look for the file
• tested quarto preview: clicked preview https URL and Cookbook opened
• edited _quarto.yml to have my hello.ipynb appear in nav bar under tutorials
• preview in browser automatically updated and hello appeared in nav bar
• discarded my changes and deleted my stef-learn branch (all in Hub)

Next steps

• figure out how to get better default resolution in screenshots (mine are 72x72 in Preview and don't look crisp)
• write first draft Contributing instructions for Adding a Section using hello.ipynb in the Hub
  • point to robust external resources when possible (Tutorial: Hello, Quarto with Jupyter was mostly helpful to me for basics, whereas How to Add a Chapter should cut to the chase and point elsewhere for basic info
  • JupyterHub screenshots for orientation and full GitHub instructions are great here: https://nasa-openscapes.github.io/2021-Cloud-Hackathon/tutorials/00_Setup.html#step-3.-jupyterhub-orientation
• record myself doing this (other people's videos have really helped me)

[stefaniebutland]

Issues have been opened in the Cookbook repo, in the NASA-Openscapes org: https://github.com/NASA-Openscapes/earthdata-cloud-cookbook/issues. Tracking in new project Cookbook Contributing