Research Methods: Open Science and Reproducible Research in Linguistics

class: center, middle, inverse, title-slide

# Research Methods: Open Science and Reproducible Research in Linguistics
## Version control III: Manuscript preparation using github
### Joseph V. Casillas, PhD
### Rutgers UniversitySpring 2019Last update: 2019-03-27

---

class: bottom
background-color: black
background-image: url(https://octodex.github.com/images/grim-repo.jpg)
background-size: contain

# More git...

---

# Review

.big[
- There are different types of workflows when using github

- Standard way: 
  - Create repo 
  - Clone local copy
  - Make changes
  - Commit/push changes to remote
]

---
background-image: url(./assets/img/vc3_github_01.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_02.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_09.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_10.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_11.pdf)
background-size: contain

---

# Review

.big[
- There are different types of workflows when using github

.lightgrey[
- Standard way: 
    - Create repo 
    - Clone local copy 
    - Make changes 
    - Commit/push changes to remote
]

- When collaborating: 
    - Fork repo
    - Clone local copy
    - Make changes
    - Commit/push changes to remote
    - Submit pull request to origin
]

---
background-image: url(./assets/img/vc3_github_03.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_04.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_05.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_06.pdf)
background-size: contain

---
class: bottom, center
background-image: url(https://octodex.github.com/images/socialite.jpg)

# Useful workflow when collaborating with many people

---
background-image: url(./assets/img/vc3_github_07.pdf)
background-size: contain

---
background-color: #EDEDED
background-image: url(./assets/img/vc3_github_08.pdf)
background-size: contain

---
class: title-slide-section-grey, middle

# **But**...

### ...this isn't the most common method

### ...or the best method

---
background-color: black
background-image: url(https://i.imgflip.com/2x4s1d.jpg)
background-size: contain

---
background-color: black
background-image: url(https://user-images.githubusercontent.com/194400/32239744-57300018-be63-11e7-8464-1389b9f8e0ee.png)
background-size: contain

---
background-image: url(https://cdn2.hubspot.net/hubfs/2249672/Imported_Blog_Media/austin_powers-1.jpg)
background-size: 500px
background-position: 97% 50%

# What gives?

.pull-left[
.big[
- In the programming world committing to master is a nono. Why?

- Most developers use git as version control for software

- The .blue[master branch] is usually left for public releases

- As such it should always work
]]

---
background-image: url(https://cdn-images-1.medium.com/max/1600/1*ezl84iQSMDnfkOipMVHgDw.png)
background-size: 350px
background-position: 97% 50%

# What's the problem

.pull-left[
.big[
- You might break something

- You might get complicated merge conflicts
]

.full-width[.content-box-blue[
Person A is working on the same file as Person B, they both make changes 
and Person A tries to submit a pull request to master on a file that is 
different from when (s)he started
]]
]

---

# What's the solution?

### Branches

- Using branches gives us a way to work on different versions of a repository 
at one time

- By default a new repo has one branch called .large[.blue[master]]

- Master is *the definitive* branch

- We create new branches to experiment, make edits, create new features, etc., 
before committing them to master

- When you create a branch off of master you’re essentially making a copy, or 
snapshot of master at a specific point in time (like making a copy of 
a word file, i.e., `essay_final_version3_for_real.docx`)

- A branch should be used for making 'one logical change', usually to add a 
feature in software development

- If a collaborator makes changes to master while you are working on a branch, 
you can pull in those changes

---
background-image: url(./assets/img/vc3_github_12.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_13.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_14.pdf)
background-size: contain

---
background-image: url(./assets/img/vc3_github_15.pdf)
background-size: contain

---
background-image: url(https://guides.github.com/activities/hello-world/branching.png)
background-size: contain

---
background-image: url(./assets/img/psychopy_network.png)
background-size: contain

---

# Yeah, but... academic writing is different

.big[
- Using branches in many cases may be overkill, depending on what your working 
on, i.e., slides for class
]

.big[
- But there are concrete examples where it makes sense to use branches...
  - when collaborating with others
  - when working on large projects
  - when making revisions to a manuscript
  - when making changes to your website, cv, conference presentation/poster
  - whenever breaking something small will have a large impact on the project
  - whenever the possibility of "going back" needs to be controlled and 
  easily achieved 
]

---
background-image: url(./assets/img/diss_ex_1.png)
background-size: 700px

---
background-image: url(./assets/img/diss_ex_2.png)
background-size: contain

---
background-image: url(./assets/img/diss_ex_3.png)
background-size: 700px

---

# Summary - workflows

### Old way

- Working solo: commit/push to master

--
(.red[medium danger])

--
- Working as collaborator: commit/push to master

--
(.red[danger]!)

--
- Working as outside collaborator: fork, commit/push to remote,  
pull request to master

--
(.red[low danger])

background-image: url(https://user-images.githubusercontent.com/194400/32239878-ad220b4c-be63-11e7-82f0-49180949fb8e.png)
background-size: 300px
background-position: 97% 50%

### Better way

- Working solo: branch, commit/push, pull request
--

- Working as collaborator, branch, commit/push, pull request
--

- Working as outside collaborator: fork, branch, commit/push, pull request

---
class: middle, inverse
background-image: url(https://user-images.githubusercontent.com/194400/32239666-10da8f34-be63-11e7-928f-c00f552dd2c5.png)
background-size: 400px
background-position: 95% 50%

# Let's practice

.big[https://github.com/jvcasillas/vc_4/]

---
class: title-slide-final, middle
background-image: url(https://github.com/jvcasillas/ru_xaringan/raw/master/img/logo/ru_shield.png), url(https://octodex.github.com/images/femalecodertocat.png)
background-size: 55px, 120px
background-position: 9% 15%, 89% 15%

# Getting help

## If you have problems with github 
## ask for help on slack

### You can find some very basic tutorials related to 
### R, RStudio, RMarkdown, GitHub, and Slack [here][here]

[here]: http://www.jvcasillas.com/ru_teaching/ru_spanish_589/589_01_s2018/sources/tuts/index.html