Merge pull request #7 from fhdsl/workshop-materials

created slides for workshop
fhdsl · Jan 9, 2024 · e56ec15 · e56ec15
2 parents b6fcb8e + 7581a1f
commit e56ec15
Show file tree

Hide file tree

Showing 76 changed files with 6,507 additions and 3 deletions.
diff --git a/01-workshop.Rmd b/01-workshop.Rmd
@@ -1,6 +1,7 @@
 ```{r, include = FALSE}
 ottrpal::set_knitr_image_path()
 ```
+
 # Workshop Notes
 
 ## Review Intro to Git material
@@ -339,7 +340,7 @@ To create a new branch on your remote, you can use the GitHub website:
 
 ![](images/git_branch.png)
 
-The branch `clo2_developmenet` is created on the remote, but it hasn't been updated locally. We run `git pull` locally to update it and switch to that branch via `git checkout`.
+The branch `clo2_development` is created on the remote, but it hasn't been updated locally. We run `git pull` locally to update it and switch to that branch via `git checkout`.
 
 ```         
 % git pull
@@ -365,7 +366,12 @@ After a variable number of commits and pushes, your remote branch is a different
 
 ### Pull Requests
 
-A **pull request** is a way to propose changes from a branch before it is merged back into the main repository. It is just like `git merge`, but it requires more documentation and confirmation. For instance, a collaborator can create their own work on a branch, and then create a pull request to have that new branch's feature to be integrated back to the main branch. The owner of the repository review the proposed changes before accepting the pull request.
+A **pull request** is a way to propose changes from a branch before it is merged back into the main repository. It is just like `git merge`, but it requires more documentation and confirmation. For instance, a collaborator can create their own work on a branch, and then create a pull request to have that new branch's feature to be integrated back to the main branch. The owner of the repository sometimes review the proposed changes before accepting the pull request.
+
+
+```{r, fig.alt="After a variable number of commits, your branch, called a-new-branch is a different version of the original code base that may have a nifty improvement to it. But our main goal is to add that nifty improvement to the main branch. To start this process of bringing in new changes to the main curated repository, we will create a pull request. A pull request will show us the difference between main and a-new-branch so you scrutinize this feature before adding it to the main branch.", out.width = "100%", echo = FALSE}
+ottrpal::include_slide("https://docs.google.com/presentation/d/1IJ_uFxJud7OdIAr6p8ZOzvYs-SGDqa7g4cUHtUld03I/edit#slide=id.g1014c75158f_0_751")
+```
 
 When you have pushed changes to the branch, you will see an option to *"Compare & pull request"*. Click on it.
 
@@ -407,7 +413,7 @@ Some advice for reviewers responding to a pull request:
 
 -   Does the code stick to the style and conventions of this project?
 
-More advice on code review can be found here for [pull request authors](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/engaging-in-code-review—as-an-author.html), and [pull request reviewers](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/engaging-in-code-review—as-a-reviewer.html).
+More advice on code review can be found here for [pull request authors](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/engaging-in-code-review---as-an-author.html), and [pull request reviewers](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/engaging-in-code-review---as-a-reviewer.html).
 
 ## Appendix: Local and remote as branches
 

diff --git a/Collaborative-Git-GitHub-slides.html b/Collaborative-Git-GitHub-slides.html
diff --git a/Collaborative-Git-GitHub-slides.qmd b/Collaborative-Git-GitHub-slides.qmd
@@ -0,0 +1,349 @@
+---
+title: "Collaborative Git and GitHub"
+format: 
+  revealjs:
+    smaller: true
+    scrollable: true
+---
+
+## Introductions
+
+-   Who am I?
+
+. . .
+
+-   What is DaSL?
+
+. . .
+
+-   Who are you?
+
+    -   Name, pronouns, group you work in
+
+    -   What brought you here?
+
+## Goals of the workshop
+
+. . .
+
+-   Understand the concept of branching and merging for collaborative and diverging work.
+
+. . .
+
+-   Create your own branch for independent work from a collaborative repository, and use a pull request on GitHub to receive feedback before merging.
+
+. . .
+
+-   Create your own branch for independent work on your private repository locally, and merging your work when your independent work is complete.
+
+## Branching and Merging
+
+. . .
+
+Linear:
+
+```         
+o <-- o <-- o <-- o
+```
+
+. . .
+
+Branching:
+
+```         
+o <-- o <-- o <-- o
+            ^
+             \
+              --- o <-- o
+```
+
+. . .
+
+Branching and Merging:
+
+```         
+o <-- o <-- o <-- o <---- o
+            ^            /
+             \          v
+              --- o <-- o
+```
+
+. . .
+
+**Branching**: when branching commit paths are created.
+
+**Merging**: when two branches are integrated together.
+
+## State of a Git repository
+
+![](images/git_workflow1.svg)
+
+## State of a Git repository, with remote
+
+![](images/git_workflow2.svg)
+
+## Set up
+
+1.  Login to your GitHub account: https://github.com/login
+
+. . .
+
+2.  Create a Replit account and "fork" this project: https://replit.com/@ChrisLo6/GitAndGitHubDaSL
+
+. . .
+
+4.  In your Replit shell,
+
+```         
+sh setup.sh
+```
+
+You will be asked how you want to log in, and pick the following:
+
+```         
+? What account do you want to log into? GitHub.com
+? What is your preferred protocol for Git operations? HTTPS
+? Authenticate Git with your GitHub credentials? Yes
+? How would you like to authenticate GitHub CLI? Login with a web browser
+```
+
+You will be given a code, and you will provide that code to GitHub via <https://github.com/login/device>.
+
+
+## Getting started with branches
+
+Let's create a local repository to practice branching:
+
+. . .
+
+```         
+% mkdir sandbox
+% cd sandbox
+% git init
+% touch README
+% git add README
+% git commit -m "Added README"
+```
+
+. . .
+
+Let's look at the branches in this repository:
+
+```         
+% git branch
+* main
+```
+
+The star `*` shows which branch we are looking at.
+
+We are on the `main` branch in this repository, as expected.
+
+## Ways to look at a branch
+
+Let's create a new branch:
+
+. . .
+
+```         
+% git branch development
+% git branch
+  development
+* main
+```
+
+. . .
+
+Another way to look at which branch we are on is via `git log`:
+
+```         
+% git log
+commit 657fcbea5a023041d359a8f1fcfc9fbf7e64f68e (HEAD -> main, development)
+Merge: 875d774 413b490
+Author: Your Name <you@example.com>
+Date:   Wed Dec 6 23:47:39 2023 +0000
+
+   Initial commit
+```
+
+The `HEAD` **pointer** tells us "What am I looking at?" in our local file system. 
+
+
+## Committing to the development branch
+
+. . .
+
+```         
+% git checkout development
+Switched to branch 'development'
+% echo "Additional README info" >> README.md 
+% git add README.md 
+% git commit -m "updated README"
+```
+
+. . .
+
+Let's look at our `git log`:
+
+```         
+% git log
+commit 260c8099f0ea82199805325a6fbe26bfc3cbd1aa (HEAD -> development)
+Author: Your Name <you@example.com>
+Date:   Thu Dec 7 00:14:02 2023 +0000
+
+    updated README
+
+commit 657fcbea5a023041d359a8f1fcfc9fbf7e64f68e (main)
+Merge: 875d774 413b490
+Author: Your Name <you@example.com>
+Date:   Wed Dec 6 23:47:39 2023 +0000
+
+    Initial commit
+```
+
+Now, our branch `development` is ahead of the `main` branch by one commit. We can toggle between two branches via `git checkout` as before.
+
+
+## Merging
+
+. . .
+
+All you have to do is checkout the branch you wish to merge into and then run `git merge [branchName]` on the branch of interest:
+
+``` 
+% git checkout main
+% git merge development 
+Merge branch 'main' of https://github.com/fhdsl/Collaborative_Git_GitHub_Student_Practice
+Updating 657fcbe..260c809
+Fast-forward
+% git log
+commit 260c8099f0ea82199805325a6fbe26bfc3cbd1aa (HEAD -> main, development)
+Author: Your Name <you@example.com>
+Date:   Thu Dec 7 00:14:02 2023 +0000
+
+    updated README
+
+commit 657fcbea5a023041d359a8f1fcfc9fbf7e64f68e 
+Merge: 875d774 413b490
+Author: Your Name <you@example.com>
+Date:   Wed Dec 6 23:47:39 2023 +0000
+
+    Initial commit
+```
+
+## Accessing our shared repository
+
+1. In Replit shell,
+
+```
+%cd ~
+%git clone https://github.com/fhdsl/Collaborative_Git_GitHub_Student_Practice.git
+```
+
+2. Open up https://github.com/fhdsl/Collaborative_Git_GitHub_Student_Practice in browser. 
+
+
+## Pull request model
+
+A **pull request** is a way to propose changes from a branch before it is merged back into the main repository. It is just like `git merge`, but it requires more documentation and confirmation. 
+
+. . .
+
+For instance, a collaborator can create their own work on a branch, and then create a pull request to have that new branch's feature to be integrated back to the main branch. The owner of the repository sometimes review the proposed changes before accepting the pull request.
+
+. . .
+
+![](images/git_PR_illustration.png)
+
+
+## Creating a branch on the remote
+
+![](images/git_branch.png)
+
+## Making changes to this new branch locally
+
+The branch `clo2_development` is created on the remote, but it hasn't been updated locally. We run `git pull` locally to update it and switch to that branch via `git checkout`.
+
+. . .
+
+```         
+% git pull
+From https://github.com/fhdsl/S2_Collaborative_Git_GitHub_Student_Practice
+ * [new branch]      clo2_development -> origin/clo2_development
+Already up to date.
+
+% git checkout clo2_development
+Branch 'clo2_development' set up to track remote branch 'clo2_development' from 'origin'.
+Switched to a new branch 'clo2_development'
+```
+
+
+## Making changes to new branch
+
+. . .
+
+```         
+% echo "branch edits" >> README.md
+% git add README.md
+% git commit -m "edited README.md"
+% git push
+```
+
+. . .
+
+When you have pushed changes to the branch, you will see an option to *"Compare & pull request"*. Click on it.
+
+![](images/git_PR1.png)
+
+## Creating a pull request
+
+You will see that you are trying to merge `clo2_development` into `main` on the remote. It also requires you to write a description of what you did on your branch.
+
+. . .
+
+![](images/git_PR2.png)
+
+. . .
+
+## Creating a pull request
+
+![](images/git_PR3.png)
+
+Add your partner's GitHub username as your reviewer, and talk about it!
+
+
+## Guidelines on pull request discussions
+
+For writers:
+
+-   it provides context of the code changes you made.
+
+-   it asks for explicit feedback of what kind of feedback is needed.
+
+-   it is a a small and modular change that can be discussed.
+
+For reviewers:
+
+-   Do the proposed changes answer the solve the problem? Can you test it out in the working branch?
+
+-   Is the code clear and readable? Does it contain a healthy amount of comments and documentation for individuals not familiar with the project to understand generally what is going on?
+
+-   Is the code efficient with computational resources?
+
+-   Does the code stick to the style and conventions of this project?
+
+. . .
+
+Click *"Merge pull request"* to finish!
+
+
+## Appendix: References
+
+-   [ProGit](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control): We covered chapter 3 in this workshop.
+
+-   [DangItGit](https://dangitgit.com/): Excellent starting point for common Git problems.
+
+-   [MIT's Git Seminar](https://missing.csail.mit.edu/2020/version-control/): A more computer science explanation of how Git works.
+
+-   [Explain Shell](https://explainshell.com/): Access Shell and Git manual and help pages in an easy-to-read way.
+
+