Skip to content

Commit 78f4ec0

Browse files
astroDimitriosastroDimitrios
authored
MetOffice#46 Adds in instructor notes
1 parent 7e63174 commit 78f4ec0

File tree

1 file changed

+205
-14
lines changed

1 file changed

+205
-14
lines changed

‎instructors/instructor-notes.md

Lines changed: 205 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,50 @@
22
title: Instructor Notes
33
---
44

5-
## Setup
5+
## General Notes
66

7-
To setup this lesson you will need
8-
to create a `git-training-demo`
9-
repository using the
10-
[zipped directory](data/git-training-demo.zip)
11-
we provide.
7+
General notes for each section are below:
8+
9+
### [Setup](../learners/setup.md)
10+
11+
Below are setup steps instructors need to complete before
12+
the workshop.
13+
14+
#### GitHub Usernames
15+
16+
You should collect GitHub usernames from learners
17+
beforehand either using the sign-up form or
18+
by emailing learners separately the week before.
19+
Sort the learners into pairs before the workshop.
20+
They need to be in pairs to review each others PRs
21+
in [Episode 5 Review](../episodes/04-review.md).
22+
23+
In [Episode 1](../episodes/00-repo-access.md) you will demonstrate
24+
how to give access to a repository by adding these users
25+
to the `git-training-demo` repository.
26+
If there are many external learners from partner institutions
27+
you may wish to give some learners **write** access to the `git-training-demo`
28+
repository before the lesson to save time.
29+
30+
### `git-training-demo` Repository
31+
32+
::: callout
33+
34+
## Met Office
35+
36+
Met Office instructors will find that the `git-training-demo`
37+
repository has already been set up for you.
38+
If for any reason you need to create a new repository
39+
you can do so by creating a new repository
40+
from the `git-training-demo-template` template repository
41+
(you will still need to setup the rule in step 8 below),
42+
or by following all the steps below.
43+
44+
:::
45+
46+
To setup the repository for this lesson you will need
47+
to create the `git-training-demo` repository using the
48+
[zipped directory](data/git-training-demo.zip) we provide.
1249

1350
1. Download the [zipped directory](data/git-training-demo.zip).
1451
2. Unzip the directory on your system.
@@ -23,16 +60,170 @@ your organisation.
2360
push all changes.
2461
8. Setup a rule to require a PR before
2562
merging with `main`.
63+
Allow admins to bypass this rule.
64+
65+
The last step is to create a new milestone on the repository
66+
with the name: **Git & GitHub WP INSERT_DATE**.
67+
68+
### GitHub Project
69+
70+
::: callout
2671

27-
Pay particular attention to the instructor
28-
callouts in episodes [05](../episodes/05-forks.md)
29-
and [08](../episodes/08-rebase.md)
30-
which outline how to create the conflicts
31-
the learners will have to resolve.
72+
## Met Office
73+
74+
Met Office instructors will find that the **Git & GitHub WP** Project
75+
has already been setup for them.
76+
Instructors just need to ensure that all learners
77+
are either in the `git-and-github-training` Met Office GitHub team
78+
or have been given read access if they are external to the organisation.
79+
80+
:::
3281

3382
You will need to create a GitHub Project for learners to
3483
link Issues they create on the `git-training-demo` repository to.
35-
You can name this Project: **Git & GitHub WP INSERT_DATE**
84+
You can name this Project **Git & GitHub WP**.
85+
Give the `git-and-github-training` team permissions on the GitHub Project.
3686

