Review of episodes 3 - 4: Version Control and Code Readability

episodes/03-version-control.md

@@ -42,7 +42,7 @@
 in time. This is incredibly useful if we want to reproduce results from a
 specific version of the code, or track down changes that broke some functionality.
 
-The other benefit we gain is that version control provides us with provenance of
+The other benefit we gain is that version control provides us with the provenance of
 the project. As we make each change, we also leave a message about what the
 change was and why it was made. This improves the transparency of the project and
 makes it auditable, which is good scientific practice.
@@ -149,7 +149,7 @@
 To get it to do that, we need to run one more command:
 
 ```bash
-$ git commit -m "Add and example script and dataset to work on"
+$ git commit -m "Add an example script and dataset to work on"
 ```
 
 ```output
@@ -168,7 +168,7 @@
 If we only run `git commit` without the `-m` option, Git will launch a text editor so that we can write a longer message.
 
 Good commit messages start with a brief (<50 characters) statement about the changes made in the commit.
-Generally, the message should complete the sentence "If applied, this commit will".
+Generally, the message should complete the sentence "If applied, this commit will...".
 If you want to go into more detail, add a blank line between the summary line and your additional notes.
 Use this additional space to explain why you made changes and/or what their impact will be.
 
@@ -203,7 +203,7 @@
 as part of the filename, and not a separate argument.
 However, it is pretty annoying and considered bad practice to have spaces in your filenames like this, 
 especially if you will be manipulating them from the terminal.
-So let's go ahead and remove the space from the filename altogether and replace it with a hyphen instead.
+So, let's go ahead and remove the space from the filename altogether and replace it with a hyphen instead.
 You can use the `mv` command again like so:
 
 ```bash
@@ -269,7 +269,7 @@
 
 ### Advanced solution
 
-We initially renamed the Python file using the `mv` command, and we than had to add *both* `my-code-v2.py` 
+We initially renamed the Python file using the `mv` command, and we than had to `git add` *both* `my-code-v2.py` 
 and `my\ code\ v2.py`.
 Alternatively, we could have used Git's own `mv` command like so:
 
@@ -308,8 +308,7 @@
 We have already met the concept of commit messages when we made and stored changes to our code files. 
 Commit messages are short descriptions of, and the motivation for, what a commit will achieve. 
 It is therefore important to take some time to ensure these commit messages are helpful and descriptive, 
-as when work is reviewed (by your future self or a collaborator) they provide the context of what change
-was made and why. 
+as when work is reviewed (by your future self or a collaborator) they provide the context about what changes were made and why. 
 This can make tracking down specific changes in commits much
 easier, without having to inspect the code or files themselves.
 
@@ -376,7 +375,7 @@
 
 ### Understanding commit contents
 
-Below are the `diff`s of two commits. A `diff` shows the differences in a file (or files!) compared to the previous 
+Below are the `diffs` of two commits. A `diff` shows the differences in a file (or files!) compared to the previous 
 commit in the history so you can what has changed. 
 The lines that begin with `+`s represent additions, and the lines that begin with `-`s represent deletions. 
 Compare these two commit `diff`s. 
@@ -384,9 +383,13 @@
 How many changes have they tried to make in each commit? 
 Discuss in pairs or small groups.
 
 1. ![Example Diff 1](fig/ex-diff-1.png)
 2. ![Example Diff 2](fig/ex-diff-2.png)
 
+
+To find out more about how to generate `diffs`, you can read the [Git documentation](git-diff-docs) or the [Tracking Changes episode][swc-git-lesson-track]
+from the [Software Carpentry Version control with Git lesson][swc-git-lesson].
+
 :::  solution
 
 ### Solution
@@ -442,10 +445,10 @@
   deciding to discard some work.
 - [`git reset`](https://git-scm.com/docs/git-reset): This command will recover
   the state of the project at the specified commit. What is done with the commits
-  you had made is defined by some optional flags:
-  - `--soft`: Any changes you had made would be preserved and left as "Changes to be committed"
-  - `--mixed`: Any changes you had made would be preserved but not marked for commit (this is the default action)
-  - `--hard`: All changes you had made are discarded
+  you had mave since is defined by some optional flags:
+  - `--soft`: Any changes you have made since the specified commit would be preserved and left as "Changes to be committed"
+  - `--mixed`: Any changes you have made since the specified commit would be preserved but not marked for commit (this is the default action)
+  - `--hard`: Any changes you have made since the specified commit are discarded
   Using this command produces a "cleaner" history, but does not tell the full
   story and your work.
 
@@ -461,7 +464,7 @@
 Git to push our projects and histories to a server (someone else's computer) so
 that they are accessible and retrievable if the worst were to happen to our
 machines. 
-Distributing our projects in this way also opens us up to collaboration
+Distributing our projects in this way also opens us up to collaboration,
 since colleagues would be able to access our projects, make their own copies on
 their machines, and conduct their own work.
 
@@ -473,20 +476,20 @@
 2. In the top right hand corner of the screen, there is a menu labelled "+" with
    a dropdown. Click the dropdown and select "New repository" from the options.
 
    ![*Creating a new GitHub repository*](fig/ep03_fig01-create_new_repo.jpg){ alt-text="Selecting the 'New repository' option from GitHub's dropdown menu" .image-with-shadow }
 
 3. You will be presented with some options to fill in or select while creating
    your repository. In the "Repository Name" field, type "spacewalks". This is
    the name of your project and matches the name of your local folder.
 
    ![*Naming the GitHub repository*](fig/ep03_fig02-repository_name.png){ alt-text="Setting the name of the repository on GitHub" .image-with-shadow }
 
    Ensure the visibility of the repository is "Public" and leave all other options
    blank. Since this repository will be connected to a local repository, it needs
    to be empty which is why we don't initialise with a README or add a license or
    `.gitignore` file. Click "Create repository" at the bottom of the page.
 
    ![*Complete GitHub repository creation*](fig/ep03_fig03-create_repository.jpg){ alt-text="Completing the creation of the GitHub repository" .image-with-shadow }
 
 4. Now you have created your repository, you need to send the files and the history
    you have stored on your local computer to GitHub's servers. GitHub provides
@@ -504,7 +507,7 @@
    squares to the right-hand side of the commands. Paste them into your terminal
    and run them.
 
    ![*Copy the commands to sync the local and remote repositories*](fig/ep03_fig04-copy_commands.jpg){ alt-text="Copying the commands to sync the local and remote repositories" .image-with-shadow }
 
 5. If you refresh your browser window, you should now see the two files `my-code-v2.py`
    and `data.json` visible in
@@ -545,7 +548,7 @@
 The `git push` command is used to update remote references with any changes you
 have made locally. This command tells Git to update the "main" branch on the
 "origin" remote. The `-u` flag (short for `--set-upstream`) will set a tracking
-reference, so that in the future only `git push` can be run without the need to
+reference, so that in the future `git push` can be run without the need to
 specify the remote and reference name.
 
 :::  challenge