More Git and GitHub

# More Git and GitHub
## ️ <svg viewBox="0 0 448 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M100.59 334.24c48.57 3.31 58.95 2.11 58.95 11.94 0 20-65.55 20.06-65.55 1.52.01-5.09 3.29-9.4 6.6-13.46zm27.95-116.64c-32.29 0-33.75 44.47-.75 44.47 32.51 0 31.71-44.47.75-44.47zM448 80v352a48 48 0 0 1-48 48H48a48 48 0 0 1-48-48V80a48 48 0 0 1 48-48h352a48 48 0 0 1 48 48zm-227 69.31c0 14.49 8.38 22.88 22.86 22.88 14.74 0 23.13-8.39 23.13-22.88S258.62 127 243.88 127c-14.48 0-22.88 7.84-22.88 22.31zM199.18 195h-49.55c-25-6.55-81.56-4.85-81.56 46.75 0 18.8 9.4 32 21.85 38.11C74.23 294.23 66.8 301 66.8 310.6c0 6.87 2.79 13.22 11.18 16.76-8.9 8.4-14 14.48-14 25.92C64 373.35 81.53 385 127.52 385c44.22 0 69.87-16.51 69.87-45.73 0-36.67-28.23-35.32-94.77-39.38l8.38-13.43c17 4.74 74.19 6.23 74.19-42.43 0-11.69-4.83-19.82-9.4-25.67l23.38-1.78zm84.34 109.84l-13-1.78c-3.82-.51-4.07-1-4.07-5.09V192.52h-52.6l-2.79 20.57c15.75 5.55 17 4.86 17 10.17V298c0 5.62-.31 4.58-17 6.87v20.06h72.42zM384 315l-6.87-22.37c-40.93 15.37-37.85-12.41-37.85-16.73v-60.72h37.85v-25.41h-35.82c-2.87 0-2 2.52-2-38.63h-24.18c-2.79 27.7-11.68 38.88-34 41.42v22.62c20.47 0 19.82-.85 19.82 2.54v66.57c0 28.72 11.43 40.91 41.67 40.91 14.45 0 30.45-4.83 41.38-10.2z"></path></svg> + <svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg>
### <br/><br/><br/>Ariel Muldoon
### May 11, 2021

---

## Today's Goal

**Learn additional tools for working with Git version-controlled projects hosted on GitHub.**

We will

-     Review how to use the `README.md` file in a GitHub repository      
-     Add collaborators to a repository      
-     Solve a merge conflict 😱 with GitKraken  
-     Learn to make a basic pull request using helper functions from package **usethis**

<br/>

