various day 1 updates

content/browsing.md

@@ -1,14 +1,15 @@
 # Copy and browse an existing project
 
-The first thing most people do is **contribute to an existing
-project**.  This, and following lessons, go over this.  We use an
-an example recipe book on GitHub.
+In this episode, we will look at an existing repository to
+understand how all of pieces work.  Along the way, we will make a copy
+(a {term}`fork`) of the {term}`repository` for us, which will be used for our
+own changes in the next episode.
 
 :::{objectives}
 * See a real git repository and understand what is inside of it.
 * Understand how version control allows advanced inspection of a
   repository.
-* See how git allows multiple people to take collaborate.
+* See how git allows multiple people to collaborate easily.
 :::
 
 :::{instructor-note}
@@ -19,9 +20,6 @@ Preparation:
 - Create one or two issues
 - Create one or two pull requests
 - Try to search for something in the recipe to trigger a search index update
-
-Before starting the exercise session:
-- Show how to fork the repository to own account
 :::
 
 ```{highlight} console
@@ -37,53 +35,27 @@ We will add to this page:
 - summary
 
 
+
 ## Introduction
 
-* You will probably interact with more repositories owned by other
-  people than with your own
-* It's easier to get to know your own repositories
+* We used to start by directly going and creating a repository.  This
+  was abstract and hard to understand.
+* Instead, we'll show you all the cool stuff in a git repository
+  first, and then start adding files.
+* We use an example recipe book we created just for this course.
+* By the end of the course, you'll know how to contribute your own
+  recipes to it.
 
 
-## Exercise
 
-Work on this by yourself.  The solution below goes over most of the
-answers, but the hints should get you most of the way.  Refer to the
-solution if you get stuck.
+## GitHub, VS Code, Command line, and more
 
 We offer **three different flows** of how to do this exercise.  For
 the CodeRefinery workshop day 1, we use and demonstrate the **GitHub
 flow** only and recommend you do that.
 
-:::{exercise} Exercise: Browsing an existing project (25 min)
-First **make a copy** to your own account to work on **by forking**
-<https://github.com/coderefinery/recipe-book>
+In the future we'll add more flows, for example Jupyter and RStudio.
 
-Then browse the project and explore commits and branches. Take notes and prepare questions.
-
-1. Browse the commit history: Are commit messages understandable?
-   (Hint: "Commit history" (like "25 commits") above the file list.)
-1. Compare the commit history with the network graph ("Insights" -> "Network"). Can you find the branches?
-1. How can you find out when a recipe was last modified?
-1. How many changes did the Guacamole recipe receive (you find it under "sides")?
-   Try to click on some of the commits to see what changed.
-   (Hint: "History" in the view of a single file.)
-1. Which recipes include the ingredient "salt"?
-   (Hint: the GitHub search.  From the repository view, it should offer
-   the filter "repo:coderefinery/recipe-book" by default.  What if you
-   add a search term?)
-1. In the Guacamole recipe, find out who modified each line last and when
-   (click on file, then click "Blame" button). Find out who added the cilantro
-   and in which commit.
-   (Hint: "Blame" view in the file view)
-1. How many people have contributed to the repository?
-   (Hint: under "Insights")
-1. Can you use these recipes yourself? Are you allowed to share
-   modifications?
-   (Hint: look for a license file)
-1. Browse issues and pull requests, any idea what these might be good
-   for?
-   (Hint: tabs in the repository view)
-:::
 
 
 ## Setup
@@ -92,22 +64,28 @@ Then browse the project and explore commits and branches. Take notes and prepare
 
 In the CodeRefinery workshop itself, we follow the **GitHub** flow.
 **VS Code** and **Command line** are for reference, for people who
-already know enough to follow.  They do not have full information and
-screenshots, and may not be complete.
+already know these tools.  They do not have full information and
+screenshots, and may not be complete yet.
 :::
 
-First, we need to make our own copy of the repository.  This will
-become important later, when we make our own changes.
+First, we need to make our own copy of the repository.
+This will become important later, when we make our own changes.
+
+1. Go to the repository view on GitHub: <https://github.com/coderefinery/recipe-book>
+1. First, on GitHub, click the button that says "Fork".  It is towards
+   the top-right of the screen.
+1. You should shortly be redirected to your copy of the repository.
 
-1. Go to the repository view on GitHub (everyone should do this,
-   regardless of which flow you are using): <https://github.com/coderefinery/recipe-book>
-1. First, on GitHub, click the button that says "Fork".
-1. TODO.
+At all times you should be aware of if you looking at *your* repository
+or the *CodeRefinery {term}`upstream`*.
+* Your repository: https://github.com/**USERNAME**/recipe-book
+* CodeRefinery repository: https://github.com/**coderefinery**/recipe-book
 
 :::::{tabs}
 ::::{group-tab} GitHub
-You only need to open your own view.  The browser URL should look like
-`https://github.com/USER/recipe-book`, where `USER` is your GitHub username.
+You only need to open your own view, as described above.  The browser
+URL should look like `https://github.com/USER/recipe-book`, where
+`USER` is your GitHub username.
 ::::
 
 ::::{group-tab} VS Code
