Merge pull request #390 from UBC-DSCI/collab-edits

Copyediting for version control

Author: leem44

version-control.Rmd

@@ -33,19 +33,19 @@ we will cover the Jupyter Git interface.
 
 ## Chapter learning objectives
 
-By the end of the chapter, readers will be able to:
-
-- Describe what version control is and why data analysis projects can benefit from it
-- Create a remote version control repository on GitHub
-- use Jupyter's Git version control tools for project versioning and collaboration: 
-  - clone a remote version control repository to create a local repository
-  - commit changes to a local version control repository
-  - push local changes to a remote version control repository
-  - pull changes from a remote version control repository to a local version control repository
-  - resolve merge conflicts
-- Give collaborators access to a remote GitHub repository
-- Communicate with collaborators using GitHub issues
-- Use best practices when collaborating on a project with others
+By the end of the chapter, readers will be able to do the following:
+
+- Describe what version control is and why data analysis projects can benefit from it.
+- Create a remote version control repository on GitHub.
+- Use Jupyter's Git version control tools for project versioning and collaboration: 
+  - Clone a remote version control repository to create a local repository.
+  - Commit changes to a local version control repository.
+  - Push local changes to a remote version control repository.
+  - Pull changes from a remote version control repository to a local version control repository.
+  - Resolve merge conflicts.
+- Give collaborators access to a remote GitHub repository.
+- Communicate with collaborators using GitHub issues.
+- Use best practices when collaborating on a project with others.
 
 ## What is version control, and why should I use it?
 
@@ -57,7 +57,7 @@ made to the analysis, projects tend to become messy.
 This mess can have serious, negative repercussions on an analysis project, 
 including interesting results files that your code cannot reproduce,
 temporary files with snippets of ideas that are forgotten or 
-not easy to find, mind-boggling filenames that make it unclear which is
+not easy to find, mind-boggling file names that make it unclear which is
 the current working version of the file (e.g., `document_final_draft_final.txt`, 
 `to_hand_in_final_v2.txt`, etc.), and more. 
 
@@ -66,7 +66,7 @@ means that most of the time, the final version of the analysis that is
 shared with the audience is only a fraction of what was explored during 
 the development of that analysis. 
 Changes in data visualizations and modeling approaches, 
-as well as some negative results are often not observable from 
+as well as some negative results, are often not observable from 
 reviewing only the final, polished analysis.
 The lack of observability of these parts of the analysis development
 can lead to others repeating things that did not work well, 
@@ -107,16 +107,16 @@ discuss issues and bugs, and distribute your final product.
 For both of these items, there is a wide variety of choices.
 In this textbook we'll use Git for version control, 
 and GitHub for repository hosting, 
-because both are currently the most widely-used platforms.
+because both are currently the most widely used platforms.
 In the 
-[additional resources section at the end of the chapter](vc-add-res)
+additional resources section at the end of the chapter,
 we list many of the common version control systems 
 and repository hosting services in use today.
 
 > **Note:** Technically you don't *have to* use a repository hosting service. 
 > You can, for example, version control a project
-> that is stored only in a folder on your computer - 
-> never sharing it on a repository hosting service. 
+> that is stored only in a folder on your computer—never 
+> sharing it on a repository hosting service. 
 > But using a repository hosting service provides a few big benefits, 
 > including managing collaborator access permissions,
 > tools to discuss and track bugs, 
@@ -128,7 +128,7 @@ and repository hosting services in use today.
 
 ## Version control repositories
 
-Typically when we put a data analysis project under version control, 
+Typically, when we put a data analysis project under version control, 
 we create two copies of the repository \index{repository} (Figure \@ref(fig:vc1-no-changes)). 
 One copy we use as our primary workspace where we create, edit, and delete files.
 This copy is commonly referred to as \index{repository!local} the **local repository**. The local
@@ -154,7 +154,7 @@ a version of the project.  These records are \index{git!commit} called **commits
 are a snapshot of the file contents as well
 metadata about the repository at that time the record was created (who made the
 commit, when it was made, etc.). In the local and remote repositories shown in
-Figure \@ref(fig:vc1-no-changes), there are two commits represented as grey
+Figure \@ref(fig:vc1-no-changes), there are two commits represented as gray
 circles.  Each commit can be identified by a 
 human-readable **message**, which you write when you make a commit, and a
 **commit hash** that Git automatically adds for you.  
@@ -177,7 +177,7 @@ two of these shortened hashes, one for each commit: `Daa29d6` and `884c7ce`.
 
 ## Version control workflows
 
-When you work in a local version controlled repository, there are generally three additional
+When you work in a local version-controlled repository, there are generally three additional
 steps you must take as part of your regular workflow. In addition to 
 just working on files—creating,
 editing, and deleting files as you normally would—you must:
