Merge pull request #228 from coding-for-reproducible-research/intro_to_version_control_proofreading

Intro to version control proofreading

Author: liamjberrisford

individual_modules/introduction_to_version_control/collaborating_with_branches.ipynb

@@ -327,6 +327,7 @@
     "`Good-practice-guides` directory (which she includes as a stand-alone commit)\n",
     "and adds the following content about the above feature branch strategy:\n",
     "\n",
+    "```\n",
     "# Best practice for collaboration\n",
     "\n",
     "## A basic feature branch strategy\n",
@@ -338,6 +339,7 @@
     "developed in their own, dedicated *feature branches* that branch off the\n",
     "`main` branch. When the feature is ready to be shared with others, the feature\n",
     "branch is merged back into `main`.\n",
+    "```\n",
     "\n",
     "Like Joe, she then also pushes the new commits on her local\n",
     "`collaboration-good-practice` to the associated remote branch,\n",
@@ -632,7 +634,7 @@
     "\n",
     "* The vertical line represents the `main` branch, that we're currently on. After\n",
     "  the starting commit, there are two more commits, `4e209e9` and `785f6f8`, that\n",
-    "  show where the feature branches where merged into `main` on the remote.\n",
+    "  show where the feature branches were merged into `main` on the remote.\n",
     "\n",
     "* We can see the commit on Joe's feature branch by following the purple line:\n",
     "  the commit is `1d026a8`, where `origin/fetching-material` currently points. (It's\n",

individual_modules/introduction_to_version_control/configuring_git.ipynb

@@ -34,7 +34,7 @@
     "whenever we use Git within a given user account on a specific computer.\n",
     "\n",
     "\n",
-    "### Username and email address\n",
+    "### User-name and email address\n",
     "\n",
     "On a command line, Git commands are written as `git <command> <options>`,\n",
     "where `<command>` is what we actually want to do and `<options>` is additional\n",
@@ -46,10 +46,10 @@
     "$ git config --global user.email \"[email protected]\"\n",
     "```\n",
     "\n",
-    "This user name and email will be associated with your subsequent Git activity,\n",
-    "which means that any changes pushed to GitHub (or another Git host server)\n",
-    "from here on will include this information. If you work on public repositories\n",
-    "with these services, then this information will be publicly visible.\n",
+    "This user-name and email will be associated with your subsequent Git activity\n",
+    "which means that any future changes pushed to GitHub (or another Git host server) \n",
+    "will include this information. If you work on public repositories\n",
+    "with these services then this information will be publicly visible.\n",
     "\n",
     "For this course, we will be interacting with GitHub and\n",
     "so the email address used should be the same as the one used when setting up\n",
@@ -85,7 +85,7 @@
     "\n",
     "The following table shows how to set the default editor for Git for several popular \n",
     "text editors. In some cases, you need to provide the path to the executable\n",
-    "program for the editor — this indicated as `path/to/executable-name` (if you\n",
+    "program for the editor — this is indicated as `path/to/executable-name` (if you\n",
     "aren't sure what to enter for this, do some online searching or try a search\n",
     "on your computer).\n",
     "\n",
@@ -150,7 +150,7 @@
     "You can change your configuration as many times as you want. Use the\n",
     "same commands as above to choose another editor, update your email address, etc.\n",
     "\n",
-    "#### Git Help and Manual\n",
+    "#### Git help and manual\n",
     "\n",
     "Always remember that if you forget the subcommands or options of a `git` command,\n",
     "you can access the relevant list of options typing `git <command> -h`, or\n",
@@ -170,7 +170,7 @@
     "$ git help\n",
     "```\n",
     " \n",
-    "#### On line Endings\n",
+    "#### Line endings\n",
     "\n",
     "You can sometimes run into issues when using Git if you (or your team) use\n",
     "different machines when working on files. If you've followed the default\n",
@@ -215,7 +215,7 @@
     "### Look after your PATs!\n",
     "**You should treat PATs with the same level of care you would your GitHub account password. Store the PAT somewhere secure, such as in a password manager. If you ever suspect a PAT has been exposed, then you should delete the token and generate a new one.**\n",
     "### Note on classic tokens\n",
