Add remaining episodes as rough drafts

steve-crouch · steve-crouch · commit 75cc7c05a428 · 2025-03-05T11:14:07.000Z
diff --git a/config.yaml b/config.yaml
@@ -86,6 +86,18 @@ episodes:
 - 34-pull-request.md
 - 35-merge-pr.md
 - 36-merge-conflicts.md
+- 40-introduction.md
+- 41-setup.md
+- 42-example-code.md
+- 43-repo-issue-fixing.md
+- 44-create-pull-request.md
+- 45-review-pull-request.md
+- 46-merge-pull-request.md
+- 50-introduction.md
+- 51-setup.md
+- 52-example-code.md
+- 53-create-new-test.md
+- 54-handling-errors.md
 
 # Information for Learners
 learners: 
diff --git a/episodes/10-introduction.md b/episodes/10-introduction.md
@@ -1,5 +1,5 @@
 ---
-title: "Lesson 1: Introduction to Integrated Development Environments"
+title: "Lesson 1: Integrated Development Environments"
 teaching: 15
 exercises: 0
 ---
diff --git a/episodes/12-running-vscode.md b/episodes/12-running-vscode.md
@@ -78,7 +78,7 @@ Then select `Mark done`, and close the welcome windows.
 
 ## A Sample Project
 
-FIXME: copy code-style-example to softwaresaved's organisation
+FIXME: copy code-style-example repo to softwaresaved's organisation
 
 Next, let’s obtain some example Python and edit it from within VSCode.
 So first, you can download the example code we'll use from https://github.com/UNIVERSE-HPC/code-style-example/releases/tag/v1.0.0, either as a `.zip` or `.tar.gz` compressed archive file.
diff --git a/episodes/22-example-code.md b/episodes/22-example-code.md
@@ -18,6 +18,8 @@ exercises: 0
 
 ## Obtaining Some Example Code
 
+FIXME: copy code-style-example into softwaresaved org
+
 Open a shell
 On own machine: open terminal with a bash shell
 Using the shell, we’re going to use Git to clone our example GitHub code repository
diff --git a/episodes/32-example-code.md b/episodes/32-example-code.md
@@ -18,6 +18,8 @@ exercises: 0
 
 ## Creating a Copy of the Example Code Repository
 
+FIXME: copy git-example repo into softwaresaved
+
 So the first thing we need to do is create a new GitHub repository from a template repository
 So first go to https://github.com/UNIVERSE-HPC/git-example [copy and paste]
 Select ‘Use this template’ -> Create a new repository
@@ -53,7 +55,7 @@ the problem would also become compounded if other developers came on board, perh
 what would be nice, would be to have our cake and eat it, so to speak
 where we can change our code using version control to track our changes,
 but not interfere with our working code on the main branch
-and as we’ve heard from Jeremy, repository branches can give us just that
+Fortunately, repository branches can give us just that
 
 ## Create Example Issues
 