@@ -240,7 +240,7 @@ you need \index{git!push} to **push** (i.e., send) those commits back to GitHub
 the history in the remote repository (i.e., GitHub) to match what you have in your 
 local repository. Now when collaborators interact with the remote repository, they will be able
 to see the changes you made. And you can also take comfort in the fact that your work is now backed 
-up on the cloud!
+up in the cloud!
 
 ```{r vc5-push, fig.cap = 'Pushing the commit to send the changes to the remote repository on GitHub.', fig.retina = 2, out.width="100%"}
 image_read("img/vc5-push.png") |>
@@ -306,8 +306,8 @@ Before you can create remote repositories on GitHub,
 you will need a GitHub account; you can sign up for a free account 
 at [https://github.com/](https://github.com/).
 Once you have logged into your account, you can create a new repository to host 
-your project by clicking on the "+" icon in the upper right 
-hand corner, and then on "New Repository," as shown in 
+your project by clicking on the "+" icon in the upper right-hand 
+corner, and then on "New Repository," as shown in 
 Figure \@ref(fig:new-repository-01).
 
 (ref:new-repository-01) New repositories on GitHub can be created by clicking on "New Repository" from the + menu. 
@@ -319,7 +319,7 @@ image_read("img/version_control/new_repository_01.png") |>
   image_flop()
 ```
 
-Repositories can be setup with a variety of configurations, including a name, 
+Repositories can be set up with a variety of configurations, including a name, 
 optional description,  and the inclusion (or not) of several template files. 
 One of the most important configuration items to choose is the visibility to the outside world,
 either public or private. *Public* repositories \index{repository!public} can be viewed by anyone.
@@ -330,7 +330,7 @@ To get started with a *public* repository having a template `README.md` file, ta
 following steps shown in Figure \@ref(fig:new-repository-02): 
 
 1. Enter the name of your project repository. In the example below, we use `canadian_languages`. Most repositories follow a similar naming convention involving only lowercase letter words separated by either underscores or hyphens.
-2. Choose an option for the privacy of your repository
+2. Choose an option for the privacy of your repository.
 3. Select "Add a README file." This creates a template `README.md` file in your repository's root folder.
 4. When you are happy with your repository name and configuration, click on the green "Create Repository" button.
 
@@ -355,7 +355,7 @@ image_read("img/version_control/new_repository_03.png") |>
 ### Editing files on GitHub with the pen tool
 
 The pen tool \index{GitHub!pen tool} can be used to edit existing plain text files. When you click on 
-the pen tool the file will be opened in a text box where you can use your 
+the pen tool, the file will be opened in a text box where you can use your 
 keyboard to make changes (Figures \@ref(fig:pen-tool-01) and \@ref(fig:pen-tool-02)).
 
 ```{r pen-tool-01, fig.cap = 'Clicking on the pen tool opens a text box for editing plain text files.', fig.retina = 2, out.width="100%"}
@@ -399,8 +399,8 @@ image_read("img/version_control/pen-tool_03.png") |>
 ### Creating files on GitHub with the "Add file" menu
 
 The "Add file" menu \index{GitHub!add file} can be used to create new plain text files and upload files 
-from your computer. To create a new plain text file, click the "Add file" drop 
-down menu and select the "Create new file" option 
+from your computer. To create a new plain text file, click the "Add file" 
+drop-down menu and select the "Create new file" option 
 (Figure \@ref(fig:create-new-file-01)).
 
 ```{r create-new-file-01, fig.cap = 'New plain text files can be created directly on GitHub.', fig.retina = 2, out.width="100%"}
@@ -420,7 +420,7 @@ Note that GitHub understands and renders `.md` files \index{markdown} using a
 very similar to Jupyter notebooks, so the "Preview" tab is especially helpful 
 for checking markdown code correctness.
 
