Merge pull request #349 from UBC-DSCI/patch-vc-pa-token

added section on personal access tokens.

Author: trevorcampbell

img/generate-pat_01.png

@@ -468,6 +468,7 @@ version control: you won't be able to see, interpret, or find changes in the his
 of any of the actual content of your project!
 
 ## Working with local repositories using Jupyter {#local-repo-jupyter}
+
 Although there are several ways to create and edit files on GitHub, they are
 not quite powerful enough for efficiently creating and editing complex files,
 or files that need to be executed to assess whether they work (e.g., files
@@ -477,14 +478,76 @@ remote repository that was created on GitHub to a local coding environment.  Thi
 can be done by creating and working in a local copy of the repository.
 In this chapter, we focus on interacting with Git via Jupyter using
 the Jupyter Git extension. The Jupyter Git \index{git!Jupyter extension} extension
-can be run via Jupyter on your local computer, or on a JupyterHub server. 
+can be run by Jupyter on your local computer, or on a JupyterHub server. 
 *Note: we recommend reading Chapter \@ref(getting-started-with-jupyter)* 
 *to learn how to use Jupyter before reading this chapter.*
 
+### Generating a GitHub personal access token
+
+To send and retrieve work between your local repository 
+and the remote repository on GitHub,
+you will frequently need to authenticate with GitHub 
+to prove you have the required permission.
+There are several methods to do this, 
+but for beginners we recommend using the HTTPS method 
+because it is easier and requires less setup.
+In order to use the HTTPS method, 
+GitHub requires you to provide a *personal access token*. \index{GitHub!personal access token} 
+A personal access token is like a password—so keep it a secret!—but it gives
+you more fine-grained control over what parts of your account
+the token can be used to access, and lets you set an expiry date for the authentication.
+To generate a personal access token, 
+you must first visit [https://github.com/settings/tokens](https://github.com/settings/tokens),
+which will take you to the "Personal access tokens" page in your account settings.
+Once there, click "Generate new token" (Figure \@ref(fig:generate-pat-01)).
+Note that you may be asked to re-authenticate with your username 
+and password to proceed.
+
+(ref:generate-pat-01) The "Generate new token" button used to initiate the creation of a new personal access token. It is found in the "Personal access tokens" section of the "Developer settings" page in your account settings.
+
+```{r generate-pat-01, fig.cap = '(ref:generate-pat-01)', fig.retina = 2, out.width="100%"}
+image_read("img/generate-pat_01.png")
+```
+
+Next you will be asked to add a note for your personal access token. 
+This should be a descriptor of the token's purpose.
+Finally, you need to select permissions for the token; this is where
+you can control what parts of your account the token can be used to access.
+Make sure to choose only those permissions that you absolutely require. In
+Figure \@ref(fig:generate-pat-02), we tick only the "repo" box, which gives the 
+token access to our repositories (so that we can push and pull) but none of our other GitHub 
+account features. Finally, to generate the token, scroll to the bottom of that page 
+and click the green "Generate token" button (Figure \@ref(fig:generate-pat-02)).
+
+(ref:generate-pat-02) Webpage for creating a new personal access token.
+
+```{r generate-pat-02, fig.cap = '(ref:generate-pat-02)', fig.retina = 2, out.width="100%"}
+image_read("img/generate-pat_02.png")
+```
+
+Finally, you will be taken to a page where you will be able to see 
+and copy the personal access token you just generated (Figure \@ref(fig:generate-pat-03)). 
+Since it provides access to certain parts of your account, you should
+treat this token like a password; for example, you should consider 
+securely storing it (and your other passwords and tokens, too!) using a password manager.
+Note that this page will only display the token to you once,
+so make sure you store it in a safe place right away. If you accidentally forget to
+store it, though, do not fret—you can delete that token by clicking the 
+"Delete" button next to your token, and generate a new one from scratch. 
+To learn more about GitHub authentication, 
+see the additional resources section at the end of this chapter.
+
+(ref:generate-pat-03) Display of the newly generated personal access token.
+
+```{r generate-pat-03, fig.cap = '(ref:generate-pat-03)', fig.retina = 2, out.width="100%"}
+image_read("img/generate-pat_03.png")
+```
+
 ### Cloning a repository using Jupyter 
 
-The first step is to *clone* the \index{git!clone} remote repository on GitHub to create a local repository,
-i.e., make a 
+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 
 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)).
@@ -521,9 +584,9 @@ image_read("img/version_control/clone_04.png") %>%
 ```
 
 ### Specifying files to commit
-Now that we have cloned the remote repository from GitHub to create a local repository,
-you can get to work editing, creating,  and deleting files. 
-For example, suppose we created and saved a new file (named `eda.ipynb`) that we would 
+Now that you have cloned the remote repository from GitHub to create a local repository,
+you can get to work editing, creating, and deleting files. 
+For example, suppose you created and saved a new file (named `eda.ipynb`) that you would 
 like to send back to the project repository on GitHub (Figure \@ref(fig:git-add-01)).
 To "add" this modified file to the staging area (i.e., flag that this is a
 file whose changes we would like to commit), click the Jupyter Git extension 
@@ -537,8 +600,8 @@ This opens the Jupyter Git graphical user interface pane. Next,
 click the plus sign (+) beside the file(s) that you want to "add"  \index{git!add}
 (Figure \@ref(fig:git-add-02)). Note that because this is the 
 first change for this file, it falls under the "Untracked" heading. 
-However, next time we edit this file  and want to add the changes,
-we will find it under the "Changed" heading.
+However, next time you edit this file  and want to add the changes,
+you will find it under the "Changed" heading.
 
 You will also see an `eda-checkpoint.ipynb` file under the "Untracked" heading.
 This is a temporary "checkpoint file" created by Jupyter when you work on `eda.ipynb`.
@@ -552,9 +615,9 @@ image_read("img/version_control/git_add_02.png")
 ```
 
 Clicking the plus sign (+) moves the file from the "Untracked" heading to the "Staged" heading, 
