Merge pull request #8 from cct-datascience/github-slides

WIP: draft lesson 5 slides

index.qmd

@@ -10,7 +10,7 @@ Welcome to the syllabus for the CCT Data Science fall workshop series: **Reprodu
 
 We'll meet on Tuesdays and Thursdays from 11am to 1pm via Zoom (link)
 
-<!-- Edit by editing schedule.csv.  To add links, use markdown [text](url) separated by commas. This code turns that into a bulleted list. -->
+<!-- Edit by editing schedule.csv.  To add links, use markdown [text](url) separated by commas. This code turns that into a bulleted list.-->
 
 ```{r}
 #| echo: false

lessons/5-github-collab/notes.qmd

@@ -18,7 +18,8 @@ Learners will fork and clone a repository on GitHub and use branches to open pul
     -   Share a repo with everyone & have everyone clone w/ RStudio
     -   Ask 1 (one) volunteer to make a change and practice commit + push
     -   Both instructor and volunteer make a change in the same file and push to main
-    -   Show how to resolve merge conflict on GitHub
+    -   Should error for whoever pushes second
+    -   Try following hints and pull, then set `git config pull.rebase false`
 
 -   Working on branches (slides)
 

lessons/5-github-collab/references.bib

@@ -0,0 +1,15 @@
+
+@article{bryan2018,
+	title = {Excuse me, do you have a moment to talk about version control?},
+	author = {Bryan, Jennifer},
+	year = {2018},
+	month = {01},
+	date = {2018-01},
+	journal = {The American Statistician},
+	pages = {20{\textendash}27},
+	volume = {72},
+	number = {1},
+	doi = {10.1080/00031305.2017.1399928},
+	url = {https://www.tandfonline.com/doi/full/10.1080/00031305.2017.1399928},
+	note = {Publisher: Taylor & Francis}
+}

lessons/5-github-collab/slides.qmd

@@ -0,0 +1,173 @@
+---
+title: "Collaborate With GitHub"
+subtitle: "Session 5"
+format: revealjs
+editor: visual
+chalkboard: true
+footer: "[Reproduciblity & Data Science in R](../../index.html)"
+bibliography: references.bib
+---
+
+## Review
+
+::: callout-note
+## Word Bank
+
+repo \| commit \| remote \| push \| pull \| add
+:::
+
+::: incremental
+1.  A collection of files tracked by git
+2.  A snapshot of the state of a repository
+3.  `git` \_\_\_ is used to tell git to track a file
+4.  For example, a repo on GitHub
+5.  `git` *\_\_\_\_* is used to synchronize changes on your computer with a remote
+:::
+
+## Homework
+
+Did anyone add a repo to GitHub?
+What difficulties did you encounter?
+
+## Collaborating with GitHub
+
+![](github-diagram-bryan.png){fig-align="center" width="671"}
+
+::: aside
+Figure 2 from [@bryan2018]
+:::
+
+::: notes
+A GitHub repo can be used to coordinate collaboration
+
+If two people have permissions, both can push changes to the repo
+
+Ask for a volunteer and give them permission to push to a repo
+:::
+
+## Example repo
+
+-   Everyone practice cloning this example repo as a new RStudio project: <!--# TODO: add link -->
+
+-   Need one volunteer to edit the README.md and practice commit + push
+
+## Dealing with Conflicts
+
+-   What happens when two people make conflicting edits to a file and push them?
+
+-   Creates a *merge conflict*
+
+    ![](push_error.png)
+
+## Ok, try `git pull`
+
+![](pull_error.png)
+
+## Merge, rebase, fast-forward??
+
+-   These are alternative ways to deal with conflicts---we won't get into the deatils
+
+-   For now, we recommend you stick with the "merge" option
+
+. . .
+
+Use:
+
+``` bash
+git config pull.rebase false
+```
+
+Or, if you want to set this option for all future repos too
+
+``` bash
+git config --global pull.rebase false
+```
+
+## Fixing a Merge Conflict
+
+![](merge_conflict.png)
+
+-   Resolve the conflict however you want (i.e. keep one of the two sections)
+
+-   Delete all lines with `<<<<<<<`, `>>>>>>>`, or `=======`
+
+-   Save and commit
+
+::: notes
+Let's have a round of applause for our volunteer!
+:::
+
+## Avoid merge conflicts by working on branches
+
+Each person works on a "branch"---an independent series of commits that can be merged back into the "main" branch.
+
+```{mermaid}
+gitGraph
+       commit
+       commit
+       branch person_1
+       commit
+       commit
+       commit
+       checkout main
+       branch person_2
+       commit
+       commit
+       checkout main
+       merge person_1
+       merge person_2
+       commit
+       
+```
+
+## Working on a Branch
+
+-   Make a new branch with your name using RStudio's Git pane
+
+-   Commit changes and push to your branch
+
+-   View changes on GitHub
+
+## Pull Requests
+
+A request to merge changes into the main branch
+
+-   Need another volunteer to share screen and be guided through making a pull request
+
+-   This time, everyone can follow along!
+
+## Forks {.smaller}
+
+::: columns
+::: {.column width="40%"}
+What if you don't have permission to push to a GitHub repo but you want to contribute?
+Make a fork!
+
+![](fork_btn.png){fig-align="center"}
+:::
+
+::: {.column width="60%"}
+
+![](fork_diagram.png){fig-align="center" width="627"}
+:::
+:::
+
+## Collaborating with Forks
+
+To contribute to a repo you don't have push permission for:
+
+1.  **Fork** the repo to your own GitHub
+2.  **Clone** the fork to your local computer
+3.  Make **commits** (ideally on a **branch**)
+4.  Make a **pull request** to the upstream repo
+
+::: callout-tip
+## Exercise
+
+In pairs, practice this workflow to make a PR to our example repo
+:::
+
+## References
+
+::: refs
+:::

schedule.csv

@@ -3,7 +3,7 @@ Lesson,Date,Theme,Topic,Links,Notes
 2,2023-09-07,Share & Collaborate,Using shell commands,[slides](lessons/2-shell/slides.html),"Install git, carpentries shell episodes 1 & 2"
 3,2023-09-12,Share & Collaborate,Version control with git,[slides](lessons/3-git/slides.html),"git novice lessons 2-4, then git pane of RStudio"
 4,2023-09-14,Share & Collaborate,Developing code on GitHub,[slides](lessons/4-github-basics/slides.html),"git_sitrep(), use_github(), git novice lesson 7"
-5,2023-09-19,Share & Collaborate,Collaborating with GitHub,[slides](https://docs.google.com/presentation/d/1oKZ2VK50_CW90Um_iOJ8D6KEPgvapqYvXBFMlx0_aiw/),"git novice lesson 8, pr_init(), pr_push(), pr_finish()"
+5,2023-09-19,Share & Collaborate,Collaborating with GitHub,[slides](lessons/5-github-collab/slides.html),"git novice lesson 8, pr_init(), pr_push(), pr_finish()"
 6,2023-09-21,Tidy & Wrangle,Data Manipulation,[slides](lessons/6-data-manipulation/slides.html),data carpentry R ecology episodes 2 & 3
 7,2023-09-26,Repeat & Reproduce,Intermediate R programming I,[slides](lessons/7-intermediate-r-1/slides.html),functions
 8,2023-09-28,Repeat & Reproduce,Intermediate R programming II,,iteration (and anonymous functions)