generated from Openscapes/quarto-clinic
-
Notifications
You must be signed in to change notification settings - Fork 0
/
part2-github.qmd
153 lines (91 loc) · 8.25 KB
/
part2-github.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
---
title: "Part 2: GitHub workflow"
---
## Workflow to contribute via GitHub
**Bold** words are git/GitHub terms. In this example there are two roles: an Author and a Reviewer.
1. Author **stages** their changes
2. Author **commits** changes with a helpful **Commit message**
3. Author **pushes** to GitHub
4. Author make a **Pull Request** and tag a reviewer from GitHub.com
5. Reviewer responds by commenting, making suggested commits, and submitting their **review**
6. Author responds to review and **merges** their Pull Request
7. A GitHub Action automatically publishes the updates in the live site
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
We have to deliberately tell Git/GitHub when we have work that we want to be versioned and synced. This is separate from saving the file, which is required first. Let's inspect the differences our edits will introduce.
{fig-align="center" width="80%"}
In the Git tab I will "stage" my saved changes. (There may be a `.json` file that you also stage; this is part of the Quarto build process.)
{fig-align="center" width="50%"}
Next I will commit my edits with a good commit message and push my edits to GitHub. A commit message is a human-readable message, like leaving a breadcrumb trail for my future self and others.
{fig-align="center" width="50%"}
When we **push** by clicking the push icon (with the orange dot since we have committed files to push), we may be prompted to enter Git credentials.
### Aside: set up our Git credentials
When you see the following screenshot, GitHub is asking for you to input your Git credentials. You see this when you have committed work to push to GitHub.com. In this case we have created a new branch and made changes to a file in the Hub and these do not yet exist on GitHub.
{fig-align="center" width="70%"}
We'll follow the instructions in the 2021 Cloud Hackathon to [Setup your Personal Access Token (PAT)](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/tutorials/00_Setup.html#step-5.6.-setup-pat).
### Author makes a Pull Request
Our current status: We are in the Hub, and in our own branch of the Quarto Clinic GitHub 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 GitHub **Pull Request**.
So now I'll go to <https://github.com/NASA-Openscapes/quarto-clinic/> and I will see a yellow banner inviting me to make a Pull Request to add my edits to the Clinic repo.
{fig-align="left" width="90%"}
#### Pull Request elements
{fig-align="center" width="90%"}
Maybe I'm not finished proposing my updates? I can **set my Pull Request as a Draft** at the start so folks can see my thinking, and we can have conversations about it. Set Ready for Review when ready and request a reviewer(s).
From the pull request page in GitHub browser, look at the elements of the pull request.
- 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:
- 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:
- 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:
- Shows status of the Github Action that renders and deploys the site. We can know whether this Pull Request is able to be deployed.
### Reviewer reviews the Pull Request
GitHub has gotten really powerful at doing reviews from the browser, so we can review small Pull Requests right here in GitHub.com. Note: When you are reviewing a Pull Request with a lot of code and analyses you need to run and dig into more deeply, you will do your review in JupyterHub by pulling the branch's updates and committing your suggestions there. Today we will only practice a small review from the GitHub browser.
- In 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.
{fig-align="center" width="60%"}
- We 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.
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.
### Author merges Pull Request
As the author, you can now address the reviewer's comments and then merge your Pull Request.
## 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
Steps:
- Author stages, commits, and pushes file
- Author makes a Pull Request
- Reviewer reviews the Pull Request
- Author merges Pull Request
- Make notes of any questions you have, challenges
## Regroup & Wrap up
### Review our updated site
<https://nasa-openscapes.github.io/quarto-clinic/demo>
### Tidying up
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
## Regroup discussion topics
### Code & rendering `.qmd` files
You can add code
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
You can add options to executable code. The `echo: false` option disables the printing of code (only output is displayed).
### Review in JupyterHub
Now, switch to the 2i2c Hub to view the Clinic preview as it would appear if the pull request was merged:
- Terminal:
- Go to the Main branch and pull so that we have the most recent changes from remote.
- `git checkout` to the branch that has the Pull Request
- `quarto preview` - this will build the book with the author's suggested edits.
In 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.
### Freeze
**Commit the freeze folder.**
- Freeze directory contains the results of code execution.
- Commit the freeze directory after you run quarto preview.
- If there are merge conflicts when you submit to NASA Earthdata Cloud Cookbook, maintainers will help resolve them.