Now that we have each saved some changes to files in our Quarto site source, liike .qmd, .ipynb, and/or _quarto.yml, we can contribute our updates using GitHub.
-
-
Demonstration
+
Now that we have each saved some changes to files in our Quarto site source, we can contribute our updates using GitHub.
+
We will demonstrate this and then you will do this in breakout rooms.
+
+
Author stages, commits, and pushes file
You have to deliberately tell Git/GitHub when you have work that you want to be versioned and synced. First, inspect the differences your edits will introduce.
-
+
-
In the Git tab “stage” your saved changes.
+
In the Git tab “stage” your saved changes. There may be a .json file that you also stage; this is part of the Quarto build process.
@@ -234,15 +244,10 @@
Demonstration
Commit your edits with a good commit message and push your edits to GitHub. A commit message is a human-readable message, like leaving a breadcrumb trail for your future self and others.
-
-
-
-Commit and Push
-
-
+
When you push by clicking the push icon (with the orange dot since we have committed files to push), you may be prompted to enter your git credentials.
-
-
Set up our Git credentials
+
+
Aside: set up our Git credentials
On your first commit, you will be prompted to add your Git credentials. When you are working on a project over time, you can have them stored, following instructions in Configure Git (git config) from the 2021 Cloud Hackathon.
TODO: do we need to do Step 5.1. Configure Git (git config)? (but ignore the push file part). Clarify the following text to say see the orange dot. click it to be prompted
When you see the following screenshot, GitHub is asking for you to input your credentials. (Note: you see this screenshot when you have committed work to push to GitHub.com. In this case we have created a new branch in the Hub and it does not yet exist on GitHub.
Our current status is that in the Hub, in our own branch of the Quarto Clinic repo, we have made one or more edits to the Clinic files, committed those updates, and pushed those commit(s) to GitHub. How do our suggested contributions get incorporated into the main Quarto Clinic repo and website? Via a Pull Request.
-
After pushing your edits, go to https://github.com/Openscapes/quarto-clinic/ and you will see a yellow banner inviting you to make a Pull Request to add your edits to the Clinic repo.
Not finished proposing your updates? You can set your Pull Request as a Draft at the start so folks can see your thinking. Set Ready for Review when ready and request a reviewer(s). For the NASA Earthdata Cloud Cookbook, any Pull Request must be reviewed before it can be merged. If you know someone who is familiar with the content you’re proposing to add, request their review.
+
+
+
+First view of a Pull Request.
+
+
-
-
Review a pull request
+
+
Reviewer reviews the Pull Request
+
TODO:
From the pull request page in GitHub browser, look at the elements of the pull request.
-
Start with Conversation tab:
+
Start with Conversation tab:
We can see all commits and comments on what Andy has worked on
This is where we can add PR reviewers by clicking the gear icon next to “Reviewers” at the top right corner of this tab.
-
Commit tab:
+
Commit tab:
More details on the commits that we saw under Conversation. When we click on one of the commits, we can see line by line what has changed under that commit (green lines are added, red lines have been removed)
-
Files Changed tab:
+
Files Changed tab:
View all the files that changed across the commits
In Nav bar: Orange dot box signifies modified; Green plus box means something’s been added; Red minus box means deleted; Grey arrow box means renamed.
-
Checks tab:
+
Checks tab:
Shows status of the Github Action that renders and deploys the site. We can know whether this Pull Request is able to be deployed.
-
Now, switch to the 2i2c Hub to view the Cookbook preview as it would appear if the pull request was merged:
+
Now, switch to the 2i2c Hub to view the Clinic preview as it would appear if the pull request was merged:
Terminal:
@@ -306,21 +318,52 @@
Review a pull reques
Review each individual file that has changed and come back to the main _quarto.yml if we see an issue with the navigation.
Once our review is complete, we add a note in the GitHub review box and click “Approve”, “Comment” or “Request changes”. In the note it can be really helpful to add a note of appreciation for some aspect of the contribution, tagging the author, saying they can merge the PR after making changes, and possibly add a summary of our requested edits including the number of changes requested. Some changes in the middle of a long list of edits can be marked as hidden conversations, so this can be helpful to the author to know they’ve seen everything.
-
-
Merge your Pull Request
+
+
Author merges Pull Request
As the author, you can now address the reviewer’s comments and then merge your Pull Request.
-
-
Try it out!
+
+
+
Your turn - Breakout rooms
Pair up in breakouts to make and review each other’s Pull Requests
+
We’ve done this demonstration - now you’ll go into breakout rooms. One of you be the Author role, and one the Reviewer role, with each of you screensharing where you are playing your role. Help each other out! If there is time, please switch roles
Good practices to tidy your workspace & save unneccessary storage costs:
+
From GitHub Browser: - Delete branch on GitHub Browser
+
From JupyterHub: - Delete stefanie branch from the Git plugin - Delete quarto-clinic folder from terminal cd .. then rm -rf quarto clinic - Shut down Hub from File menu
-
-
View your updates in the live site (Regroup, 10 min)
Regroup discussion topics
-
Short message: commit the freeze folder.
+
+
Deleting branches
+
+
+
Code & rendering .qmd files
+
You can add code TODO
+
When you Render, a document will be generated that includes both content and the output of embedded code. You can embed code like this:
+
TODO: day before clinic, make this Python code (don’t add screenshot - fewer files to for folks to get distracted with, lighter weight repo)
+
You can add options to executable code. The echo: false option disables the printing of code (only output is displayed).
+
+
+
Freeze
+
Commit the freeze folder.
Freeze directory contains the results of code execution.
Commit the freeze directory after you run quarto preview.
@@ -328,6 +371,7 @@
Regroup discussi
+
diff --git a/search.json b/search.json
index c13285a..8621283 100644
--- a/search.json
+++ b/search.json
@@ -114,17 +114,27 @@
"href": "part2-github.html#contribute-your-updates-using-github",
"title": "Part 2: GitHub workflow",
"section": "Contribute your updates using GitHub",
- "text": "Contribute your updates using GitHub\nNow that we have each saved some changes to files in our Quarto site source, liike .qmd, .ipynb, and/or _quarto.yml, we can contribute our updates using GitHub.\n\nDemonstration\nYou have to deliberately tell Git/GitHub when you have work that you want to be versioned and synced. First, inspect the differences your edits will introduce.\n\n\n\n\n\nIn the Git tab “stage” your saved changes.\n\n\n\nStage your changes\n\n\nCommit your edits with a good commit message and push your edits to GitHub. A commit message is a human-readable message, like leaving a breadcrumb trail for your future self and others.\n\n\n\nCommit and Push\n\n\n\n\nSet up our Git credentials\nOn your first commit, you will be prompted to add your Git credentials. When you are working on a project over time, you can have them stored, following instructions in Configure Git (git config) from the 2021 Cloud Hackathon.\nTODO: do we need to do Step 5.1. Configure Git (git config)? (but ignore the push file part). Clarify the following text to say see the orange dot. click it to be prompted\nWhen you see the following screenshot, GitHub is asking for you to input your credentials. (Note: you see this screenshot when you have committed work to push to GitHub.com. In this case we have created a new branch in the Hub and it does not yet exist on GitHub.\n\n\n\nPrompt to add your Git credentials\n\n\nWe’ll follow the instructions in the 2021 Cloud Hackathon to Setup your Personal Access Token (PAT).\n\n\nMake a Pull Request\nOur current status is that in the Hub, in our own branch of the Quarto Clinic repo, we have made one or more edits to the Clinic files, committed those updates, and pushed those commit(s) to GitHub. How do our suggested contributions get incorporated into the main Quarto Clinic repo and website? Via a Pull Request.\nAfter pushing your edits, go to https://github.com/Openscapes/quarto-clinic/ and you will see a yellow banner inviting you to make a Pull Request to add your edits to the Clinic repo.\n\n\n\n\n\nNot finished proposing your updates? You can set your Pull Request as a Draft at the start so folks can see your thinking. Set Ready for Review when ready and request a reviewer(s). For the NASA Earthdata Cloud Cookbook, any Pull Request must be reviewed before it can be merged. If you know someone who is familiar with the content you’re proposing to add, request their review.\n\n\nReview a pull request\nFrom the pull request page in GitHub browser, look at the elements of the pull request.\n\n\nStart with Conversation tab:\n\nWe can see all commits and comments on what Andy has worked on\nThis is where we can add PR reviewers by clicking the gear icon next to “Reviewers” at the top right corner of this tab.\n\nCommit tab:\n\nMore details on the commits that we saw under Conversation. When we click on one of the commits, we can see line by line what has changed under that commit (green lines are added, red lines have been removed)\n\nFiles Changed tab:\n\nView all the files that changed across the commits\nIn Nav bar: Orange dot box signifies modified; Green plus box means something’s been added; Red minus box means deleted; Grey arrow box means renamed.\n\nChecks tab:\n\nShows status of the Github Action that renders and deploys the site. We can know whether this Pull Request is able to be deployed.\n\n\nNow, switch to the 2i2c Hub to view the Cookbook preview as it would appear if the pull request was merged:\n\nTerminal:\n\nGo to the Main branch and pull so that we have the most recent changes from remote.\ngit checkout to the branch that has the Pull Request\nquarto preview - this will build the book with the author’s suggested edits.\n\n\nIn reviewing a pull request with lots of changes, it can be helpful to have windows open to view both the GitHub browser and the 2i2c Hub showing the Clinic site preview.\n\nIn GitHub under the “Files changed” tab of the PR, we can add a suggested edit by clicking the “plus” button below the line in question. Suggesting specific commits can speed the contributor’s workflow compared with trying to describe what we’d like them to change.\nWe can click “Start a review” button so the author gets a single email when we’re done reviewing, rather than getting one notification for every edit we suggest.\n\nReview each individual file that has changed and come back to the main _quarto.yml if we see an issue with the navigation.\nOnce our review is complete, we add a note in the GitHub review box and click “Approve”, “Comment” or “Request changes”. In the note it can be really helpful to add a note of appreciation for some aspect of the contribution, tagging the author, saying they can merge the PR after making changes, and possibly add a summary of our requested edits including the number of changes requested. Some changes in the middle of a long list of edits can be marked as hidden conversations, so this can be helpful to the author to know they’ve seen everything.\n\n\nMerge your Pull Request\nAs the author, you can now address the reviewer’s comments and then merge your Pull Request.\n\n\nTry it out!\nPair up in breakouts to make and review each other’s Pull Requests",
+ "text": "Contribute your updates using GitHub\nNow that we have each saved some changes to files in our Quarto site source, we can contribute our updates using GitHub.\nWe will demonstrate this and then you will do this in breakout rooms.\n\nAuthor stages, commits, and pushes file\nYou have to deliberately tell Git/GitHub when you have work that you want to be versioned and synced. First, inspect the differences your edits will introduce.\n\n\n\n\n\nIn the Git tab “stage” your saved changes. There may be a .json file that you also stage; this is part of the Quarto build process.\n\n\n\nStage your changes\n\n\nCommit your edits with a good commit message and push your edits to GitHub. A commit message is a human-readable message, like leaving a breadcrumb trail for your future self and others.\n When you push by clicking the push icon (with the orange dot since we have committed files to push), you may be prompted to enter your git credentials.\n\n\nAside: set up our Git credentials\nOn your first commit, you will be prompted to add your Git credentials. When you are working on a project over time, you can have them stored, following instructions in Configure Git (git config) from the 2021 Cloud Hackathon.\nTODO: do we need to do Step 5.1. Configure Git (git config)? (but ignore the push file part). Clarify the following text to say see the orange dot. click it to be prompted\nWhen you see the following screenshot, GitHub is asking for you to input your credentials. (Note: you see this screenshot when you have committed work to push to GitHub.com. In this case we have created a new branch in the Hub and it does not yet exist on GitHub.\n\n\n\nPrompt to add your Git credentials\n\n\nWe’ll follow the instructions in the 2021 Cloud Hackathon to Setup your Personal Access Token (PAT).\n\n\nAuthor makes a Pull Request\nOur current status is that in the Hub, in our own branch of the Quarto Clinic repo, we have made one or more edits to the Clinic files, committed those updates, and pushed those commit(s) to GitHub. How do our suggested contributions get incorporated into the main Quarto Clinic repo and website? Via a Pull Request.\nNow we’ll go to https://github.com/Openscapes/quarto-clinic/ and you will see a yellow banner inviting you to make a Pull Request to add your edits to the Clinic repo.\n\n\n\n\n\nNot finished proposing your updates? You can set your Pull Request as a Draft at the start so folks can see your thinking. Set Ready for Review when ready and request a reviewer(s). For the NASA Earthdata Cloud Cookbook, any Pull Request must be reviewed before it can be merged. If you know someone who is familiar with the content you’re proposing to add, request their review.\n\n\n\nFirst view of a Pull Request.\n\n\n\n\nReviewer reviews the Pull Request\nTODO:\nFrom the pull request page in GitHub browser, look at the elements of the pull request.\n\n\nStart with Conversation tab:\n\nWe can see all commits and comments on what Andy has worked on\nThis is where we can add PR reviewers by clicking the gear icon next to “Reviewers” at the top right corner of this tab.\n\nCommit tab:\n\nMore details on the commits that we saw under Conversation. When we click on one of the commits, we can see line by line what has changed under that commit (green lines are added, red lines have been removed)\n\nFiles Changed tab:\n\nView all the files that changed across the commits\nIn Nav bar: Orange dot box signifies modified; Green plus box means something’s been added; Red minus box means deleted; Grey arrow box means renamed.\n\nChecks tab:\n\nShows status of the Github Action that renders and deploys the site. We can know whether this Pull Request is able to be deployed.\n\n\nNow, switch to the 2i2c Hub to view the Clinic preview as it would appear if the pull request was merged:\n\nTerminal:\n\nGo to the Main branch and pull so that we have the most recent changes from remote.\ngit checkout to the branch that has the Pull Request\nquarto preview - this will build the book with the author’s suggested edits.\n\n\nIn reviewing a pull request with lots of changes, it can be helpful to have windows open to view both the GitHub browser and the 2i2c Hub showing the Clinic site preview.\n\nIn GitHub under the “Files changed” tab of the PR, we can add a suggested edit by clicking the “plus” button below the line in question. Suggesting specific commits can speed the contributor’s workflow compared with trying to describe what we’d like them to change.\nWe can click “Start a review” button so the author gets a single email when we’re done reviewing, rather than getting one notification for every edit we suggest.\n\nReview each individual file that has changed and come back to the main _quarto.yml if we see an issue with the navigation.\nOnce our review is complete, we add a note in the GitHub review box and click “Approve”, “Comment” or “Request changes”. In the note it can be really helpful to add a note of appreciation for some aspect of the contribution, tagging the author, saying they can merge the PR after making changes, and possibly add a summary of our requested edits including the number of changes requested. Some changes in the middle of a long list of edits can be marked as hidden conversations, so this can be helpful to the author to know they’ve seen everything.\n\n\nAuthor merges Pull Request\nAs the author, you can now address the reviewer’s comments and then merge your Pull Request.",
"crumbs": [
"Part 2: GitHub workflow"
]
},
{
- "objectID": "part2-github.html#view-your-updates-in-the-live-site-regroup-10-min",
- "href": "part2-github.html#view-your-updates-in-the-live-site-regroup-10-min",
+ "objectID": "part2-github.html#your-turn---breakout-rooms",
+ "href": "part2-github.html#your-turn---breakout-rooms",
"title": "Part 2: GitHub workflow",
- "section": "View your updates in the live site (Regroup, 10 min)",
- "text": "View your updates in the live site (Regroup, 10 min)",
+ "section": "Your turn - Breakout rooms",
+ "text": "Your turn - Breakout rooms\nPair up in breakouts to make and review each other’s Pull Requests\nWe’ve done this demonstration - now you’ll go into breakout rooms. One of you be the Author role, and one the Reviewer role, with each of you screensharing where you are playing your role. Help each other out! If there is time, please switch roles\nSteps:\n\nAuthor stages, commits, and pushes file\nAuthor makes a Pull Request\nReviewer reviews the Pull Request\nAuthor merges Pull Request\nMake notes of any questions you have, challenges",
+ "crumbs": [
+ "Part 2: GitHub workflow"
+ ]
+ },
+ {
+ "objectID": "part2-github.html#regroup-wrap-up",
+ "href": "part2-github.html#regroup-wrap-up",
+ "title": "Part 2: GitHub workflow",
+ "section": "Regroup & Wrap up",
+ "text": "Regroup & Wrap up\n\nReview our updated site\nhttps://openscapes.github.io/quarto-clinic/demo\n\n\nTidying up\nGood practices to tidy your workspace & save unneccessary storage costs:\nFrom GitHub Browser: - Delete branch on GitHub Browser\nFrom JupyterHub: - Delete stefanie branch from the Git plugin - Delete quarto-clinic folder from terminal cd .. then rm -rf quarto clinic - Shut down Hub from File menu",
"crumbs": [
"Part 2: GitHub workflow"
]
@@ -134,7 +144,7 @@
"href": "part2-github.html#regroup-discussion-topics",
"title": "Part 2: GitHub workflow",
"section": "Regroup discussion topics",
- "text": "Regroup discussion topics\nShort message: commit the freeze folder.\n\nFreeze directory contains the results of code execution.\nCommit the freeze directory after you run quarto preview.\nIf there are merge conflicts when you submit to NASA Openscapes Cookbook, maintainers will help resolve them.",
+ "text": "Regroup discussion topics\n\nDeleting branches\n\n\nCode & rendering .qmd files\nYou can add code TODO\nWhen you Render, a document will be generated that includes both content and the output of embedded code. You can embed code like this:\nTODO: day before clinic, make this Python code (don’t add screenshot - fewer files to for folks to get distracted with, lighter weight repo)\nYou can add options to executable code. The echo: false option disables the printing of code (only output is displayed).\n\n\nFreeze\nCommit the freeze folder.\n\nFreeze directory contains the results of code execution.\nCommit the freeze directory after you run quarto preview.\nIf there are merge conflicts when you submit to NASA Openscapes Cookbook, maintainers will help resolve them.",
"crumbs": [
"Part 2: GitHub workflow"
]
@@ -215,7 +225,7 @@
"href": "demo.html#ideas-for-contributions",
"title": ".qmd file for practice",
"section": "Ideas for contributions",
- "text": "Ideas for contributions\n\nHeaders\nWe can make headers using ## Name, ### Name, etc. Headers are powerful in Quarto because they let you organize your content. You can share a specific subsection of a page by copying its URL.\n\n\nHyperlinks\nWe can make hyperlinks using the []() pattern: you name the hyperlink in [] and put the URL in (). For example, here’s a link to Markdown Basics. Hyperlinking lets us cite and give credit to our sources, like the NASA Earthdata Cloud Cookbook (Barrett et al.).\n\n\nImages\nWe can include an image with the same []() pattern, by adding a preceding exclamation point: ![](). The [] contain the caption (optional) and () contain the path to the image file.\nAdditional attributes like image size, alt text, and linking the image to a URL, are set inside {} in this example:\n{fig-alt=\"Openscapes logo. A hexagonal shape with orange border, yellow background, the word openscapes in orange above a cartoon evoking a landscape of data plots\" width=\"35%\"}\n\n\n\nThe Openscapes logo\n\n\n\n\nCode\nWhen you Render, a document will be generated that includes both content and the output of embedded code. You can embed code like this:\nTODO: day before clinic, make this Python code (don’t add screenshot - fewer files to for folks to get distracted with, lighter weight repo)\n\n2 * 2\n\n[1] 4\n\n\nYou can add options to executable code. The echo: false option disables the printing of code (only output is displayed).",
+ "text": "Ideas for contributions\n\nHeaders\nWe can make headers using ## Name, ### Name, etc. Headers are powerful in Quarto because they let you organize your content. You can share a specific subsection of a page by copying its URL.\n\n\nHyperlinks\nWe can make hyperlinks using the []() pattern: you name the hyperlink in [] and put the URL in (). For example, here’s a link to Markdown Basics. Hyperlinking lets us cite and give credit to our sources, like the NASA Earthdata Cloud Cookbook (Barrett et al.).\n\n\nImages\nWe can include an image with the same []() pattern, by adding a preceding exclamation point: ![](). The [] contain the caption (optional) and () contain the path to the image file.\nAdditional attributes like image size, alt text, and linking the image to a URL, are set inside {} in this example:\n{fig-alt=\"Openscapes logo. A hexagonal shape with orange border, yellow background, the word openscapes in orange above a cartoon evoking a landscape of data plots\" width=\"35%\"}\n\n\n\nThe Openscapes logo",
"crumbs": [
"Part 1: Quarto workflow",
"`.qmd` file for practice"
diff --git a/sitemap.xml b/sitemap.xml
index 713bdc3..4cea4fb 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,26 +2,26 @@
https://openscapes.github.io/quarto-clinic/part0-setup.html
- 2024-06-25T20:37:14.901Z
+ 2024-06-25T22:28:34.791Zhttps://openscapes.github.io/quarto-clinic/next-steps.html
- 2024-06-25T20:37:14.901Z
+ 2024-06-25T22:28:34.791Zhttps://openscapes.github.io/quarto-clinic/part2-github.html
- 2024-06-25T20:37:14.901Z
+ 2024-06-25T22:28:34.791Zhttps://openscapes.github.io/quarto-clinic/part1-quarto.html
- 2024-06-25T20:37:14.901Z
+ 2024-06-25T22:28:34.791Zhttps://openscapes.github.io/quarto-clinic/demo.html
- 2024-06-25T20:37:14.841Z
+ 2024-06-25T22:28:34.727Zhttps://openscapes.github.io/quarto-clinic/index.html
- 2024-06-25T20:37:14.901Z
+ 2024-06-25T22:28:34.791Z
