markdown source builds

Auto-generated via `{sandpaper}`
Source  : 78f4ec0
Branch  : main
Author  : Dimitrios Theodorakis <[email protected]>
Time    : 2025-01-10 16:53:57 +0000
Message : MetOffice#46 Adds in instructor notes

instructor-notes.md

@@ -2,13 +2,50 @@
 title: Instructor Notes
 ---
 
-## Setup
+## General Notes
 
-To setup this lesson you will need
-to create a `git-training-demo`
-repository using the
-[zipped directory](data/git-training-demo.zip)
-we provide.
+General notes for each section are below:
+
+### [Setup](../learners/setup.md)
+
+Below are setup steps instructors need to complete before
+the workshop.
+
+#### GitHub Usernames
+
+You should collect GitHub usernames from learners
+beforehand either using the sign-up form or
+by emailing learners separately the week before.
+Sort the learners into pairs before the workshop.
+They need to be in pairs to review each others PRs
+in [Episode 5 Review](../episodes/04-review.md).
+
+In [Episode 1](../episodes/00-repo-access.md) you will demonstrate
+how to give access to a repository by adding these users
+to the `git-training-demo` repository.
+If there are many external learners from partner institutions
+you may wish to give some learners **write** access to the `git-training-demo`
+repository before the lesson to save time.
+
+### `git-training-demo` Repository
+
+::: callout
+
+## Met Office
+
+Met Office instructors will find that the `git-training-demo`
+repository has already been set up for you.
+If for any reason you need to create a new repository
+you can do so by creating a new repository
+from the  `git-training-demo-template` template repository
+(you will still need to setup the rule in step 8 below),
+or by following all the steps below.
+
+:::
+
+To setup the repository for this lesson you will need
+to create the `git-training-demo` repository using the
+[zipped directory](data/git-training-demo.zip) we provide.
 
 1. Download the [zipped directory](data/git-training-demo.zip).
 2. Unzip the directory on your system.
@@ -23,16 +60,170 @@ your organisation.
    push all changes.
 8. Setup a rule to require a PR before
    merging with `main`.
+   Allow admins to bypass this rule.
+
+The last step is to create a new milestone on the repository
+with the name: **Git & GitHub WP INSERT_DATE**.
+
+### GitHub Project
+
+::: callout
 
-Pay particular attention to the instructor
-callouts in episodes [05](../episodes/05-forks.md)
-and [08](../episodes/08-rebase.md)
-which outline how to create the conflicts
-the learners will have to resolve.
+## Met Office
+
+Met Office instructors will find that the **Git & GitHub WP** Project
+has already been setup for them.
+Instructors just need to ensure that all learners
+are either in the `git-and-github-training` Met Office GitHub team
+or have been given read access if they are external to the organisation.
+
+:::
 
 You will need to create a GitHub Project for learners to
 link Issues they create on the `git-training-demo` repository to.
-You can name this Project: **Git & GitHub WP INSERT_DATE**
+You can name this Project **Git & GitHub WP**.
+Give the `git-and-github-training` team permissions on the GitHub Project.
 