@@ -136,7 +114,8 @@ We need to start by making a copy of this repository locally.
 1. Start the terminal in which you use git (Terminal application, or
    Git-Bash).
 1. Change to the directory where you would want the repository to be
-   (`cd code` for example)
+   (`cd ~/code` for example, if the `~/code` directory is where you
+   store your files).
 1. Run the following command: `git clone
    https://github.com/USER/recipe-book`, where `USER` is your
    username.  You might need to use a SSH clone command instead of
@@ -146,7 +125,53 @@ We need to start by making a copy of this repository locally.
 :::::
 
 
-## Solution
+## Exercise
+
+Work on this by yourself or in your team.
+
+:::{instructor-note}
+Before starting the exercise session:
+- Make sure you have shown how to fork the repository to own account
+  (above).
+:::
+
+:::{exercise} Exercise: Browsing an existing project (25 min)
+
+Then browse the project and explore commits and branches. Take notes and prepare questions.
+
+1. Browse the commit history: Are commit messages understandable?
+   (Hint: "Commit history" (like "25 commits") above the file list.)
+1. Compare the commit history with the network graph ("Insights" -> "Network"). Can you find the branches?
+1. How can you find out when a recipe was last modified?
+1. How many changes did the Guacamole recipe receive (you find it under "sides")?
+   Try to click on some of the commits to see what changed.
+   (Hint: "History" in the view of a single file.)
+1. Which recipes include the ingredient "salt"?
+   (Hint: the GitHub search.  From the repository view, it should offer
+   the filter "repo:coderefinery/recipe-book" by default.  What if you
+   add a search term?)
+1. In the Guacamole recipe, find out who modified each line last and when
+   (click on file, then click "Blame" button). Find out who added the cilantro
+   and in which commit.
+   (Hint: "Blame" view in the file view)
+1. How many people have contributed to the repository?
+   (Hint: under "Insights")
+1. Can you use these recipes yourself? Are you allowed to share
+   modifications?
+   (Hint: look for a license file)
+1. Browse issues and pull requests, any idea what these might be good
+   for?
+   (Hint: tabs in the repository view)
+:::
+
+
+The solution below goes over most of the answers, and you are
+encouraged to use it when the hints aren't enough - this is by
+design.
+
+
+
+## Solution and walk-through
 
 ### (1) Basic browsing
 
