-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy path01-github-collaboration-workflows.qmd
More file actions
207 lines (159 loc) · 13.5 KB
/
01-github-collaboration-workflows.qmd
File metadata and controls
207 lines (159 loc) · 13.5 KB
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
---
title: "GitHub Collaboration Workflows"
---
## Welcome & Setup Check (10 mins)
**Learning Objective:** Practice key steps for remote code hosting and collaborating in GitHub by using branches, opening pull requests (PRs), reviewing PRs, and merging changes
::: mark
#### **Activity**: Make your own copy of a repo (`clone`)
:::
We are going to use the repository <https://github.com/dawnbcgov/aq-intro-to-github-shinyapps> that hosts this website for practice today.
Go ahead and make a copy of the repository with all the files for (or using git terminology "`clone`") this website to your local machine.
```{=html}
<div class="accordion">
<div class="accordion-item">
<h2 class="accordion-header" id="headingOne">
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne" aria-expanded="false" aria-controls="collapseOne">
<strong>Detailed Steps</strong>
</button>
</h2>
<div id="collapseOne" class="accordion-collapse collapse" aria-labelledby="headingOne" data-bs-parent="#accordionExample" style="">
<div class="accordion-body">
<ol>
<li>Find the URL or address of the repository you want to make a local copy of on GitHub (in this case <code>https://github.com/dawnbcgov/aq-intro-to-github-shinyapps.git</code> (how you clone via GitHub desktop) or <code>git@github.com:dawnbcgov/aq-intro-to-github-shinyapps.git</code> (which is how to clone via cli)) </li>
<li>If you are using GitHub Desktop, go to File > Clone repository </li>
<li>Or, if you are using the <code>git</code> cli, use Git Bash and the command <code>git clone <url></code> where the <code><url></code> is the address</li>
</ol>
</div>
</div>
</div>
</div>
```
::: callout-note
## Resources used
- [Cloning and forking repositories from GitHub Desktop](https://docs.github.com/en/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop)
- [Git Basics - Getting a Git Repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)
:::
## Refresher on key concepts with version control (10 mins)
- Key concepts we want to review:
#### Version Control
Sequential changes:
The power of git and similar version control systems: different versions can be saved, conflicts resolved, and then merged together:
#### Remote Code Hosting and GitHub
#### Branches
::: callout-note
## Resources used
- BC Stats: [Introduction to Version Control with Git & GitHub \> What is Version Control](https://bcgov.github.io/ds-intro-to-git/materials/01-what-is-vc.html)
- BC Stats: [Introduction to Version Control with Git & GitHub \> Remote Code Hosting and GitHub](https://bcgov.github.io/ds-intro-to-git/materials/03-remote-hosting.html)
- GitHub: [About Branches](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches)
:::
## Tracking changes (20 mins)
::: mark
#### **Activity**: Make a change to this site (commit and push)
:::
Now that we each have a copy of this site, we are going to make a change! (First a micro crash course on quarto and markdown)
So, now, on your computer, make a new page for this website in the practice area. Add whatever you want then save it. Next, you'll need to commit that change and `push` (or publish / send it) so we all can see.
```{=html}
<div class="accordion">
<div class="accordion-item">
<h2 class="accordion-header" id="headingTwo">
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
<strong>Detailed Steps</strong>
</button>
</h2>
<div id="collapseTwo" class="accordion-collapse collapse" aria-labelledby="headingTwo" data-bs-parent="#accordionExample" style="">
<div class="accordion-body">
<ol>
<li>Open RStudio, VS Code or your preferred editor, markdown files are like text files so you could use notepad if you want</li>
<li>Create a new file in the <code>practice</code> folder, it should end in <code>.qmd</code> and needs to have the <code>---</code> section at the top. (You could make a copy of one of the files that are there)</li>
<li>Make your edits and save</li>
<li>When you are ready, select the file you changed, commit it (you will need to add a message), and push it</li>
</ol>
</div>
</div>
</div>
</div>
```
::: callout-note
## Resources used
- Software Carpentry: [Version Control with Git](https://swcarpentry.github.io/git-novice/) (Episode: 4. Tracking changes)
:::
## Collaboration on GitHub (20 mins)
We've all been working from the `main` branch, but that can be risky for a many reasons.
Just a couple: we might make a mistake while we're working and if we just keep updating the authoritative copy we could miss it. second, two people might change the same file and then we need a process to resolve that conflict.
Git and GitHub give us powerful collaboration tools we can use to manage all these processes!
### Creating pull requests (PR)
::: mark
#### **Activity**: Make a change to another page on a branch and change it back to the main site (pull request)
:::
Let's make an edit to someone else's page on a new `branch` and use the collaboration tools to review and merge those changes (and resolve conflicts!).
```{=html}
<div class="accordion">
<div class="accordion-item">
<h2 class="accordion-header" id="headingThree">
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
<strong>Detailed Steps</strong>
</button>
</h2>
<div id="collapseThree" class="accordion-collapse collapse" aria-labelledby="headingThree" data-bs-parent="#accordionExample" style="">
<div class="accordion-body">
<ol>
<li>First you have to make a new <code>branch</code> give it a name that someone else is not likely to use, like your name</li>
<li>Open and edit an existing file in the <code>practice</code> folder</li>
<li>Make your edits and save</li>
<li>When you are ready, select the file you changed, commit it (you will need to add a message), and push it. There will be an extra step to set up the branch in the repository we are all using depending on your software</li>
<li>Then go to GitHub.com and go to the <a href="https://github.com/dawnbcgov/aq-intro-to-github-shinyapps/pulls">pull request tab</a></li>
<li>Select your branch to "compare" with the main branch and then the button create pull request</li>
</ol>
</div>
</div>
</div>
</div>
```
### Reviewing pull requests
To mitigate the risk of pushing directly to the `main` branch, some repositories have [branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). These rules restrict merges and commits to specific branches unless specific criteria are made. One common criteria is that the pull request can only be merged to the `main` branch if it has been reviewed by another collaborator. Even without these rules, working on a development branch and asking a collaborator to review your pull request is good practice. When you create a pull request, you can use the GitHub pull request page to request/assign reviewers (right hand menu).
::: mark
#### **Activity**: Review a proposed change to the main site (pull request)
:::
Although this repo will not have branch protection rules applied, we can practice navigating the pull request review process on GitHub. Let's review the practice branch we've created, `pr_practice`, together. Follow the instructions on the pull request itself. You can also walk through every step in the accordion box below.
```{=html}
<div class="accordion">
<div class="accordion-item">
<h2 class="accordion-header" id="headingThree">
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
<strong>Detailed Steps</strong>
</button>
</h2>
<div id="collapseThree" class="accordion-collapse collapse" aria-labelledby="headingThree" data-bs-parent="#accordionExample" style="">
<div class="accordion-body">
<ol>
<li>First, navigate to the <a href="https://github.com/dawnbcgov/aq-intro-to-github-shinyapps/pulls">pull request tab</a> of the GitHub repository.</li>
<li>Click on the PR you want to review. For this activity, it is the one named "PR Review Practice". Note that Issues and PRs are numbered in the same sequence.</li>
<li>On the PR's page, you can first start with the "Conversation" tab and read through the PR author's description of the changes. You can follow any conversation that might have already happened and also see a history of commits, all in chronological order. Read through the existing comments and add a hello of your own.</li>
<li>On the "Commits" tab, you can see just the commit history for the branch that is the subject of the pull request. Note that as the review and conversation progresses, further pushes to this branch will also update the pull request. That is, the pull request is for a *branch* to be pulled into another, not a specific commit. </li>
<li>We can skip the "Checks" tab for this practice. For repos with Continuous Integration/Continuous Deployment (aka <a href="https://www.redhat.com/en/topics/devops/what-is-ci-cd">CI/CD</a>), the history of the output of all automated checking and unit testing scripts will appear here. For workflows that use it, it can help the collaborators answer the question "Does this code work?"</li>
<li>The "Files changed" tab is where you will do most of the reviewing. For each file changed, you can see the "diff" of the original and proposed changes. For long files, only the changed lines are displayed, but you can expand the collapsed lines if you need to see the context. Here are some review activities to try:</li>
<ol>
<li> Notice that there is a review interface in the upper right (that will stay on top as you scroll) showing how many files you have reviewed and a green button to finalise your review. But first, let's just read through the file with the long word list.</li>
<li>Find duplicate lines and add a line-specific comment to flag as a duplicate. Just do one duplicate so others can flag too. You can do this by mousing over the space between the line number and the line of code. A blue + sign will appear. Click on it. You can type a comment (e.g. a correction of the spelling) and then add your comment with either "add single comment" or "Start a review" (choose this for this activity).</li>
<li>You can also add a comment to the entire file rather than a specific line. In the upper right area of the box for the cat facts file (or any file in the PR), there is a speech bubble icon to click on and add a comment. Write a comment and then "Add review comment".
<li>When you are finished with each file, you can click the "Viewed" box to indicate that you have reviewed the file. It will close/collapse the container and you can move on to the next file. It's not necessary to check this box but it can help you keep track and indicate to others that you reviewed it without having to leave a comment that just says "looks good".</li>
<li>Repeat with any other files and then click "Finish your review". You can write one additional "final review" comment if you want. You also have three options with your review: just comment, approve, or indicate that more changes are needed before you can approve. Submit an "approve" review.</li>
</ol>
</ol>
</div>
</div>
</div>
</div>
```
The GitHub review interface is very handy. All review comments go into the "Conversation" tab. When specific lines of codes are mentioned, a preview appears. Each comment can have its own thread to help discuss the details of the code. Conversations can be "resolved" when you have iterated enough to meet the requirements.
If you come back to the PR after having reviewed it and changes have been made, the interface remembers what you have seen and you can just review the new changes. Files that you have clicked as "Viewed" will be unclicked if there were changes. If you need to see the full context and history, those are available as well, in the tabs mentioned above. You can also use `diff` tools on GitHub or on your own software to make more comparisons.
Finally, testing the code is not part of this activity, but if you wanted to run the code on the pull request locally, you would check out the branch of the PR and then you have a copy of the code being reviewed as well.
::: callout-note
## Resources used
- Software Carpentry: [Version Control with Git](https://swcarpentry.github.io/git-novice/08-collab.html) (Episode: 8. Collaborating and Episode 9. Conflicts)
:::