-The last step is to create a new milestone on the repository
-with an identical or similar name to the Project name.
+### [Introduction](../index.md)
+
+Use the following text as a guide for your intro,
+show the web notes as you introducing the workshop.
+
+How do you use Git and GitHub to collaborate?
+This course will guide learners through two common workflows
+used to collaborate on code with GitHub.
+It will introduce you to all sorts of neat features like
+GitHub projects for team management and automatic code review testing.
+By the end of the workshop you'll have the knowledge you
+need to decide which working practices are right for you
+and your team.
+Some things we'll be thinking about:
+
+- Who do I need to give repo access to? How do I do it?
+- How do you do a full code review on GitHub?
+- What do all the merge options mean?
+- Do we merge main (trunk) into our feature branches?
+- Who presses the merge button?
+
+### [Repository Access](../episodes/00-repo-access.md)
+
+At the start of this episode you will demonstrate how to give
+collaborators access to the `git-training-demo` repository.
+Give **write** access to:
+
+- The `git-and-github-training` team (which will include all Met Office colleagues).
+- Add partners individually.
+
+Later on in the workshop before the episode on forking
+you will reduce learners permissions to **triage**.
+
+### [Issues](../episodes/01-issues.md)
+
+This section is relatively simple - open an Issue to
+add a file with your favourite cloud.
+
+- Add a milestone, project, and assign yourself to the Issue.
+- It would be good to have an image of a cloud to
+  drag and drop in the Issue to demonstrate this functionality.
+
+### [Branching Models](../episodes/02-branching.md)
+
+There is nothing in this episode for learners to do
+so keep it short and snappy.
+
+- Highlight that in the intro lesson learners used the feature branch workflow.
+- Mention the links at the end of the episode which have much
+more detail on other models.
+
+### [Feature Branch Model](../episodes/03-feature-branch.md)
+
+Learners will not have cloned a repository before!
+PR templates and automatically closing PRs are also new.
+**When the PR is opened they should assign the other learner
+in their pair as the reviewer**.
+
+There is a chance their changes fail the PR checks.
+Point out that they may have failed, show the PR page
+and see if any have red cross next to them.
+Explain briefly that we use automated PR checks
+using pre-commit and there is an [optional episode](../episodes/09-pre-commit.md)
+at the end of the lesson on how to use these.
+You may need to help learners fix their change locally
+and push a new commit so these checks pass.
+If you take a 10 minute or longer break at the end of
+the episode you can help those learners whose tests failed during the break.
+
+### [Review](../episodes/04-review.md)
+
+It's important that learners make a suggestion on their partners PR,
+it doesn't matter what that suggestion is.
+
+The 2 instructors will need to swap part way through this episode.
+
+#### Reviewing Changes
+
+In this section the first instructor should review the PR
+opened by the second instructor.
+
+#### Responding to Review
+
+In this section the second instructor should respond to the review,
+sharing their screen.
+They can change their GitHub theme so that the 2 instructors GitHub pages
+look visually distinct, this makes it clearer whether we are
+watching the reviewer or the developer.
+
+#### Approving Changes
+
+Swap back to the first instructor so they can approve the changes.
+Make sure you cover the content in the
+**WHO PRESSES THE MERGE BUTTON?** callout.
+Give learners a break and the opportunity to complete
+the yellow challenge **Local Cleanup**.
+
+### [Break](../episodes/Break.md)
+
+Remember to take regular breaks.
+
+### [Forks](../episodes/05-forks.md)
+
+You can choose here to either change everyone's permissions down
+to **triage**:
+
+- during the break before the episode.
+- at the start of the episode to remind learners again how to change permissions.
+
+Please showcase fully, as described in the episode,
+how to sync your fork via the command line.
+They will use the handy GitHub button later.
+
+### [Conflicts](../episodes/06-conflict.md)
+
+The most important thing to remember here is the second instructor
+**MUST** have opened a PR just like the learners are doing
+and merge this after opening (and after learners have updated their `main`
+branches and created their feature branches).
+They can bypass protections and do this while the first instructor is teaching.
+This generates the citation file conflict the first instructor will point out.
+
+### [History](../episodes/07-history.md)
+
+Users will have covered using `git log` in the intro lesson.
+Show learners what the history of the repository looks like now.
+Then walk through the merge options, keep it short and snappy.
+There are no learner exercises in this episode,
+make sure you ask learners what questions they have at the end.
+
+### [End](../episodes/End.md)
+
+What questions do the learners still have?
+If there is time then maybe with a vote decide what to briefly look at:
+
+- Actions
+- pre-commit
+- Rebasing
+
+## Notes from within Episodes
+
+The following notes are stored within the episode webpages
+and are extracted here for completeness:

md5sum.txt

@@ -15,7 +15,7 @@
 "episodes/End.md" "42f2019c55b38db5ec0eab909b6bca4d" "site/built/End.md" "2025-01-09"
 "episodes/08-rebase.md" "7e00861bac4464ebf12cfac75109cdd6" "site/built/08-rebase.md" "2025-01-09"
 "episodes/09-pre-commit.md" "99096b6d10f4f7c1f6f5bfa72f728e45" "site/built/09-pre-commit.md" "2024-12-02"
-"instructors/instructor-notes.md" "42bb7e13901f84f6569851e10e562c1f" "site/built/instructor-notes.md" "2024-12-03"
+"instructors/instructor-notes.md" "7bc3dcf1fdb97514a50c2d15f7e951df" "site/built/instructor-notes.md" "2025-01-15"
 "learners/discuss.md" "aaef6991af918125ae722d3ce4e36443" "site/built/discuss.md" "2024-11-19"
 "learners/fcm-git_cheat_sheet.md" "a90c25c1218a18430dd67a243e63533e" "site/built/fcm-git_cheat_sheet.md" "2024-11-19"
 "learners/reference.md" "d976a57639fa49361d9c8431850cde6a" "site/built/reference.md" "2024-11-19"