@@ -248,7 +273,8 @@ According to the view above, it seems to have five changes (as of
 ### (5) Which recipes include the ingredient "salt" ?
 
 Version control makes it very easy to find all occurrences of a single
-word.  This is useful for things like tracing through code
+word.  This is useful for things like finding where things are
+defined.
 
 :::::{tabs}
 ::::{group-tab} GitHub
@@ -347,7 +373,7 @@ repository, the one of "CodeRefinery" (not your fork):
 <https://github.com/coderefinery/recipe-book>.  Issues and Pull
 Requests are different for each GitHub copy.
 
-* Click on the Issues" tab.  These are notes that people have added,
+* Click on the "Issues" tab.  These are notes that people have added,
   which allow discussion about the project.
 * Click on the "Pull requests" tab.  This allows anyone to *propose
   changes*, but only the repository owners can accept.

content/commits.md

@@ -20,6 +20,16 @@ Before starting the exercise session:
 ```{highlight} console
 ```
 
+We will add to this page:
+- intro
+- screenshots
+- tab on how to do this locally
+- hints
+- solution
+- discussion
+- summary
+
+
 
 ## Background
 
@@ -44,17 +54,13 @@ Make sure that you work now **on your fork** of the recipe-book repository.
 1. Try to rename the branch that you created and then browse the network again.
 :::
 
-We will add to this page:
-- intro
-- screenshots
-- tab on how to do this locally
-- hints
-- solution
-- discussion
-- summary
+The solution below goes over most of the answers, and you are
+encouraged to use it when the hints aren't enough - this is by
+design.
+
 
 
-## Solution
+## Solution and walk-through
 
 ### (1) Create a branch and add recipe to the branch
 

content/merging.md

@@ -2,10 +2,10 @@
 
 When different people do different things at the same time, it means we
 have to somehow combine the changes later.  This part goes over that
-**merging**.
+{term}`merging`.
 
 :::{objectives}
-* Understand that merging is done throguh **pull requests** (= change proposal).
+* Understand that merging is done through a {term}`pull request` (= change proposal).
 * Create and merge a pull request within your own repository.
 * Understand (and optionally) do the same for the main public repository.
 :::
@@ -18,10 +18,34 @@ Before starting the exercise session:
 ```{highlight} console
 ```
 
+We will add to this page:
+- intro
+- screenshots
+- tab on how to do this locally
+- hints
+- solution
+- discussion
+- summary
+
+
+
+## Background
+
+* In the last episode, we added a new recipe on a branch.  This allows
+  us to test it before it becomes "live".
+* Now, we want to bring that change into the "main" branch.
+* We find it's not that hard!  But you do have to keep track of the
+  steps and make sure that you work very precisely.
+
+
 
 ## Terminology
 
 * {term}`upstream`: The original repository from where your code comes
+* {term}`pull request`
+* {term}`merge`
+
+
 
 ## Exercise
 
@@ -37,6 +61,9 @@ some GitHub-specific notes, but most is possibly with any flow.
 :::::{tabs}
 ::::{group-tab} GitHub
 
+First, we make something called a {term}`pull request`, which allows
+review and commenting before the actual merge.
+
 :::{exercise} Exercise: Merging branches with pull requests (20 min)
 We assume that in the previous exercise you have created a new branch
 with a recipe.  In our previous example, it is called `new-recipe`.
@@ -79,7 +106,8 @@ As usual, this is basic hints.  You should refer to the solution as needed.
 ::::{group-tab} Local (VS Code, Command line)
 
 When working locally, it's easier to merge branches: we can just do
-the merge, without making a pull request.
+the merge, without making a pull request.  But we don't have that step
+of review and commenting.
 
 :::{exercise}
 
@@ -96,30 +124,16 @@ Then:
    upstream repository.  *This is very complex right now since your
    change has to get to GitHub, and we haven't shown that yet.  We
    don't give a solution for this.*
-
-
 :::
 
 ::::
-
 :::::
-Demo:
-- conflict
-- delete branches
-- create release (or optional exercise step)
-
-We will add to this page:
-- intro
-- screenshots
-- tab on how to do this locally
-- hints
-- solution
-- discussion
-- summary
 
+The solution below goes over most of the answers, and you are
+encouraged to use it when the hints aren't enough - this is by design.
 
 
-## Solution
+## Solution and walk-through
 
 ### (1) Navigate to your branch
 
@@ -238,6 +252,12 @@ a recipe to everyone.
 :::::
 
 
+## Demo: resolving a conflict
+
+## Demo: deleting a branch
+
+## Demo: create a release
+
 
 ## Discussion