diff --git a/episodes/40-introduction.md b/episodes/40-introduction.md
@@ -0,0 +1,21 @@
+---
+title: "Lesson 4: Code Review"
+teaching: 15
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## 
+
+## 
diff --git a/episodes/41-setup.md b/episodes/41-setup.md
@@ -0,0 +1,21 @@
+---
+title: "4.1 Setup"
+teaching: 10
+exercises: 2
+---
+
+## Setup
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+
diff --git a/episodes/42-example-code.md b/episodes/42-example-code.md
@@ -0,0 +1,33 @@
+---
+title: "4.2 Some Example Code"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Creating a Copy of the Example Code Repository
+
+FIXME: copy review-example repo into softwaresaved org
+
+So the first thing we need to do is create a new GitHub repository from a template repository
+So first go to https://github.com/UNIVERSE-HPC/review-example [copy and paste]
+Select ‘Use this template’ -> Create a new repository
+Set owner and repo name (e.g. git-example), ensure it’s set to public, Create
+
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
diff --git a/episodes/43-repo-issue-fixing.md b/episodes/43-repo-issue-fixing.md
@@ -0,0 +1,70 @@
+---
+title: "4.3 Fixing a Repository Issue"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Adding an Issue to the Repository
+
+Next thing to do is to add an issue to the repository
+Which will represent something we need to work on
+For the sake of this exercise, it doesn't really matter what the issue is
+But perhaps we've spotted a problem with our codebase during development, and we need to note this problem needs to be fixed
+
+For example, if we look at the README for the repo, we can see there's a broken link
+Clearly a problem, so let's register that as an issue
+Select “Issues”, then “New issue”
+Title: Broken link to article
+Description: The README link to the SSI website article is broken, resulting in a page not found error
+Select “Submit new issue”
+Have opportunity to assign someone to the issue - let's say me
+And also assign what type of issue it is
+It's a problem with the README, so that's probably documentation, so let's set it as that
+
+QUESTION: who’s been able to create a new issue on the repository? Yes/No
+
+## Fixing the Issue
+
+Now the next thing, is perhaps a bit later on, we decide to fix the issue
+So we navigate to the README (go to repository main page)
+And here, for the sake of the exercise, we'll just use GitHub's edit mechanism to edit the file directly
+Alternatively, and in most cases, we'd probably do this by having the repository cloned on our machine, and then we'd make the change, and submit it that way
+But in the interests of time and simplicity, we'll just use GitHub's edit function
+So select the edit icon
+And edit the README to fix the link (remove the bit that says “typo/“)
+
+So we now need to commit the change, so we now select “Commit changes” in the top right
+Good practice when committing a change is to refer to the issue number in the commit message
+This gives us traceability for changes back to the originating issue
+We had our issue number 1, so let's refer to that
+#1 - Fix broken article link
+We could optionally put more info about the fix in the description if we wanted
+
+Now importantly, we want to submit this change as a pull request on a new branch
+This will allow others to review that pull request
+Selecting the second option here allows us to create a new branch for these changes
+And we can give this new branch an identifiable name
+readme-broken-link-fix
+
+Once we select propose changes, this change is submitted and our new branch, with that fix, is created
+And scrolling down, we can see our change highlighted
+
+QUESTION: who’s managed to commit their fix to a new branch? Yes/No
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
diff --git a/episodes/44-create-pull-request.md b/episodes/44-create-pull-request.md
@@ -0,0 +1,49 @@
+---
+title: "4.4 Submiting a Pull Request"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Creating a Pull Request
+
+But - we still need to submit this new branch and the commit we made as a pull request
+And GitHub nicely guides us to doing this
+Select “Create pull request”
+
+Once we've done that, we can see that our pull request has been opened
+And is ready for consideration to be merged into the codebase
+For information, we can see that GitHub is aware that the change we've committed can be merged directly - without conflicts - into our main branch
+We could optionally add more info about this pull request here in comments if we wanted
+
+QUESTION: who’s been able to create a new pull request? Yes/No
+
+::::::::::::::::::::::::::::::::::::: challenge
+
+## Swap Repository with Someone Else
+
+For the next stage, you'll be reviewing a pull request. Either:
+
+- If you are attending a workshop with other learners,
+the instructor will enable you to swap the URL of your repository with the repository URL of another learner so you can review the pull request they made on their own repository.
+- If you are going through this material on your own,
+you can review the pull request you made on your own repository instead.
+
+:::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
diff --git a/episodes/45-review-pull-request.md b/episodes/45-review-pull-request.md
@@ -0,0 +1,79 @@
+---
+title: "4.5 Reviewing a Pull Request"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+Let's now adopt a new role - that of the reviewer of a pull request (or PR for short).
+Let's assume that a colleague has created a pull request of his own, for the purposes of this exercise, it's on their own repository
+But it could be a shared repository we are both working on
+In a collaborative environment, this is mostly likely going to be the case
+So let's take a look at it and review it
+
+## Write a Review of the PR
+
+So we open the repo URL link in a browser, and go to “Pull requests” on the repo main page
+Then select the pull request
+To review the request's changes, we can go to 'Files changed' - one of the tabs
+Which perhaps unsurprisingly, shows us the changes in each file, in this case just one file, and one change
+The view on the left (in red) is the old version, and the view on the right (in green), is the revised version of the line change
+
+We have the option of adding comments or suggestions inline to the proposed changes, if we want
+For example, perhaps we know there is a Zenodo record for the code that this article points to, which we think should be added
+By hovering over a line and selecting the '+' symbol at the start of the line
+And adding a comment
+So select the changed line, and add something like
+We should also link to the Zenodo record for the code that this article links to, at https://zenodo.org/record/250494#.Y2UUN-zP1R4
+Then selecting 'Start a review'
+Can add as many comments as we want
+If this were a larger pull request, we would review the other changes, and add comments as needed
+
+So let's assume we've done that
+
+Finally, as a reviewer of this pull request, we “Finish our review”
+We can add a comment, maybe with some high-level observations or suggestions
+Overall, the changes look good, although we should consider adding the Zenodo repository link.
+
+And then we can select whether (three options here)
+Comment - we can just leave a comment to consider
+Approve - the pull request is approved as is
+Request changes - there are some aspects that must be addressed before it can be merged
+For simplicity, let's just go with the first option for this exercise
+
+::::::::::::::::::::::::::::::::::::: callout
+
+## The `Approve` and `Request changes` options are unavailable!
+
+If you're following through the material on your own,
+and have reviewed your own pull request,
+you'll notice that the `Approve` and `Request changes` options are not available.
+This is because GitHub does not allow users to approve their own pull requests.
+The reason for this is that it goes against the reason behind pull requests - to have others review your changes, and in a usual team environment, you'd ask a colleague (or colleagues) to do a review.
+
+GitHub still allows you to submit a review to your PRs with comments however,
+so for the purposes of this training feel free to select the `Comment` option instead.
+
+:::::::::::::::::::::::::::::::::::::
+
+So then submit the review, and our role as reviewer on the pull request is complete
+The other participant can then take our review into account, when deciding whether to merge that pull request
+
+QUESTION: Who’s submitted a very brief code review? Yes/No
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
diff --git a/episodes/46-merge-pull-request.md b/episodes/46-merge-pull-request.md
@@ -0,0 +1,48 @@
+---
+title: "4.6 Merge the Pull Request"
+teaching: 10
+exercises: 0
+---
+
+:::::::::::::::::::::::::::::::::::::: questions 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: objectives
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Read Review and Merge the Pull Request
+
+Now - final step
+Back to our role as contributor...
+We created our own pull request, that hopefully another participant (or ourselves) has reviewed
+
+Let's take a look, by going back to our repository, and looking at our own pull request, and looking at the review
+We should now consider the review, and any observations or suggestions made
+At this point, we could go ahead and make any needed changes
+But, for simplicity, and assuming their review is positive (and they don't suggest more changes are required)
+We can go ahead and merge the pull request into our codebase
+By selecting 'Merge pull request’, and then “Confirm Merge”
+
+So now, our change has been integrated into our codebase
+
+QUESTION: Who’s read the other participants’ review of their PR, and merged it? Yes/No
+
+## Housekeeping
+
+But - there's a bit of housekeeping we should do
+The pull request branch is no longer needed, everything's been merged
+So let's keep a tidy repository and delete the branch
+If we go to our repo's main page, and select 'branches'
+We can delete our pull request branch
+
+::::::::::::::::::::::::::::::::::::: keypoints 
+
+- FIXME
+
+::::::::::::::::::::::::::::::::::::::::::::::::
diff --git a/episodes/50-introduction.md b/episodes/50-introduction.md
diff --git a/episodes/51-setup.md b/episodes/51-setup.md
diff --git a/episodes/52-example-code.md b/episodes/52-example-code.md
diff --git a/episodes/53-create-new-test.md b/episodes/53-create-new-test.md
diff --git a/episodes/54-handling-errors.md b/episodes/54-handling-errors.md