-    "At the time of writing, GitHub is in the process of creating newer, so-called 'fine  grained' personal access tokens. These provide more fine grained control, but are still in a developmental phase. The older, 'classic', PATs are sufficient forour needs and simpler to set up, so we'll use them throughout this course.\n",
+    "At the time of writing, GitHub is in the process of creating newer, so-called 'fine  grained' personal access tokens. These provide more fine grained control, but are still in a developmental phase. The older, 'classic', PATs are sufficient for our needs and simpler to set up, so we'll use them throughout this course.\n",
     "\n",
     "To set up a PAT, follow the\n",
     "<a href=\"https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic\" target=\"_blank\" rel=\"external noreferrer\">instructions provided by GitHub for classic tokens</a>. Note:\n",

individual_modules/introduction_to_version_control/git_vs_github.ipynb

@@ -11,14 +11,14 @@
     "tags": []
    },
    "source": [
-    "# Git vs Github\n",
+    "# Git vs GitHub\n",
     "\n",
     "## Learning Objectives\n",
     "- Differentiate between Git and GitHub and understand their distinct roles\n",
     "- Learn the basic functionality of Git as a version control system\n",
     "- Understand the concept of terminals and how to use them for Git operations\n",
     "- Explore the additional features provided by GitHub for collaboration and code sharing\n",
-    "- Understand how GitHub supports managing project development and team collaboration \n",
+    "- Understand how GitHub supports project development and team collaboration \n",
     "\n",
     "\n",
     "## Git: our version control system of choice\n",

individual_modules/introduction_to_version_control/history_and_changes.ipynb

@@ -17,7 +17,7 @@
     "- Understand how to view the history of commits in a Git repository using the `git log` command\n",
     "- Learn to navigate through the log output using the paging commands\n",
     "- Use the `gif diff` command to view differences between commits and changes in the working directory\n",
-    "- Differentiate between various states of changes: unstaged, stages and committed\n",
+    "- Differentiate between various states of changes: unstaged, staged and committed\n",
     "- Explore GUI tools for viewing differences in files \n",
     "\n",
     "\n",
@@ -66,7 +66,7 @@
     "\n",
     "The log contains one entry for each commit. The commit messages for the\n",
     "commits are included, as well as details of who made the commit. The name and email address\n",
-    "are those that were given when configuring Git (see the episode Setting up Git and GitHub.\n",
+    "are those that were given when configuring Git (see the episode Setting up Git and GitHub).\n",
     "\n",
     "In addition, each commit has a unique **identifier** associated to it, which is the long\n",
     "random-looking string next to each commit. (The identifiers for your\n",
@@ -196,8 +196,8 @@
     "\n",
     "### Understanding the output of `git diff`\n",
     "The output of `git diff`, as shown above, is cryptic because it is actually a series of commands for tools like editors and `patch` telling them how to reconstruct one file given the other. If we break it down into pieces:\n",
-    "1. The 'diff' for each file begins with a line like `diff --git a/<filename> b/<filename>`. It tells us that Git is producing output similar to the Unix `diff` command, comparing the old and new versions of thefile `<filename>`. In the example above, the output starts with the diff for `Commit-good-practice.md` until just before the line  `diff --git a/Git-cheatsheet.md b/Git-cheatsheet.md`, at which point it switches to the diff for `Git-cheatsheet.md`.\n",
-    "2. The next few lines in each file's diff tell exactly which versions of the file Git is comparing. Confusingly, it looks like it contains commit identifiers, but these are in face different, computer-generated labels for the versions of the files.\n",
+    "1. The 'diff' for each file begins with a line like `diff --git a/<filename> b/<filename>`. It tells us that Git is producing output similar to the Unix `diff` command, comparing the old and new versions of the file `<filename>`. In the example above, the output starts with the diff for `Commit-good-practice.md` until just before the line  `diff --git a/Git-cheatsheet.md b/Git-cheatsheet.md`, at which point it switches to the diff for `Git-cheatsheet.md`.\n",
+    "2. The next few lines in each file's diff tell exactly which versions of the file Git is comparing. Confusingly, it looks like it contains commit identifiers, but these are in fact different, computer-generated labels for the versions of the files.\n",
     "3. The remaining lines, beginning `@@`, are the most interesting: they show us the actual differences and the lines on which they occur. In particular, the `+` marker in the first column shows where we added a line. If we had lines that were removed, these would be marked with `-`.\n",
     "\n",
     "If we wanted to view just the diff for the file `Git-cheatsheet.md` we would\n",
@@ -279,13 +279,13 @@
     "  changes that have been made to `Git-cheatsheet.md` since commit `ad56194`\n",
     "  i.e. the changes required to go from 3 commits earlier to the current commit.\n",
     "\n",
-    "* The command `git diff HEAD~3 HEAD~2` would give the changes required to fo\n",
+    "* The command `git diff HEAD~3 HEAD~2` would give the changes required to get\n",
     "  from commit `HEAD~3` (`ad56194`) to `HEAD~2` (`34c19f2`). In other words, it\n",
     "  just gives the changes applied back when we did commit `34c19f2`.\n",
     "\n",
     "\n",
     "### Exercise\n",
-    "Verify the claims in the three bullet point examples given above, checking the outputs of `git diff` agree for the `HEAD` versions and the regular commit identifier versions. _Note: make sure to use the commit identifiersfound in your own log, not the ones that feature in the example output above!_\n",
+    "Verify the claims in the three bullet point examples given above, checking the outputs of `git diff` agree for the `HEAD` versions and the regular commit identifier versions. _Note: make sure to use the commit identifiers found in your own log, not the ones that feature in the example output above!_\n",
     "\n",
     "\n",
     "## Working tree and staging area diffs\n",
@@ -386,7 +386,7 @@
     "\n",
     "\n",
     "### Exercise\n",
-    "First follow the steps above, so that you end up with entries about `git log` and `git log --oneline` in `Git-cheatsheet.md` that are staged but not committed.Now add a new entry to the cheatsheet about `git log -n`, but don't stage it. Now do the following:\n",
+    "First follow the steps above, so that you end up with entries about `git log` and `git log --oneline` in `Git-cheatsheet.md` that are staged but not committed.Now add a new entry to the cheatsheet about `git log -n`, but don't stage it. Next do the following:\n",
     "* Run `git diff Git-cheatsheet.md`\n",
     "* Run `git status`\n",
     "Can you explain what the output from these commands is saying, and why we get it? Once you're happy you understand what's going on, complete the task of adding the material about `git log` to the cheatsheet by making an appropriate commit, making sure to include the entry about `git log -n`.\n",
@@ -404,7 +404,7 @@
     "For VS Code users, the following links may be of help:\n",
     "* View the diffs for files that have not been staged, or have been staged but not committed <https://code.visualstudio.com/docs/sourcecontrol/overview#_working-in-a-git-repository>.\n",
     "* View the commit history of a file:  <https://code.visualstudio.com/docs/sourcecontrol/overview#_timeline-view>. This also suggests some extensions for VS Code to make working with Git more graphical.\n",
-    "* Displaying diffs by selecting files to compare: <https://code.visualstudio.com/docs/sourcecontrol/overview#_viewing-diffs>. Note that the method described in this link can be used on the 'timeline' described in the previous link: simply right-click on different commits inthe timeline for a given file to see the changes between the commits.\n",
+    "* Displaying diffs by selecting files to compare: <https://code.visualstudio.com/docs/sourcecontrol/overview#_viewing-diffs>. Note that the method described in this link can be used on the 'timeline' described in the previous link: simply right-click on different commits in the timeline for a given file to see the changes between the commits.\n",
     "\n",
     "## Summary Quiz"
    ]