Today we extend the very basic work done in the week 1 slides. If you've never worked with Git/GitHub before, you'll want to review [those slides](https://aosmith16.github.io/spring-r-topics/slides/week01_introduction_git_and_github.html) before proceeding.

???

Today won't make anybody an expert, but will get started doing more with the resources on next slide for when they decide to start doing more

---

## Resources

- GitHub articles on [adding collaborators](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/inviting-collaborators-to-a-personal-repository) and [README files](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes) 
- Brief [article](https://blog.axosoft.com/merge-conflict-tool/) from GitKraken on their merge conflict tool  
- Package **usethis** [article](https://usethis.r-lib.org/articles/articles/pr-functions.html) on pull request helpers  
- A lecture in the [R programming for biologists class](https://r-bio.github.io/intro-git-rstudio/#pull-requests) outlines an approach to pull requests *without* **usethis**

.center[
<img src="figs/week07_files/usethis_logo.png" title="usethis hex logo" alt="usethis hex logo" width="25%" />
]

---

# <font style="font-family: cursive; font-style:italic">Let's get started!</font>

---

## The README file

It is standard to have a `README.md` file in your GitHub repository.  This file is for describing the project you are working on.

???

Such as why it is important, what the files contain, etc.

<br/><br/>
The README file is a Markdown document.  Markdown files render to HTML on GitHub. This mean the information in the file will automatically be included in an easily-readable format on the main page of your repository.

Markdown syntax is what you use to write in R Markdown, so you already know the basic syntax for adding information to your README. 🎉

???

Information to include may be what is in the project, why you are doing the project, metadata on the project like where data comes from, etc.

---

## The README file

Here's an example of part of the README file from the GitHub repository for the class website.

.center[
<img src="figs/week07_files/readme_example.png" title="Screenshot of class webiste repository to show how the README file is rendered below the files" alt="Screenshot of class webiste repository to show how the README file is rendered below the files" width="40%" />
]

???

Main point here is that the README renders and is on the repo home page

---

## Examples of wild-caught README's

Let's spend a few minutes looking at examples of README files in the wild.

Some of the easiest examples to find of good README files are for R packages, such as on the [palmerpenguins](https://github.com/allisonhorst/palmerpenguins) repository.

Follow the link to the the [palmerpenguins](https://github.com/allisonhorst/palmerpenguins) repo and scroll down to explore the README file there.

Of course people use repositories for other types of work. Here are two examples of non-R package repositories with information-filled README files:

- [Hill and Grolemund's repository for a workshop](https://github.com/rstudio-conf-2020/intro-to-ml-tidy)  
- [Christopherson et al.'s project repo](https://github.com/UW-MSDS-DATA-598-Reproducibility-WI20/Christopherson-Garcia-Todd-Winegarden-replication-project) demonstrates information you might want in a repo for an analysis

.footnote[
For research projects you can use GitHub to make a *research compendium*. See the [Marwick et al. paper](https://peerj.com/preprints/3192v1/) and an [example compendium](https://github.com/benmarwick/1989-excavation-report-Madjedbebe).
]

???

Purposefully focusing on more "applied" README examples, since that is audience here. Not all README's need to go into this much detail.

Have students follow links to look at README files. Then move on to the practical work for the day

---

## Make a new GitHub <svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg> repository

Make a new GitHub repository called `merge-conflict`.

Remember in Week 1 you learned to   
1. Create a new repository on GitHub, initializing with README and .gitignore files.  
2. Clone the repository via the "Code" button.  
3. Use the copied URL to make a version-controlled RStudio Project on your computer.

???

They may have forgotten how to do this, so be prepared to answer questions.

---

## Add a collaborator

Right now you are the only person who can make direct changes to files in one of your repositories.

Add *collaborators* if you'd like others to also be able to work directly on a repository.

1. Start by going to your `merge-conflict` repository and then go to `Settings`.

.center[
<img src="figs/week03_files/github_settings.png" title="Screenshot showing the 'Settings' button at the right of menus along the top of the GitHub repository, The button has been circled to draw attention to it." alt="Screenshot showing the 'Settings' button at the right of menus along the top of the GitHub repository, The button has been circled to draw attention to it." width="100%" />
]

---

## Add a collaborator

Right now you are the only person who can make direct changes to files in one of your repositories.

Add *collaborators* if you'd like others to also be able to work directly on a repository.

1. Start by going to your `merge-conflict` repository and then go to `Settings`.
2. From the left-hand menu choose `Manage Access` (second menu item from the top).

.center[
<img src="figs/week07_files/manage_access.png" title="Screenshot of first three settings menus, where 'Manage access' is the second one of the three" alt="Screenshot of first three settings menus, where 'Manage access' is the second one of the three" width="30%" />
]

---

## Add a collaborator

Right now you are the only person who can make direct changes to files in one of your repositories.

Add *collaborators* if you'd like others to also be able to work directly on a repository.

---

## Add a collaborator

Right now you are the only person who can make direct changes to files in one of your repositories.

Add *collaborators* if you'd like others to also be able to work directly on a repository.

1. Start by going to your `merge-conflict` repository and then go to `Settings`.
2. From the left-hand menu choose `Manage Access` (second menu item from the top).
3. Click on the "Invite a collaborator" button.
4. Find the collaborator you want to add using their GitHub user name, email, or their full name.  Once you've selected someone, click the green button to send them an invite. My user name is `aosmith16` if you'd like to invite me for practice. 😁

.center[
<img src="figs/week07_files/add_collaborator.png" title="Screenshot to show how to add a collaborator using a GitHub user name" alt="Screenshot to show how to add a collaborator using a GitHub user name" width="30%" />
]

???

They can invite me if that's easiest.

---

## Add a collaborator

Right now you are the only person who can make direct changes to files in one of your repositories.

Add *collaborators* if you'd like others to also be able to work directly on a repository.

---

## Merge conflicts

A *merge conflict* is when the same lines of a file have been changed in two places, most often by different people. These can become more common once you have collaborators.

I am going to have you create a merge conflict by changing a file on GitHub and in the local version of the repository at the same time.

???

I don't need collaborators to make merge conflicts, myself. I can manage that all on my own! :-D

We'll use GitKraken's merge conflict tool to address the conflict.

Make sure you have GitKraken installed on your computer.

.center[
<img src="figs/week01_files/gitkraken.png" title="GitKraken logo" alt="GitKraken logo" width="20%" />
]

---

### Change README on GitHub

Go to your `merge-conflict` repository on GitHub and open the `README.md` file.

Click on the edit button in the right-hand corner.

.center[
<img src="figs/week07_files/github_readme2.png" title="Screenshot with the cursor hovering over the pencil shaped edit button when getting ready to edit the README file directly on GitHub" alt="Screenshot with the cursor hovering over the pencil shaped edit button when getting ready to edit the README file directly on GitHub" width="65%" />
]

???

The edit button has a picture of a pencil on it.

---

### Change README on GitHub

Replace the current title and description in the README with:

```
# Merge conflict
Practice dealing with a merge conflict
```

---

### Change README on GitHub

After making the change, scroll down to `Commit` the changes. Write a commit message in the first box and then hit the `Commit changes` box. I used `Update README` as my commit message.

.center[
<img src="figs/week07_files/commit_github2.png" title="Screenshot of committing the changes to the README file made directly on GitHub" alt="Screenshot of committing the changes to the README file made directly on GitHub" width="65%" />
]

---

### Change README locally

Now go to your local version of the repository in RStudio.

Open the README file there and replace the current title and description with:

```
# Practice a merge conflict
We will practice a merge conflict
```

---

### Change README locally

Save your changes and then `Stage` - `Commit` - `Push`.

The `Push` will fail, but note the useful message.

.center[
<img src="figs/week07_files/push_fail.png" title="Screenshot of failure to push from local repository when there are changes on GitHub that haven't been pulled in yet" alt="Screenshot of failure to push from local repository when there are changes on GitHub that haven't been pulled in yet" width="65%" />
]

???

This tells us that we are missing work done elsewhere that is on GitHub so we likely need to `Pull`.

---

## Pull changes from GitHub <svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg>

When working with multiple people or working alone but from multiple devices you need to `Pull` changes from GitHub before you can `Push` changes you made locally.

The message in the last slide indicated we hadn't done this. `Pull` using the pull button in the `Git` Pane.

???

Forgetting to pull before working on a local repo is one of my most common mistakes!

Now we get a message about a merge conflict.

.center[
<img src="figs/week07_files/merge_conflict.png" title="Screenshot of merge conflict message after trying to pull changes GitHub when we've changed the same files in the local repository" alt="Screenshot of merge conflict message after trying to pull changes GitHub when we've changed the same files in the local repository" width="65%" />
]

???

Note Git attempted to auto-merge, which can work in many cases. Here it fails since the same lines are changed in both versions of the document.

---

## Open GitKraken <svg viewBox="0 0 592 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M565.7 118.1c-2.3-6.1-9.3-9.2-15.3-6.6-5.7 2.4-8.5 8.9-6.3 14.6 10.9 29 16.9 60.5 16.9 93.3 0 134.6-100.3 245.7-230.2 262.7V358.4c7.9-1.5 15.5-3.6 23-6.2v104c106.7-25.9 185.9-122.1 185.9-236.8 0-91.8-50.8-171.8-125.8-213.3-5.7-3.2-13-.9-15.9 5-2.7 5.5-.6 12.2 4.7 15.1 67.9 37.6 113.9 110 113.9 193.2 0 93.3-57.9 173.1-139.8 205.4v-92.2c14.2-4.5 24.9-17.7 24.9-33.5 0-13.1-6.8-24.4-17.3-30.5 8.3-79.5 44.5-58.6 44.5-83.9V170c0-38-87.9-161.8-129-164.7-2.5-.2-5-.2-7.6 0C251.1 8.3 163.2 132 163.2 170v14.8c0 25.3 36.3 4.3 44.5 83.9-10.6 6.1-17.3 17.4-17.3 30.5 0 15.8 10.6 29 24.8 33.5v92.2c-81.9-32.2-139.8-112-139.8-205.4 0-83.1 46-155.5 113.9-193.2 5.4-3 7.4-9.6 4.7-15.1-2.9-5.9-10.1-8.2-15.9-5-75 41.5-125.8 121.5-125.8 213.3 0 114.7 79.2 210.8 185.9 236.8v-104c7.6 2.5 15.1 4.6 23 6.2v123.7C131.4 465.2 31 354.1 31 219.5c0-32.8 6-64.3 16.9-93.3 2.2-5.8-.6-12.2-6.3-14.6-6-2.6-13 .4-15.3 6.6C14.5 149.7 8 183.8 8 219.5c0 155.1 122.6 281.6 276.3 287.8V361.4c6.8.4 15 .5 23.4 0v145.8C461.4 501.1 584 374.6 584 219.5c0-35.7-6.5-69.8-18.3-101.4zM365.9 275.5c13 0 23.7 10.5 23.7 23.7 0 13.1-10.6 23.7-23.7 23.7-13 0-23.7-10.5-23.7-23.7 0-13.1 10.6-23.7 23.7-23.7zm-139.8 47.3c-13.2 0-23.7-10.7-23.7-23.7s10.5-23.7 23.7-23.7c13.1 0 23.7 10.6 23.7 23.7 0 13-10.5 23.7-23.7 23.7z"></path></svg>

We will now switch to GitKraken to make use of their merge conflict tool.

You will be asked to sign in to GitKraken. Choose the first option to sign in with your GitHub account.

.center[
<img src="figs/week07_files/open_gitkraken.png" title="Screenshot showing the initial window in GitKraken that asks for a sign in. The top button allows you to use GitHub as your sign in" alt="Screenshot showing the initial window in GitKraken that asks for a sign in. The top button allows you to use GitHub as your sign in" width="45%" />
]

---

A new window will pop up in your web browser that will ask you to authorize GitKraken to access GitHub. Continue with the authorization.

.center[
<br/>
<img src="figs/week07_files/authorize_gitkraken.png" title="Screenshot of window that opens in the browser when authenticating GitKraken using your GitHub account" alt="Screenshot of window that opens in the browser when authenticating GitKraken using your GitHub account" width="85%" />
]

---

You should then get a `Success` message, and you are ready to open the local `merge-conflict` repository in GitKraken.

.center[
<img src="figs/week07_files/success_gitkraken.png" title="Screenshot to show a successful authorization of GitKraken through your GitHub account" alt="Screenshot to show a successful authorization of GitKraken through your GitHub account" width="45%" />
]

---

## Open repository in GitKraken <svg viewBox="0 0 592 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M565.7 118.1c-2.3-6.1-9.3-9.2-15.3-6.6-5.7 2.4-8.5 8.9-6.3 14.6 10.9 29 16.9 60.5 16.9 93.3 0 134.6-100.3 245.7-230.2 262.7V358.4c7.9-1.5 15.5-3.6 23-6.2v104c106.7-25.9 185.9-122.1 185.9-236.8 0-91.8-50.8-171.8-125.8-213.3-5.7-3.2-13-.9-15.9 5-2.7 5.5-.6 12.2 4.7 15.1 67.9 37.6 113.9 110 113.9 193.2 0 93.3-57.9 173.1-139.8 205.4v-92.2c14.2-4.5 24.9-17.7 24.9-33.5 0-13.1-6.8-24.4-17.3-30.5 8.3-79.5 44.5-58.6 44.5-83.9V170c0-38-87.9-161.8-129-164.7-2.5-.2-5-.2-7.6 0C251.1 8.3 163.2 132 163.2 170v14.8c0 25.3 36.3 4.3 44.5 83.9-10.6 6.1-17.3 17.4-17.3 30.5 0 15.8 10.6 29 24.8 33.5v92.2c-81.9-32.2-139.8-112-139.8-205.4 0-83.1 46-155.5 113.9-193.2 5.4-3 7.4-9.6 4.7-15.1-2.9-5.9-10.1-8.2-15.9-5-75 41.5-125.8 121.5-125.8 213.3 0 114.7 79.2 210.8 185.9 236.8v-104c7.6 2.5 15.1 4.6 23 6.2v123.7C131.4 465.2 31 354.1 31 219.5c0-32.8 6-64.3 16.9-93.3 2.2-5.8-.6-12.2-6.3-14.6-6-2.6-13 .4-15.3 6.6C14.5 149.7 8 183.8 8 219.5c0 155.1 122.6 281.6 276.3 287.8V361.4c6.8.4 15 .5 23.4 0v145.8C461.4 501.1 584 374.6 584 219.5c0-35.7-6.5-69.8-18.3-101.4zM365.9 275.5c13 0 23.7 10.5 23.7 23.7 0 13.1-10.6 23.7-23.7 23.7-13 0-23.7-10.5-23.7-23.7 0-13.1 10.6-23.7 23.7-23.7zm-139.8 47.3c-13.2 0-23.7-10.7-23.7-23.7s10.5-23.7 23.7-23.7c13.1 0 23.7 10.6 23.7 23.7 0 13-10.5 23.7-23.7 23.7z"></path></svg>

.center[
<img src="figs/week07_files/open_repo1.png" title="Screenshot showing the 'Open a repo' button that is on the main screen of GitKraken after you've authorized" alt="Screenshot showing the 'Open a repo' button that is on the main screen of GitKraken after you've authorized" width="70%" />
]
]

Navigate to the folder that contains the local version of your `merge-conflict` repository and `Select Folder`. The repository will open in GitKraken.
]

---

### Merge conflict message

.pull-left[
Since we currently have a merge conflict, you will see the message `Merge conflict detected` on the right-hand side of GitKraken.

<br/>
Any files with a merge conflict are listed in the window under the message.  Currently this shows `README.md`, the file that has a conflict.
]

.pull-right[
<img src="figs/week07_files/gitkraken_merge_message.png" title="Screenshot showing the right-hand side of GitKraken where the merge conflict message and files that have merge conflicts show up" alt="Screenshot showing the right-hand side of GitKraken where the merge conflict message and files that have merge conflicts show up" width="90%" />
]

---

### GitKraken <svg viewBox="0 0 592 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M565.7 118.1c-2.3-6.1-9.3-9.2-15.3-6.6-5.7 2.4-8.5 8.9-6.3 14.6 10.9 29 16.9 60.5 16.9 93.3 0 134.6-100.3 245.7-230.2 262.7V358.4c7.9-1.5 15.5-3.6 23-6.2v104c106.7-25.9 185.9-122.1 185.9-236.8 0-91.8-50.8-171.8-125.8-213.3-5.7-3.2-13-.9-15.9 5-2.7 5.5-.6 12.2 4.7 15.1 67.9 37.6 113.9 110 113.9 193.2 0 93.3-57.9 173.1-139.8 205.4v-92.2c14.2-4.5 24.9-17.7 24.9-33.5 0-13.1-6.8-24.4-17.3-30.5 8.3-79.5 44.5-58.6 44.5-83.9V170c0-38-87.9-161.8-129-164.7-2.5-.2-5-.2-7.6 0C251.1 8.3 163.2 132 163.2 170v14.8c0 25.3 36.3 4.3 44.5 83.9-10.6 6.1-17.3 17.4-17.3 30.5 0 15.8 10.6 29 24.8 33.5v92.2c-81.9-32.2-139.8-112-139.8-205.4 0-83.1 46-155.5 113.9-193.2 5.4-3 7.4-9.6 4.7-15.1-2.9-5.9-10.1-8.2-15.9-5-75 41.5-125.8 121.5-125.8 213.3 0 114.7 79.2 210.8 185.9 236.8v-104c7.6 2.5 15.1 4.6 23 6.2v123.7C131.4 465.2 31 354.1 31 219.5c0-32.8 6-64.3 16.9-93.3 2.2-5.8-.6-12.2-6.3-14.6-6-2.6-13 .4-15.3 6.6C14.5 149.7 8 183.8 8 219.5c0 155.1 122.6 281.6 276.3 287.8V361.4c6.8.4 15 .5 23.4 0v145.8C461.4 501.1 584 374.6 584 219.5c0-35.7-6.5-69.8-18.3-101.4zM365.9 275.5c13 0 23.7 10.5 23.7 23.7 0 13.1-10.6 23.7-23.7 23.7-13 0-23.7-10.5-23.7-23.7 0-13.1 10.6-23.7 23.7-23.7zm-139.8 47.3c-13.2 0-23.7-10.7-23.7-23.7s10.5-23.7 23.7-23.7c13.1 0 23.7 10.6 23.7 23.7 0 13-10.5 23.7-23.7 23.7z"></path></svg> merge conflict tool

Click on `README.md` in the merge conflict window to open GitKraken's merge conflict tool.

.center[
<img src="figs/week07_files/merge_tool2.png" title="Screenshot of what merge conflict tool looks like when first opened, showing the two top boxes with the two different versions and the bottom box for the Output" alt="Screenshot of what merge conflict tool looks like when first opened, showing the two top boxes with the two different versions and the bottom box for the Output" width="80%" />
]

???

This took me a single click, not a double click

The top two panes show the two versions of the document.  The bottom pane, "Output", shows the original file and will update to show changes as we choose which lines we want to keep.

---

We can choose all lines from one of the two versions. Here I show clicking the "A" box to add all content from "A" to `Output`. I then remove the second line from `Output` by clicking next to that line.

.center[
<img src="figs/week07_files/choose_ab.png" title="Screenshot showing clicking the box next to the left version to add all lines to the Output in the merge conflict tool. The cursor is on the the second line of Output to show I can remove the line by clicking next to it." alt="Screenshot showing clicking the box next to the left version to add all lines to the Output in the merge conflict tool. The cursor is on the the second line of Output to show I can remove the line by clicking next to it." width="80%" />
]

---

I ultimately add the top line from version "A" and the bottom line from version "B" to make a final, combined version of `README.md`.  Click on `Save` in the upper right when you're done.

.center[
<img src="figs/week07_files/final_merge_output.png" title="Screenshot showing my final choices for merging in the Output window, taking one line from the first version and one line from the second" alt="Screenshot showing my final choices for merging in the Output window, taking one line from the first version and one line from the second" width="80%" />
]

???

Students should play around with adding all lines or just one line or some combination.

---

## GitKraken <svg viewBox="0 0 592 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M565.7 118.1c-2.3-6.1-9.3-9.2-15.3-6.6-5.7 2.4-8.5 8.9-6.3 14.6 10.9 29 16.9 60.5 16.9 93.3 0 134.6-100.3 245.7-230.2 262.7V358.4c7.9-1.5 15.5-3.6 23-6.2v104c106.7-25.9 185.9-122.1 185.9-236.8 0-91.8-50.8-171.8-125.8-213.3-5.7-3.2-13-.9-15.9 5-2.7 5.5-.6 12.2 4.7 15.1 67.9 37.6 113.9 110 113.9 193.2 0 93.3-57.9 173.1-139.8 205.4v-92.2c14.2-4.5 24.9-17.7 24.9-33.5 0-13.1-6.8-24.4-17.3-30.5 8.3-79.5 44.5-58.6 44.5-83.9V170c0-38-87.9-161.8-129-164.7-2.5-.2-5-.2-7.6 0C251.1 8.3 163.2 132 163.2 170v14.8c0 25.3 36.3 4.3 44.5 83.9-10.6 6.1-17.3 17.4-17.3 30.5 0 15.8 10.6 29 24.8 33.5v92.2c-81.9-32.2-139.8-112-139.8-205.4 0-83.1 46-155.5 113.9-193.2 5.4-3 7.4-9.6 4.7-15.1-2.9-5.9-10.1-8.2-15.9-5-75 41.5-125.8 121.5-125.8 213.3 0 114.7 79.2 210.8 185.9 236.8v-104c7.6 2.5 15.1 4.6 23 6.2v123.7C131.4 465.2 31 354.1 31 219.5c0-32.8 6-64.3 16.9-93.3 2.2-5.8-.6-12.2-6.3-14.6-6-2.6-13 .4-15.3 6.6C14.5 149.7 8 183.8 8 219.5c0 155.1 122.6 281.6 276.3 287.8V361.4c6.8.4 15 .5 23.4 0v145.8C461.4 501.1 584 374.6 584 219.5c0-35.7-6.5-69.8-18.3-101.4zM365.9 275.5c13 0 23.7 10.5 23.7 23.7 0 13.1-10.6 23.7-23.7 23.7-13 0-23.7-10.5-23.7-23.7 0-13.1 10.6-23.7 23.7-23.7zm-139.8 47.3c-13.2 0-23.7-10.7-23.7-23.7s10.5-23.7 23.7-23.7c13.1 0 23.7 10.6 23.7 23.7 0 13-10.5 23.7-23.7 23.7z"></path></svg> commit and push

<br/>
In the right-hand side you can see that your final version of `README.md` has been staged.

<br/>
Write a commit message and then click `Commit and Merge`.
]

.pull-right[
<img src="figs/week07_files/commit_merge.png" title="Screenshot of the left side of GitKraken, where the merged files have been staged and you need to add message and commit the changes" alt="Screenshot of the left side of GitKraken, where the merged files have been staged and you need to add message and commit the changes" width="90%" />

]

---

`Push` these changes to GitHub with the push button found at the top of the GitKraken window.

.center[
<br/>
<img src="figs/week07_files/push_gitkraken.png" title="Screenshot showing the GitKraken push button up at the top of your screen" alt="Screenshot showing the GitKraken push button up at the top of your screen" width="40%" />
]

<br/><br/>
Once you `Push` these changes you're done. If you go back to the Project in RStudio you'll find the merge conflict message is gone and everything is up-to-date.

You can now close GitKraken and close the `merge-conflict` Project in RStudio.

---

## Pull requests

We will finish this session by going through the steps for making a *pull request* to propose changes to a repository.

A pull request is how you can propose changes to a GitHub repository. If accepted, the person who maintains the repository will *pull* your changes in to change the contents of their repo.

???

Pull requests can be something as simple as to fix typos or help re-word documentation all the way up to proposing new functions or changing code in a package. For the latter, make sure you use the correct coding style for the package.

<br/><br/>
Today we will practice making a pull request on someone else's repository.

Using pull requests is also a reasonable way to approach working with collaborators on a shared repository to avoid merge conflicts.

If working on your own repository, you won't need the step to *fork and clone* the repository.

---

## Pull requests

We'll be using helper functions from package **usethis** for pull requests.

We will start by setting up a *personal access token* or PAT from GitHub. This is required for using the pull request functions in package **usethis**.

.center[
<img src="figs/week07_files/usethis_logo.png" title="usethis hex sticker" alt="usethis hex sticker" width="25%" />
]

---

## Get personal access token (PAT)

This process is necessary only once per computer or if a PAT has been compromised for some reason and you need a new one.

See complete instructions and important additional information about managing your credentials at [Managing Git(Hub) Credentials](https://usethis.r-lib.org/articles/articles/git-credentials.html).

<br/><br/>
**Important:** I will be showing you a screenshot and example code that includes a GitHub PAT. It is important you do not give or show your PAT to anyone. Since the PAT I used to create these slides was compromised, I deleted it and created a new one.

???

Make sure they understand that a PAT should be protected and I'm showing one for educational purposes only.

---

## Get personal access token (PAT)

Make sure you are signed in to GitHub. Open a clean R session in RStudio.

Create a token using function `create_github_token()` from package **usethis**. Run the following code in your R Console or paste into a script and run from there.

```r
usethis::create_github_token()
```

<br/>
You will see a message like the one below and then you will be taken to GitHub.

```
* Call `gitcreds::gitcreds_set()` to register this token in the local Git credential store
It is also a great idea to store this token in any password-management software that you use
√ Opening URL 'https://github.com/settings/tokens/new?scopes=repo,user,gist,workflow&description=R:GITHUB_PAT'
```
    
---

## Get personal access token (PAT)

In GitHub you will give the new PAT a name. This name should allow you to recognize which computer it is for. In my example I create a PAT for my laptop.

.center[
<img src="figs/week07_files/new_PAT.png" title="Screenshot showing the name given to the created PAT so you can identify which computer it is for. I added 'laptop' to the name so I would remember it was the PAT for my laptop" alt="Screenshot showing the name given to the created PAT so you can identify which computer it is for. I added 'laptop' to the name so I would remember it was the PAT for my laptop" width="45%" />
]

<br/><br/>
After naming, scroll down to the bottom and click `Generate token`.  **usethis** has already filled in some recommended scopes and we'll leave them all as is.

---

## Get personal access token (PAT)

Once you create the PAT you will see a page where the token code is visible. Once you leave this page you will not be able to see it again.

**Important:** Make sure you copy the PAT for the next step using the clipboard button before exiting the page.

<br/>
.center[
<img src="figs/week07_files/copy_PAT.png" title="Screenshot showing an example of a created PAT that needs to be copied to your clipboard" alt="Screenshot showing an example of a created PAT that needs to be copied to your clipboard" width="65%" />
]

---

## Store personal access token (PAT)

.pull-left[
Back in R, we can *store* the PAT using the **gitcreds** package. This package was installed when you installed **usethis**.

<br/>
**Note:** You *must* have package **gh** version 1.2.1 or higher installed for this to work.
]

I'm avoiding copying and pasting here because your PAT is currently on your clipboard and you'll need it in this next step. 🙂

```r
gitcreds::gitcreds_set()
```
]

???

Students may want to type out the gitcreds command since they have the PAT on the clipboard.

---

## Store personal access token (PAT)

If you have no credentials stored, you will be prompted to enter your token. Paste it and press enter.

protocol: https
  host    : github.com
  path    : 
  username: PersonalAccessToken
  password: <-- hidden -->

-> What would you like to do?

1: Keep these credentials
2: Replace these credentials
3: See the password / token

Selection:
```
]
]

-> Removing current credentials...

? Enter new password or token: 
```
]

I then pasted my PAT and pressed enter to finish the process.

.smaller[
```
? Enter new password or token: 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
-> Adding new credentials...
-> Removing credetials from cache...
-> Done.
```
]
]

???

Again I have shown my PAT. Since it was compromised I deleted it and made a new one.

---

## Make pull request

Now that we have stored a PAT we can start the pull request process.

For more complete instructions, including instructions on how to edit pull requests, see the **usethis** article on [Pull request helpers](https://usethis.r-lib.org/articles/articles/pr-functions.html).

We're using **usethis** to do some of the heavy lifting here but you can absolutely do this process without it. You can see a basic "manual" approach in the materials for [R programming for biologists](https://r-bio.github.io/intro-git-rstudio/#pull-requests)

---

### Fork and clone a repository

This step is important if you are going to propose a change to someone else's repository.

To *fork* means you make your own copy of the repository on GitHub.

Then *clone* to make a local version of the repository.

???

Students have cloned before manually by copying the github repo URL using the "Code" button on GitHub

<br/><br/>
I'll have you practice making a pull request on one of my repository's, called `practice-repo`. My user name is `aosmith16`.

Copy the following fork and clone code and run it in R:

```r
usethis::create_from_github("aosmith16/practice-repo")
```

Note you need both the user name and repo name for this step.

???

Copy and paste the R code into your R Console to run it.

---

### Fork and clone a repository

.smaller[
```
i Defaulting to 'https' Git protocol
√ Setting `fork = TRUE`
√ Creating 'C:/Users/ariel/Desktop/practice-repo/'
√ Forking 'aosmith16-testing/practice-repo'
√ Cloning repo from 'https://github.com/aosmith16/practice-repo.git' into 'C:/Users/ariel/Desktop/practice-repo'
√ Setting active project to 'C:/Users/ariel/Desktop/practice-repo'
i Default branch is 'master'
√ Adding 'upstream' remote: 'https://github.com/aosmith16/practice-repo.git'
√ Pulling changes from 'upstream/master' (default branch of source repo)
√ Setting remote tracking branch for local 'master' branch to 'upstream/master'
√ Writing 'practice-repo.Rproj'
√ Adding '.Rproj.user' to '.gitignore'
√ Opening 'C:/Users/ariel/Desktop/practice-repo/' in new RStudio session
√ Setting active project to '<no active project>'

```
]
]

.pull-right[
When the process finishes, a new RStudio Project will open from a new local directory for the forked repository.

By default **usethis** will make the local directory on your Desktop. This is usually OK since the local version is temporary; most often you will delete it after finishing your pull request.

You can set a different location for the directory using the `destdir` argument in `create_from_github()`.
]

---

### Create branch to work in

Before you commence making changes to the repository you need to make a new *branch*.  Avoid making changes to the default branch, which is `master` here but for newer repositories is often `main`.

For this exercise, name your branch with your last name plus "prac". Here I named mine `muldoonprac`; name yours based on your own last name. 😉

Run this code with your own branch name in R:

```r
usethis::pr_init(branch = "muldoonprac")
```

```
√ Setting active project to 'C:/Users/ariel/Desktop/practice-repo'
√ Pulling changes from 'upstream/master'
√ Creating and switching to local branch 'muldoonprac'
* Use `pr_push()` to create PR.
```

---

### Edit repository

Now you are working in a new branch and can proceed making your proposed changes.

Today I want each of you to:
- Create a new R Markdown document with HTML output 
- Put your name as the title
- Save the document using your first and last name, like `firstname_lastname.Rmd`

<br/><br/>
Once you have created and saved the new document, `Stage` and `Commit` your changes. Note the `Push` button is grayed out.

???

No need to knit. It's not the end of the world if they do but trying to keep this simple with just a Rmd doc

---

### Create pull request

After finishing any proposed edits and committing them, create a pull request (PR) using `pr_push()`.

Run the following code in R:

```r
usethis::pr_push()
```

You will see some messages in RStudio:

```
√ Pushing local 'muldoonprac' branch to 'origin' remote
* Create PR at link given below
√ Opening URL 'https://github.com/aosmith16/practice-repo/compare/muldoonprac'
```

And then you will be taken to GitHub. This may take a few minutes! ⏳

---

### Create pull request

You will do the final steps to finish the pull request in GitHub. Click the `Create pull request` button.

.center[
<img src="figs/week07_files/create_pull_request.png" title="Screenshot showing the window you are taken from after using pr_push() from usethis" alt="Screenshot showing the window you are taken from after using pr_push() from usethis" width="65%" />
]

---

### Create pull request

You then have the option to add a description in addition to your commit message. This is where you can describe what you edited and why. Fill this is in now.

Once you have added a description click the `Create pull request` button to create the pull request.

.center[
<img src="figs/week07_files/pull_message.png" title="Screenshot showing where you can add a description of your pull request and then finally create it on GitHub" alt="Screenshot showing where you can add a description of your pull request and then finally create it on GitHub" width="65%" />
]

---

### Maintainer response

Now you need to wait for the maintainer to respond. A simple pull request may be accepted or *merged* right away. That is what will happen today with your practice pull request. 😄

<br/><br/>
A maintainer could ask you to make additional changes or they could make changes on top of the ones you proposed. And, of course, they could decide not to accept any of your pull request.

See how to work with some of these alternatives in the **usethis** [Pull request helpers article](https://usethis.r-lib.org/articles/articles/pr-functions.html#review-of-the-pull-request).

---

### Maintainer response

.pull-left[
Once you get a response on your pull request you will see a notification in GitHub (blue dot on bell in upper right-hand corner) and an email.

.center[
<img src="figs/week07_files/notification.png" title="Screenshot showing the blue dot on the bell in GitHub that indicates you have a notification" alt="Screenshot showing the blue dot on the bell in GitHub that indicates you have a notification" width="30%" />
]

Click on the notification <svg viewBox="0 0 448 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M439.39 362.29c-19.32-20.76-55.47-51.99-55.47-154.29 0-77.7-54.48-139.9-127.94-155.16V32c0-17.67-14.32-32-31.98-32s-31.98 14.33-31.98 32v20.84C118.56 68.1 64.08 130.3 64.08 208c0 102.3-36.15 133.53-55.47 154.29-6 6.45-8.66 14.16-8.61 21.71.11 16.4 12.98 32 32.1 32h383.8c19.12 0 32-15.6 32.1-32 .05-7.55-2.61-15.27-8.61-21.71zM67.53 368c21.22-27.97 44.42-74.33 44.53-159.42 0-.2-.06-.38-.06-.58 0-61.86 50.14-112 112-112s112 50.14 112 112c0 .2-.06.38-.06.58.11 85.1 23.31 131.46 44.53 159.42H67.53zM224 512c35.32 0 63.97-28.65 63.97-64H160.03c0 35.35 28.65 64 63.97 64z"></path></svg> and then open the pull request in your Inbox on GitHub.

.center[
<img src="figs/week07_files/github_inbox.png" title="Screenshot showing the inbox after clicking on the notification bell in GitHub. This is where you can see what the maintainer did with the pull request." alt="Screenshot showing the inbox after clicking on the notification bell in GitHub. This is where you can see what the maintainer did with the pull request." width="100%" />
]

]

???

Notification is shown by the blue dot on the bell in the upper right-hand corner.

--
-
.pull-right[
In this case when you open the pull request you will see that it has been merged.

.center[
<img src="figs/week07_files/pull_merge.png" title="Screenshot showing a merged pull request" alt="Screenshot showing a merged pull request" width="100%" />
]
]

---

### Finish pull request process

Once the pull request has been merged we can clean things up on our end.

Back in R, use `pr_finish()` to delete the branch.

Run the following code in R:

```r
usethis::pr_finish()
```

This does some work behind the scenes so don't be alarmed if it at first it doesn't look like it is doing anything.

```
√ Switching back to default branch ('master')
√ Pulling changes from 'upstream/master'
√ Deleting local 'muldoonprac' branch
√ PR 'aosmith16/practice-repo/#9' has been merged, deleting remote branch 'origin/muldoonprac'
```

---

### Finish pull request process

If this was a one-time interaction with a repository, manually delete the local directory from your computer.

You can do this from the merged pull request if you still have it open. Click on `settings`.

Then enter your user name and repository name as requested to delete the forked repository.
]

.pull-right[
.center[
<img src="figs/week07_files/delete_repo.png" title="Screenshot showing the process to delete a repository, where you enter the username and repo name to make sure you aren't deleting by mistake" alt="Screenshot showing the process to delete a repository, where you enter the username and repo name to make sure you aren't deleting by mistake" width="80%" />
]
]

Alternatively, go to your version of the GitHub repository and then `Settings`. Scroll down, down, down to the "Danger Zone" 😱. Click `Delete this repository` and follow instructions.

---

## Next week

- We'll briefly explore a few packages for making interactive plots and tables 
- Download/save `week08_interaction.Rmd` from website prior to class  
- Make sure you have current versions of **htmlwidgets**, **palmerpenguins**, **ggplot2**, **plotly**, **DT**, **leaflet**, **dygraphs**, and **flexdashboard** installed

.center[
<img src="figs/week08_files/flexdashboard.png" title="flexdashboard hex logo" alt="flexdashboard hex logo" width="15%" />
]

.footnote[
[Code for slides](https://github.com/aosmith16/spring-r-topics/tree/main/docs/slides)  
Slides created via the R packages:  
[**xaringan**](https://github.com/yihui/xaringan), 
[gadenbuie/xaringanthemer](https://github.com/gadenbuie/xaringanthemer), 
[gadenbuie/xaringanExtra](https://github.com/gadenbuie/xaringanExtra) 
.center[*This work is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License. 
To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/4.0/.*]
]