<!-- --- -->
<!-- title: "Lab 02 - GitHub" -->
<!-- output: tufte::tufte_html -->
<!-- link-citations: yes -->
<!-- --- -->

# Learning goals

In this lab, you are expected to learn/put in practice the following skills:

- Forking on GitHub
- Git workflow clone/commit/push
- Using pull requests (PR)

The last bit of the lab will deal with GitHub Classrooms. While this is not a
fundamental tool for academia/industry, we will be using this tool throughout
the course, meaning that your grade will depend on it :).

# Updating a single repo

One of the most common tasks that people uses git for is for collaborating. While
in general team members organize such that there are no overlapping editing of
the files, git is smart enough to avoid clashes when multiple edits are done in
the same document[^multiedits]. To show this, we will do a collaborative edit of
a file!

[^multiedits]: Team-members could be working on the same file but editing
different lines of code. If this is the case, after pull/push, git will integrate
the changes without conflicts.

We will be working with the repository https://github.com/USCbiostats/git-crash-whoami

## Step 1: For the project in your repo

Not a term/command actually available in Git, forking is a feature available in
Github (as in other services) that allows users to create copies of other people's
projects to propose changes (i.e. make **pull requests**, i.e. "I have this
great update to your project! Would you like to add it by *pulling it* into your
repo?").

To start you just need to use the Fork button available on the project you would
like to contribute to[^githubmanualfork]:

[^githubmanualfork]: For more details, take a look at the [Forking Projects](https://guides.github.com/activities/forking/) article in GitHub guides.

<figure>
<img src="https://github-images.s3.amazonaws.com/help/bootcamp/Bootcamp-Fork.png" width="400px">
<figcaption>Source: GitHub Help</figcaption>
</figure>

Once you "Fork" a project, GitHub will:

1. Create a copy (using `git clone`) of that project in your account.

2. Set up a pipeline to generate pull requests.

<figure>
<img src="https://github-images.s3.amazonaws.com/help/pull_requests/recently_pushed_branch.png" width="600px">
<figcaption>Source: GitHub Help</figcaption>
</figure>

Once you have a copy of the project in your account, you can proceed by
"downloading it" to your computer using the `git clone` command. For example, if
your github user name is `statsnerd` and the original repository is `Spoon-Knife`
(as in the example), you could use the following in your command line

```shell
cd a-place-where-you-want-to-download-the-thing
git clone https://github.com/statsnerd/Spoon-Knife.git
```

And if you have your ssh credentials set up, you can do instead

```shell
cd a-place-where-you-want-to-download-the-thing
git clone git@github.com:statsnerd/Spoon-Knife.git
```

This way you will get a copy of the repository in your local machine. Now, let's
see how can we update the project!

## Step 2: Modifying the corresponding line

If you got the correct copy, you should find a very simple repository with only
two files: `.gitignore` and `README.md`. The first file is just a reference file
for git to know what things it should be "looking at" (checkout the lecture
slides), so we will **ignore it** at this time (pun intended). The second file
is the one that we will be playing with. The readme file, which happens to be
a [Markdown](https://en.wikipedia.org/wiki/Markdown) file, contains, or at least
will contain, your and your team members biographies. Here is what you need to
do:

1. Go to the last line of the file. Make sure to leave a blank line before
your addition.

2. In that single line (i.e. not spanning multiple lines), write something about
yourself, e.g. "I am from XYZ, I love doing ABC, ...".

3. (optional) if you feel like it, add at the beginning of the line a picture
of yourself (or avatar) using either html or markdown. This will require you
to include the figure in the repo (if you are not linking a web fig).

4. Commit the changes and push the changes to your repo using `git commit` and
`git push`, e.g.

```sh
git commit -a -m "[A short but meaningful message]"
# git add [your-avatar.png] ... if you need to add a picture
git push
```

You are now one step closer to make your first "pull request". We will see how
that happens in the next part.


## Step 3: Do the pull request

This is the final step. Overall, pull requests (PR) are as complex as the proposed
changes are. The PR that you are about to make should go smoothly, yet, any time
that you make a new PR, the changes should be able to be `merged` in the original
repository without conflicts. Conflicts may only appear if the proposed changes
are out-dated with respect to the main repository, meaning that the main repository
was modified *after* your fork and your proposed changes cannot be merged without
generating conflicts[^mergeconflicts]. For now, let's just look at the simple case.

[^mergeconflicts]: More info about how to deal with conflicts in this very neat
post on stackoverflow.com [How to resolve merge conflicts in Git](https://stackoverflow.com/questions/161813/how-to-resolve-merge-conflicts-in-git?page=1&tab=votes#tab-top).
GitHub also has a way to solve conflicts in PRs, but this is only available to
the admins of target repo. More info [here](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github),


To create the PR, you just need to go to your online copy of the project and
click on "Compare & pull request" link:

<figure>
<img src="https://github-images.s3.amazonaws.com/help/pull_requests/recently_pushed_branch.png" width="600px">
<figcaption>Source: GitHub Help</figcaption>
</figure>

This will create a PR in the reference repository. GitHub will automatically
analyze the PR and check whether merging the PR to the master branch will result
in a conflict or not. If all is OK, then the owner/admin of the repository can
merge the PR. Otherwise, if there's a conflict, you can go back to your local
repo, make the needed changes, commit the changes, and push the changes to
your copy on github. In this stage, the PR will automatically update to reflect
the new changes you made in your copy of the project.

For more information checkout [Creating a pull request from a fork
](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)
on GitHub.

<!--
# Using GitHub classrooms

When you start work on an exercises or assignment, you will need to complete the
following steps:

1. Accept the invitation to the assignment that you will receive (by email, I
   think)

2. Link the assignment to your Github ID (github will automatically ask you to
   do this and help you get it done).

3. Downoad the pseudocode (if there is any for that problem). The simplest way
   to do this using RStudio is shown in the "Hello World" exercise that we will
   be doing at the start of class on Week 1.

4. As you are working on the problem, regularly "commit" your work. I will not
   be able to see what you are doing, and comment on it, until you "push" the
   work back to Github. Get into the habit of committing regularly.

5. Once you have completed your work on that problem you need to "commit" you
   work and then push it to github one final time.
    
    For each assignment there will be a Github issue
    [here](https://github.com/PM520-Spring-2020/General-course-info/issues)
    which you are required to reference when submitting the final version of
    your assignment. This way I will be notified that your's is ready to be
    reviewed. In order to use this functionallity, you can:
    
    - Add the full URL in the commit message or in a new comment like this:
      `https://github.com/PM520-Spring-2020/General-course-info/issues/1`, or
       
    - Add a short version of it like this: `PM520-Spring-2020/General-course-info#1`
    
    For more information about automatic cross-reference links, take a look at
    the Github documentation
    [here](https://help.github.com/en/github/writing-on-github/autolinked-references-and-urls)


## Testing out GitHub Classrooms

The excercise is simple. You should either had received an email or directly
forked the assignment from the course's [GitHub classroom website](UPS?). The
excercise consists on the following:

1. Setup the assignment repo following the instructions above.

2. Clone the repo in your computer using `git clone`.

3. Go and edit the `README.md` file in the repository. The `README.md` file
   should have the following contents:
   
   ```markdown
   # Getting to know you a bit more
   
   1. What is your favorite book?
   
   2. What is your favorite movie?
   
   3. What is your favorite kind of music?
   
   4. What would you like to learn from this class?
   ```
   
   Answer the questions in the same `README.md` file.
   
4. Once you are done answering the questions, commit the changes and push them
   to GitHub. The commit message should include a reference to the following
   issue LINK TO THE ISSUE.

And you are done!

<!-- --- -->

<!-- This set of lab exersixes have been adopted from [Mine Çetinkaya-Rundel](https://twitter.com/minebocek)'s class [Introduction to Data Science](https://github.com/ids-s1-19). -->