individual_modules/introduction_to_version_control/ignoring_files.ipynb

@@ -17,7 +17,7 @@
     "- Create a `.gitignore` file to specify files and directories that Git should ignore\n",
     "- Understand how to use comments within a `.gitignore` file\n",
     "- Use pathspecs to ignore groups of similar files\n",
-    "- IDentify the types of files that should be typically be ignored in a Git repository\n",
+    "- Identify the types of files that should typically be ignored in a Git repository\n",
     "- Force Git to add ignored files if necessary\n",
     "\n",
     "\n",

individual_modules/introduction_to_version_control/making_repos.ipynb

@@ -116,10 +116,10 @@
     "\n",
     "\n",
     "#### Further options for GitHub repositories\n",
-    "Let's take a moment mention a few extra things about creating repositories on GitHub. None of these points are essential for moving forward, but you'll likely come into contact with them as you use GitHub more:\n",
+    "Let's take a moment to mention a few extra things about creating repositories on GitHub. None of these points are essential for moving forward, but you'll likely come into contact with them as you use GitHub more:\n",
     "* When creating the repository, there was the option to initialise the repository with some extra files:\n",
     "  - A `.gitignore` file. This is a particular file that can be used to tell Git about files that it should _not_ keep a version history for. We will see this later in the course.\n",