37-
The last step is to create a new milestone on the repository
38-
with an identical or similar name to the Project name.
87+
### [Introduction](../index.md)
88+
89+
Use the following text as a guide for your intro,
90+
show the web notes as you introducing the workshop.
91+
92+
How do you use Git and GitHub to collaborate?
93+
This course will guide learners through two common workflows
94+
used to collaborate on code with GitHub.
95+
It will introduce you to all sorts of neat features like
96+
GitHub projects for team management and automatic code review testing.
97+
By the end of the workshop you'll have the knowledge you
98+
need to decide which working practices are right for you
99+
and your team.
100+
Some things we'll be thinking about:
101+
102+
- Who do I need to give repo access to? How do I do it?
103+
- How do you do a full code review on GitHub?
104+
- What do all the merge options mean?
105+
- Do we merge main (trunk) into our feature branches?
106+
- Who presses the merge button?
107+
108+
### [Repository Access](../episodes/00-repo-access.md)
109+
110+
At the start of this episode you will demonstrate how to give
111+
collaborators access to the `git-training-demo` repository.
112+
Give **write** access to:
113+
114+
- The `git-and-github-training` team (which will include all Met Office colleagues).
115+
- Add partners individually.
116+
117+
Later on in the workshop before the episode on forking
118+
you will reduce learners permissions to **triage**.
119+
120+
### [Issues](../episodes/01-issues.md)
121+
122+
This section is relatively simple - open an Issue to
123+
add a file with your favourite cloud.
124+
125+
- Add a milestone, project, and assign yourself to the Issue.
126+
- It would be good to have an image of a cloud to
127+
drag and drop in the Issue to demonstrate this functionality.
128+
129+
### [Branching Models](../episodes/02-branching.md)
130+
131+
There is nothing in this episode for learners to do
132+
so keep it short and snappy.
133+
134+
- Highlight that in the intro lesson learners used the feature branch workflow.
135+
- Mention the links at the end of the episode which have much
136+
more detail on other models.
137+
138+
### [Feature Branch Model](../episodes/03-feature-branch.md)
139+
140+
Learners will not have cloned a repository before!
141+
PR templates and automatically closing PRs are also new.
142+
**When the PR is opened they should assign the other learner
143+
in their pair as the reviewer**.
144+
145+
There is a chance their changes fail the PR checks.
146+
Point out that they may have failed, show the PR page
147+
and see if any have red cross next to them.
148+
Explain briefly that we use automated PR checks
149+
using pre-commit and there is an [optional episode](../episodes/09-pre-commit.md)
150+
at the end of the lesson on how to use these.
151+
You may need to help learners fix their change locally
152+
and push a new commit so these checks pass.
153+
If you take a 10 minute or longer break at the end of
154+
the episode you can help those learners whose tests failed during the break.
155+
156+
### [Review](../episodes/04-review.md)
157+
158+
It's important that learners make a suggestion on their partners PR,
159+
it doesn't matter what that suggestion is.
160+
161+
The 2 instructors will need to swap part way through this episode.
162+
163+
#### Reviewing Changes
164+
165+
In this section the first instructor should review the PR
166+
opened by the second instructor.
167+
168+
#### Responding to Review
169+
170+
In this section the second instructor should respond to the review,
171+
sharing their screen.
172+
They can change their GitHub theme so that the 2 instructors GitHub pages
173+
look visually distinct, this makes it clearer whether we are
174+
watching the reviewer or the developer.
175+
176+
#### Approving Changes
177+
178+
Swap back to the first instructor so they can approve the changes.
179+
Make sure you cover the content in the
180+
**WHO PRESSES THE MERGE BUTTON?** callout.
181+
Give learners a break and the opportunity to complete
182+
the yellow challenge **Local Cleanup**.
183+
184+
### [Break](../episodes/Break.md)
185+
186+
Remember to take regular breaks.
187+
188+
### [Forks](../episodes/05-forks.md)
189+
190+
You can choose here to either change everyone's permissions down
191+
to **triage**:
192+
193+
- during the break before the episode.
194+
- at the start of the episode to remind learners again how to change permissions.
195+
196+
Please showcase fully, as described in the episode,
197+
how to sync your fork via the command line.
198+
They will use the handy GitHub button later.
199+
200+
### [Conflicts](../episodes/06-conflict.md)
201+
202+
The most important thing to remember here is the second instructor
203+
**MUST** have opened a PR just like the learners are doing
204+
and merge this after opening (and after learners have updated their `main`
205+
branches and created their feature branches).
206+
They can bypass protections and do this while the first instructor is teaching.
207+
This generates the citation file conflict the first instructor will point out.
208+
209+
### [History](../episodes/07-history.md)
210+
211+
Users will have covered using `git log` in the intro lesson.
212+
Show learners what the history of the repository looks like now.
213+
Then walk through the merge options, keep it short and snappy.
214+
There are no learner exercises in this episode,
215+
make sure you ask learners what questions they have at the end.
216+
217+
### [End](../episodes/End.md)
218+
219+
What questions do the learners still have?
220+
If there is time then maybe with a vote decide what to briefly look at:
221+
222+
- Actions
223+
- pre-commit
224+
- Rebasing
225+
226+
## Notes from within Episodes
227+
228+
The following notes are stored within the episode webpages
229+
and are extracted here for completeness:

0 commit comments

Comments
 (0)