-flagging this file so that Git knows we want a snapshot of its current state 
+flagging this file so that Git knows you want a snapshot of its current state 
 as a commit (Figure \@ref(fig:git-add-03)).
-Now we are ready to "commit" the changes. 
+Now you are ready to "commit" the changes. 
 Make sure to include a (clear and helpful!) message about what was changed
 so that your collaborators (and future you) know what happened in this commit. 
 
@@ -567,13 +630,13 @@ image_read("img/version_control/git_add_03.png")
 ### Making the commit
 
 To snapshot the changes with an associated commit message, 
-we put a message in the text box at the bottom of the Git pane 
+you must put a message in the text box at the bottom of the Git pane 
 and click on the blue "Commit" button (Figure \@ref(fig:git-commit-01)). \index{git!commit}
 It is highly recommended to write useful and meaningful messages about what 
 was changed. These commit messages, and the datetime stamp for a given 
 commit, are the primary means to navigate through the project's history in the 
- event that we need to view or retrieve a past version of a file, or 
-revert our project to an earlier state.
+ event that you need to view or retrieve a past version of a file, or 
+revert your project to an earlier state.
 When you click the "Commit" button for the first time, you will be prompted to 
 enter your name and email. This only needs to be done once for each machine 
 you use Git on.
@@ -582,9 +645,9 @@ you use Git on.
 image_read("img/version_control/git_commit_01.png")
 ```
 
-After "committing" the file(s), you will see there are 0 "Staged" files 
-and we are now ready to push our changes
-to our remote repository on GitHub (Figure \@ref(fig:git-commit-03)).
+After "committing" the file(s), you will see there are 0 "Staged" files. 
+You are now ready to push your changes
+to the remote repository on GitHub (Figure \@ref(fig:git-commit-03)).
 
 ```{r git-commit-03, fig.cap = 'After recording a commit, the staging area should be empty.', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_commit_03.png")
@@ -593,7 +656,8 @@ image_read("img/version_control/git_commit_03.png")
 ### Pushing the commits to GitHub
 
 To send the committed changes back to the remote repository on 
-GitHub, we need to *push* them. \index{git!push} To do this we click on the cloud icon with the up arrow on the Jupyter Git tab 
+GitHub, you need to *push* them. \index{git!push} To do this, 
+click on the cloud icon with the up arrow on the Jupyter Git tab 
 (Figure \@ref(fig:git-push-01)).
 
 (ref:git-push-01) The Jupyter Git extension "push" button (circled in red).
@@ -602,23 +666,25 @@ GitHub, we need to *push* them. \index{git!push} To do this we click on the clou
 image_read("img/version_control/git_push_01.png")
 ```
 
-We will then be prompted to enter our GitHub username 
-and password, and click the blue "OK" button (Figure \@ref(fig:git-push-02)).
+You will then be prompted to enter your GitHub username 
+and password. Instead of your password, though, you will 
+need to enter the personal access token that you generated
+earlier. Click the blue "OK" button to initiate the push (Figure \@ref(fig:git-push-02)).
 
 ```{r git-push-02, fig.cap = 'Enter your Git credentials to authorize the push to the remote repository.', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_push_02.png")
 ```
 
-If the files were successfully pushed to our project repository on 
-GitHub we will be given the success message shown below. 
-Click "Dismiss" to continue working in Jupyter (Figure \@ref(fig:git-push-03)).
+If the files were successfully pushed to the project repository on 
+GitHub, you will be shown a success message (Figure \@ref(fig:git-push-03)). 
+Click "Dismiss" to continue working in Jupyter.
 
 ```{r git-push-03, fig.cap = 'The prompt that the push was successful.', fig.retina = 2, out.width="100%"}
 image_read("img/version_control/git_push_03.png")
 ```
 
 If you visit the remote repository on GitHub, 
-you will see that the changes now exist there via their web interface 
+you will see that the changes now exist there too
 (Figure \@ref(fig:git-push-04))!
 
 ```{r git-push-04, fig.cap = 'The GitHub web interface shows a preview of the commit message, and the time of the most recently pushed commit for each file.', fig.retina = 2, out.width="100%"}
@@ -756,7 +822,7 @@ image_read("img/version_control/merge_conflict_03.png") %>%
 
 ### Handling merge conflicts
 
-To fix the merge conflict, \index{git!merge conflict} we need to open the offending file
+To fix the merge conflict, \index{git!merge conflict} you need to open the offending file
 in a plain text editor and look for special marks that Git puts in the file to
 tell you where the merge conflict occurred (Figure \@ref(fig:merge-conflict-04)). 
 
@@ -865,7 +931,7 @@ Now that you've picked up the basics of version control with Git and GitHub,
 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](https://happygitwithr.com/) are great resources to take the next steps in learning about Git and GitHub.
+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!
-
+- [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.