-    "  - A licence file. If you intend to make your work publicly available, then it's important to include a licence file which both allows others to use your work and specify the terms for their use. You can read more about this important topic <a href=\"https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository\" target=\"_blank\" rel=\"external noreferrer\">on GitHub</a> and on the <a href=\"https://www.software.ac.uk/resources/guides/choosing-open-source-licence\" target=\"_blank\" rel=\"external noreferrer\">Software Sustainability Institute</a>'s website.\n",
+    "  - A licence file. If you intend to make your work publicly available, then it's important to include a licence file which both allows others to use your work and specifies the terms for its use. You can read more about this important topic <a href=\"https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository\" target=\"_blank\" rel=\"external noreferrer\">on GitHub</a> and on the <a href=\"https://www.software.ac.uk/resources/guides/choosing-open-source-licence\" target=\"_blank\" rel=\"external noreferrer\">Software Sustainability Institute</a>'s website.\n",
     "* If you belong to an _Organisation_ on GitHub and have the correct permissions, then you will be able to create repositories under the organisation instead of your own user account. See GitHub's <a href=\"https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations\" target=\"_blank\" rel=\"external noreferrer\">overview on organisations</a> for more information. \n",
     "\n",
     "\n",

individual_modules/introduction_to_version_control/merge_conflicts.ipynb

@@ -215,7 +215,7 @@
     "\n",
     "\n",
     "### Understanding the representation of conflicts\n",
-    "The content between the markers `<<<<<<< HEAD` and `=======` contains the changes that were made on the current branch i.e. the changes as they are at `HEAD`. In contrast, the content between the markers `=======` and `>>>>>>> main` represents the changes that have been made on the incoming branch, which in example above is `main`. (Of course, in the general case the incoming branch could be a different branch, in which case the name of this branch will be used in the third marker.)\n",
+    "The content between the markers `<<<<<<< HEAD` and `=======` contains the changes that were made on the current branch i.e. the changes as they are at `HEAD`. In contrast, the content between the markers `=======` and `>>>>>>> main` represents the changes that have been made on the incoming branch, which in the example above is `main`. (Of course, in the general case, the incoming branch could be a different branch, in which case the name of this branch will be used in the third marker.)\n",
     "\n",
     "\n",
     "In order to fix this conflict, we simply need to edit this text so that it contains\n",

individual_modules/introduction_to_version_control/motivation.ipynb

@@ -17,7 +17,7 @@
     "- Describe what version control systems (VCS) are and their purpose\n",
     "- Understand the key benefits of using version control systems for individual and collaborative work\n",
     "- Differentiate between version control systems and other file synchronisation methods\n",
-    "- Learn about the common challenges address by version control systems in managing file versions\n",
+    "- Learn about the common challenges addressed by version control systems in managing file versions\n",
     "- Recognize the importance of version control systems in maintaining an organised project history and facilitating collaboration \n",
     "\n",
     "\n",

individual_modules/introduction_to_version_control/pushing_and_pulling.ipynb

@@ -11,7 +11,7 @@
     "tags": []
    },
    "source": [
-    "# Pushing to and Pulling From the Remote Repository\n",
+    "# Pushing To and Pulling From the Remote Repository\n",
     "\n",
     "## Learning objectives\n",
     "- Understand the purpose and process of pushing changes from a local Git repository to a remote repository on GitHub\n",

individual_modules/introduction_to_version_control/questions/summary_collaborating_with_branches.json

@@ -1,6 +1,6 @@
 [
     {
-        "question": "What is the main advantage of using feature brnaching in collaborative development?",
+        "question": "What is the main advantage of using feature branching in collaborative development?",
         "type": "many_choice",
         "answers": [
             {