github_collab_workshop/outline.html at master · arockenberger/github_collab_workshop · GitHub

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
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>workshop_outline_english</title>
  <style>
    html {
      line-height: 1.7;
      font-family: Georgia, serif;
      font-size: 20px;
      color: #1a1a1a;
      background-color: #fdfdfd;
    }
    body {
      margin: 0 auto;
      max-width: 40em;
      padding-left: 50px;
      padding-right: 50px;
      padding-top: 50px;
      padding-bottom: 50px;
      hyphens: auto;
      word-wrap: break-word;
      text-rendering: optimizeLegibility;
      font-kerning: normal;
    }
    @media (max-width: 600px) {
      body {
        font-size: 0.9em;
        padding: 1em;
      }
    }
    @media print {
      body {
        background-color: transparent;
        color: black;
      }
      p, h2, h3 {
        orphans: 3;
        widows: 3;
      }
      h2, h3, h4 {
        page-break-after: avoid;
      }
    }
    p {
      margin-top: 1.7em;
    }
    a {
      color: #1a1a1a;
    }
    a:visited {
      color: #1a1a1a;
    }
    img {
      max-width: 100%;
    }
    h1, h2, h3, h4, h5, h6 {
      margin-top: 1.7em;
    }
    ol, ul {
      padding-left: 1.7em;
      margin-top: 1.7em;
    }
    li > ol, li > ul {
      margin-top: 0;
    }
    blockquote {
      margin: 1.7em 0 1.7em 1.7em;
      padding-left: 1em;
      border-left: 2px solid #e6e6e6;
      font-style: italic;
    }
    code {
      font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
      background-color: #f0f0f0;
      font-size: 85%;
      margin: 0;
      padding: .2em .4em;
    }
    pre {
      line-height: 1.5em;
      padding: 1em;
      background-color: #f0f0f0;
      overflow: auto;
    }
    pre code {
      padding: 0;
      overflow: visible;
    }
    hr {
      background-color: #1a1a1a;
      border: none;
      height: 1px;
      margin-top: 1.7em;
    }
    table {
      border-collapse: collapse;
      width: 100%;
      overflow-x: auto;
      display: block;
    }
    th, td {
      border-bottom: 1px solid lightgray;
      padding: 1em 3em 1em 0;
    }
    header {
      margin-bottom: 6em;
      text-align: center;
    }
    nav a:not(:hover) {
      text-decoration: none;
    }
    code{white-space: pre-wrap;}
    span.smallcaps{font-variant: small-caps;}
    span.underline{text-decoration: underline;}
    div.column{display: inline-block; vertical-align: top; width: 50%;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    ul.task-list{list-style: none;}
    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
  </style>
  <!--[if lt IE 9]>
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
  <![endif]-->
</head>
<body>
<h1 id="writing-and-publishing-on-the-web-together-using-github">Writing and Publishing on the Web Together Using Github</h1>
<p>You may be familiar with GitHub as a source of software, scripts, and programs. But, did you know that:</p>
<ul>
<li>GitHub can also be used to work on text documents?</li>
<li>GitHub enables collaboration on documents and software entirely through the web interface?</li>
<li>You can create a simple web page with a few clicks through GitHub?</li>
<li>You do not need any knowledge of the <a href="https://git-scm.com/">command-line version control tool Git</a> to do all this?</li>
</ul>
<p>In addition:</p>
<ul>
<li>Many researchers and developers in many disciplines put their code and projects on GitHub – or its sister GitLab.</li>
<li>You can find many useful – or just fun – projects here, e.g. for creating your website without having the hassle of finding a web hosting service and for no hosting cost <a href="https://github.com/academicpages/academicpages.github.io">academicpages</a>, or for making interactive presentations <a href="https://github.com/hakimel/reveal.js/">reveal.js</a>.</li>
<li>You can also use GitHub for collaborating with your team and managing your projects!</li>
</ul>
<p>This course will teach you how to do all these things, and more. It is aimed at graduate students and researchers at UiO and OUS, and tailored towards those with very little or no experience in the subjects taught. Experience with git, GitHub, or similar programs/services is not necessary, although it doesn’t hurt.</p>
<hr />
<h2 id="introduction">Introduction</h2>
<ul>
<li>What is GitHub?</li>
<li>What is in it for Me?</li>
</ul>
<h2 id="sign-up-and-setup">Sign up and Setup</h2>
<ul>
<li>create a GitHub account
<ul>
<li>chose the proper setup</li>
<li>make an informed decision about which email address to use</li>
<li>make an informed decision about what information you want to share with GitHub</li>
</ul></li>
<li>create a repository called “historical-recipes”</li>
<li>IMPORTANT:
<ul>
<li>Before clicking the “Create Repository” button, add a ‘README.md’ file</li>
<li>Address licenses - why they are essential &amp; useful (show https://choosealicense.com/)</li>
</ul></li>
<li>Tailor info about Open Science to local/national rules
<ul>
<li><a href="https://www.uio.no/english/for-employees/support/research/research-data-management/">University of Oslo guidelines for research data and research software</a></li>
</ul></li>
</ul>
<h2 id="backdrop">Backdrop</h2>
<ul>
<li>Historical Recipes project (see <a href="https://github.com/arockenberger/github_collab_workshop/blob/master/story.md">here</a>)</li>
</ul>
<h2 id="add-files-to-a-repo">Add Files to a Repo</h2>
<ul>
<li>Create a file called <code>ingredients.txt</code>
<ul>
<li>add one ingredient “eggs”</li>
<li>explain commit action
<ul>
<li>show a good commit message</li>
<li>add description; commit</li>
</ul></li>
</ul></li>
<li>Edit <code>ingredients.txt</code> by adding butter, cream, chives; commit
<ul>
<li>Show diff</li>
</ul></li>
<li>Edit <code>ingredients.txt</code> by removing cream; commit
<ul>
<li>Show diff</li>
</ul></li>
<li>Create a file called <code>instructions.txt</code> and add:
<ul>
<li>scramble eggs</li>
<li>mince chives</li>
<li>melt butter</li>
<li>whisk in cream; commit</li>
</ul></li>
</ul>
<h2 id="collaborate-directly">Collaborate directly</h2>
<h3 id="group-work-setup">Group-work Setup</h3>
<ul>
<li>Divide into groups of four
<ul>
<li>“project lead” #1 gets yellow sticky note</li>
<li>#1 repo will be used</li>
<li>#2, #3, #4 close the window with their repo</li>
<li>#1 add #2, #3, #4 as collaborators
<ul>
<li>navigate to ‘Settings’ tab,</li>
<li>click ‘Collaborators’ in left panel</li>
<li>use GitHub username without @</li>
</ul></li>
<li>#2, #3, #4 check their email and accept invitation</li>
</ul></li>
</ul>
<h3 id="making-changes-to-repository">Making Changes to Repository</h3>
<ul>
<li>#2 makes a change to repository
<ul>
<li>add <em>heat skillet to medium-low</em> to <code>instructions.txt</code>; <code>commit</code></li>
<li>#1 click on commit message
<ul>
<li>#1 add comment to commit (scroll down)</li>
<li>#2 respond to comment</li>
</ul></li>
</ul></li>
<li>#1 convert <code>ingredients.txt</code> to <code>ingredients.md</code>
<ul>
<li>quick intro markdown</li>
<li>google “markdown cheat sheet”
<ul>
<li>convert into markdown list</li>
<li>add salt</li>
<li>look at rendered version</li>
</ul></li>
</ul></li>
</ul>
<h3 id="explain-issues-and-pull-request-principles">Explain Issues and Pull Request Principles</h3>
<ul>
<li><p>#4 submit an issue</p>
<ul>
<li>“We need to convert <code>instructions.txt</code> to <code>instructions.md</code>”</li>
<li>#1 check email</li>
</ul></li>
<li><p>#3 submit an unrelated Issue</p>
<ul>
<li>“Change ‘chives’ to ‘Allium schoenoprasum’ as ingredient”</li>
<li>#1 check Notifications</li>
</ul></li>
<li><p>#4 prepare a Pull request to address Issue #1</p>
<ul>
<li>make branch</li>
<li>make changes</li>
<li>commit to new branch</li>
<li>submit Pull request</li>
<li>add link to issue in Pull-request</li>
<li>#1 check email/notifications</li>
</ul></li>
<li><p>#3 prepare a pull request to address issue #2</p>
<ul>
<li>this time, do not start from a new branch</li>
<li>instead, commit to new branch when finished</li>
<li>also include a typo in the change (!)</li>
</ul></li>
<li><p>#1 add a comment to pull request, ‘fix typo!’</p>
<ul>
<li>#3 check email/notifications</li>
</ul></li>
<li><p>#3 fix typo, thus adding a commit to the Pull-request</p></li>
<li><p>#1 merge Pull-request</p></li>
<li><p>Exercise: do another cycle of an issue by one and a PR by the other, include comments and merge PR</p></li>
</ul>
<h2 id="prevent-conflicts">Prevent conflicts</h2>
<ul>
<li><p>#2 create branch with change</p>
<ul>
<li>call branch collab</li>
<li>wait with the PR</li>
</ul></li>
<li><p>#1 commit change on same line in same file in main branch</p></li>
<li><p>#2 submit PR –&gt; conflict</p>
<ul>
<li>#1 &amp; #2 communicate through ‘code review’</li>
<li>#1 resolve</li>
</ul></li>
<li><p>#1 merge PR</p></li>
</ul>
<h2 id="collaborate-by-suggesting-changes">Collaborate by ‘suggesting’ changes</h2>
<ul>
<li>no commit rights</li>
<li>explain forking</li>
<li>instructor makes new repo for biographies</li>
<li>second instructor, demonstrate adding bio as PR
<ul>
<li>for the repo</li>
<li>add a new file in a fork</li>
<li>find ‘submit PR’ button on the forked repo</li>
<li>follow PR steps</li>
</ul></li>
<li>first instructor accept PR</li>
<li>each participant: add a new file with two or three lines to describe yourself (can be made up), add as PR</li>
<li>Exercise: in pairs
<ul>
<li>add issues to the other person’s biography file</li>
<li>and/or add PR, comments to PR, fixes etc</li>
<li>discuss through Github</li>
<li>add ‘OK to merge’ when ready</li>
</ul></li>
<li>instructor merges
<ul>
<li>merge PRs and close issues</li>
</ul></li>
<li>update your fork with the changes from the repo you forked from
<ul>
<li>in the fork, click the ‘compare’ button (right)</li>
<li>switch the base</li>
<li>check changes</li>
<li>click ‘Pull request’</li>
<li>now it is OK to merge your Pull request</li>
</ul></li>
</ul>
<h2 id="real-world-example">Real-world example</h2>
<ul>
<li>look at (https://github.com/swcarpentry/make-novice/)</li>
<li>issues and pull request, conversation</li>
<li>(https://github.com/swcarpentry/make-novice/pull/43)</li>
</ul>
<h2 id="building-a-simple-website-using-github">Building a simple website using GitHub</h2>
<ul>
<li>back to Historical Recipes repo</li>
<li>add <code>index.md</code> with a few lines of text</li>
<li>on the ‘Settings’ tab of the Github repo, enable finding “Select a source below to enable GitHub Pages for this repository” and select ‘main branch’ from the pulldown</li>
<li>find your webpage</li>
<li>in <code>index.md</code>, add (markdown) links to <code>ingredients.md</code> and <code>instructions.md</code></li>
<li>Exercise: customise your recipe website</li>
</ul>
<h2 id="another-demo-norwegian-correspondences-project-website">Another demo: Norwegian Correspondences project website</h2>
<ul>
<li>(https://arockenberger.github.io/NorKorr/)</li>
</ul>
<h2 id="example-of-the-final-result">Example of the final result</h2>
<hr />
<h2 id="instructor-notes">instructor notes</h2>
<ul>
<li>Co-instructor is number 2</li>
<li>Laptop switching between them, make the second laptop look different</li>
</ul>
</body>
</html>