-```{r create-new-file-02, fig.cap = 'New plain text files require a filename in the text box circled in red, and file content entered in the larger text box (red arrow).', fig.retina = 2, out.width="100%"}
+```{r create-new-file-02, fig.cap = 'New plain text files require a file name in the text box circled in red, and file content entered in the larger text box (red arrow).', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/create-new-file_02.png") |>
   image_flop() |>
   image_crop("3584x1300") |>
@@ -436,10 +436,10 @@ image_read("img/version_control/create-new-file_03.png") |>
 ```
 
 You can also upload files that you have created on your local machine by using 
-the "Add file" drop down menu and selecting "Upload files"
+the "Add file" drop-down menu and selecting "Upload files"
 (Figure \@ref(fig:upload-files-01)).
 To select the files from your local computer to upload, you can either drag and 
-drop them into the grey box area shown below, or click the "choose your files" 
+drop them into the gray box area shown below, or click the "choose your files" 
 link to access a file browser dialog. Once the files you want to upload have 
 been selected, click the green "Commit changes" button at the bottom of the 
 page (Figure \@ref(fig:upload-files-02)).
@@ -548,11 +548,11 @@ image_read("img/generate-pat_03.png")
 Now that we have everything we need for authentication,
 the next step is to *clone* the \index{git!clone} remote repository on GitHub
 to create a local repository, i.e., make a 
-copy that knows where it was obtained from so that it knows where send/receive 
+copy that knows where it was obtained from so that it knows where to send/receive 
 new committed edits. In order to do this, first copy the URL from the HTTPS tab 
-of the Code drop down menu on GitHub (Figure \@ref(fig:clone-02)).
+of the Code drop-down menu on GitHub (Figure \@ref(fig:clone-02)).
 
-(ref:clone-02) The remote address (URL) corresponding to the location of the remote GitHub repository can be found in the green "Code" drop down menu.
+(ref:clone-02) The remote address (URL) corresponding to the location of the remote GitHub repository can be found in the green "Code" drop-down menu.
 
 ```{r clone-02, fig.cap = '(ref:clone-02)', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/clone_02.png") |>
@@ -743,7 +743,7 @@ image_read("img/version_control/add_collab_05.png") |>
   image_crop("3584x1250")
 ```
 
-After this you should see your newly added collaborator listed under the 
+After this, you should see your newly added collaborator listed under the 
 "Manage access" tab. They should receive an email invitation to join the 
 GitHub repository as a collaborator. They need to accept this invitation 
 to enable write access.
@@ -835,7 +835,7 @@ The beginning of the merge
 conflict is preceded by `<<<<<<< HEAD` and the end of the merge conflict is 
 marked by `>>>>>>>`. Between these markings, Git also inserts a separator 
 (`=======`). The version of the change before the separator is your change, and 
-the version that follows the separator was the change that existed on GitHub
+the version that follows the separator was the change that existed on GitHub.
 In Figure \@ref(fig:merge-conflict-05), you can see that in your local repository
 there is a line of code that calls `scale_color_manual` with three color values (`deeppink2`, `cyan4`, and `purple1`).
 It looks like your collaborator made an edit to that line too, except with different colors (to `blue3`, `red3`, and `black`)!
@@ -873,7 +873,7 @@ GitHub page, and they persist there even after the conversation is over and the
 contrast to email, issues are not usually deleted). One issue thread is usually created
 per topic, and they are easily searchable using GitHub's search tools. All 
 issues are accessible to all project collaborators, so no one is left out of 
-the conversation. Finally, issues can be setup so that team members get email 
+the conversation. Finally, issues can be set up so that team members get email 
 notifications when a new issue is created or a new post is made in an issue 
 thread. Replying to issues from email is also possible. Given all of these advantages,
  we highly recommend the use of issues for project-related communication.
@@ -898,7 +898,7 @@ image_read("img/version_control/issue_02.png") |>
 ```
 
 Add an issue title (which acts like an email subject line), and then put the 
-body of the message in the larger text box. Finally click "Submit new issue"
+body of the message in the larger text box. Finally, click "Submit new issue"
 to post the issue to share with others (Figure \@ref(fig:issue-03)).
 
 ```{r issue-03, fig.cap = 'Dialog boxes and submission button for creating new GitHub issues.', fig.retina = 2, out.width="100%"}
@@ -943,5 +943,5 @@ you can expand your knowledge through the resources listed below:
 - GitHub's [guides website](https://guides.github.com/) and [YouTube channel](https://www.youtube.com/githubguides),
 and [*Happy Git with R*](https://happygitwithr.com/) are great resources to take the next steps in learning about Git and GitHub.
 - [Good enough practices in scientific computing](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510#sec014) [-@wilson2014best] provides more advice on useful workflows and "good enough" practices in data analysis projects.
-- In addition to [GitHub](https://github.com), there are other popular Git repository hosting services such as [GitLab](https://gitlab.com) and  [BitBucket](https://bitbucket.org). Comparing all of these options is beyond the scope of this book, and until you become a more advanced user you are perfectly fine to just stick with GitHub. Just be aware that you have options!
+- In addition to [GitHub](https://github.com), there are other popular Git repository hosting services such as [GitLab](https://gitlab.com) and  [BitBucket](https://bitbucket.org). Comparing all of these options is beyond the scope of this book, and until you become a more advanced user, you are perfectly fine to just stick with GitHub. Just be aware that you have options!
 - [GitHub's documentation on creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and the *Happy Git with R* [cache credentials for HTTPS](https://happygitwithr.com/credential-caching.html) chapter are both excellent additional resources to consult if you need additional help generating and using personal access tokens.