Class Meeting 1 Introduction to STAT 545 and GitHub

1.1 Outline

We’ll cover three topics today:

  • Syllabus. (~20 min)
  • GitHub. (~35 min)
  • Getting help (~10 min)

We’ll end class with a to-do list before next class.

1.2 Learning Objectives

By the end of today’s class, students are expected to be able to:

  • Distinguish and navigate between GitHub repositories, Organization accounts, and user accounts.
  • Edit plain text files on GitHub.
  • Navigate the commit history of a repository and a file on GitHub.
  • Contribute to GitHub Issues, especially for STAT 545.
  • Identify whether a software-related question has a reproducible example.

1.3 Resources

If you want to learn more about today’s topics, check out:

  • The GitHub guide has lots of info about GitHub. If you do go here, I recommend you start with “Hello, World!”. You’ll see stuff about branching there – we’ll be discussing that next Thursday.
  • Jenny’s “How to get unstuck” page is useful for getting help online (even outside of STAT 545).

1.4 Topic 1: Syllabus (20 min)

The course syllabus can be found on the STAT 545 @ UBC homepage, stat545.stat.ubc.ca. We’ll cover:

  • Guidebook (2 min)
  • Learning Objectives and Course Structure (8 min)
    • Example of an analysis: Interpreting-Regression book.
  • Teaching Team and Contact (5 min)
  • Resources, especially what’s going on with stat545.com (5 min)

1.5 Topic 2: GitHub (35 min)

(2 min)

We will be using GitHub a lot in this course:

  • All course-related work will go on GitHub.
  • Discussion will happen on GitHub.
  • Even this guidebook and the STAT 545 website files are on GitHub.

But why GitHub? Because it’s tremendously effective for developing a project. Examples:

Today, we’ll check out:

  1. GitHub as cloud storage;
  2. GitHub for collaboration; and
  3. GitHub for version control with git.

1.5.1 Register a GitHub account - Activity (4 min)

Your turn:

  1. Register for a free account on github.com.
    • You’ll be using this account for the duration of the course.
    • Give your username some thought – ideally, should include your name.
  2. Tell us what your username is by filling out this survey.

1.5.2 GitHub as cloud storage (4 min)

At the very least, GitHub allows for cloud storage, like Google Drive and Dropbox do. There’s a bit more structure than just storing files under your account:

  • Repositories (aka “repo”): All files must be organized into repositories. Think of these as self-contained projects. These can either be public or private.
  • User Accounts vs. Organization Accounts (aka “Org”): All repositories belong to an account:
    • A user account is the account you just made, and typically holds repositories related to your own work.
    • An Organization account can be owned by multiple people, and typically holds repositories relevant to a group (like STAT 545).

Examples:

  • The ggplot2 repo, within its corresponding tidyverse Org.
  • My website repo, within my own user account.

Want to read more about GitHub accounts? Check out this help page on GitHub.

1.5.3 GitHub as cloud storage - Activity (10 min)

Together: Make a participation repo

Navigating GitHub

  1. Together: Make a new file on your participation repository:
    • Click on the “Create New File” button on your repository’s home page.
    • Call it navigating_github.md
    • Leave it blank, and commit (“save”) the file by clicking on green “commit new file” button at the bottom of the page.
  2. Together: Add the following URL’s to your navigating_github.md file (click on the pen button to edit), together with some commentary:
    • The repository for the STAT 545 home page, called STAT545-home (use this if the site ever goes down!)
    • The account it’s under.
    • Whether the account is a user account or an Org.
  3. Together: Commit the changes.
  4. Your turn: Continue the exercise, and add more URL’s (with more commentary):
    • The URL to your participation repo
    • The URL to your user account page
  5. Your turn: Commit the changes.

1.5.4 GitHub for collaboration (4 min)

The “traditional” way to collaborate involves sending files over email. Problems:

  • Easily lose track of who has the most recent version.
  • Emails get buried.

Addressed by GitHub:

  • GitHub repository treated as the “master version”.
  • Use GitHub Issues instead of email.

Issues are a discussion board corresponding to a particular repository. One “thread” is called an Issue. Some features:

  • Tag other GitHub users using @username.
  • Get email notifications if you are tagged, or are Watching a repository.

As an example, check out the Issues in the ggplot2 repository.

More on collaboration next Thursday.

1.5.5 GitHub for collaboration - Activity (1 min)

Together: Watching the Announcements repo

  1. Navigate to the STAT 545 Announcements repository.
  2. Click Watch on the upper-right corner of the repo

You should now get an email notification whenever an Issue is posted.

1.5.6 GitHub for version control with git (5 min)

GitHub uses a program called git to keep track of the project’s history (more about git next Thursday).

  • Users make “commits” to form a commit history.
  • git only tracks the changes associated with a commit, so it doesn’t need to take a snapshot of all your files each time.
  • The actual changes are called a diff.

Demostration:

  • View commit history of the STAT545-home repository by clicking on the “commits” button on the repo home page.
  • View a recent diff by clicking on the button with the SHA or hash code (something like 6c0a5f1).
    • This is also useful for collaborators to see exactly what you changed.
  • View the repository from a while back with the <> button.
  • View the history of a file by clicking on the file, then clicking “History”.

Why version control?

  • Don’t fret removing stuff
  • Leave a breadcrumb trail for troubleshooting
  • “Undo” and navigate a previous state
  • Helps you define your work
  • …

1.5.7 GitHub for version control with git - Activity (5 min)

Your turn: History of the STAT545-UBC/Classroom repository.

  1. Use the commit history of the STAT545-UBC/Classroom repository to find Assignment 01 that was delivered last year in STAT 545A (Note: the course ended in mid October 2018, and the assignments were held in a folder called assignments).
  2. Add the URL of this assignment to your navigating_github.md file in your participation repository. Keep up with the commentary within the file, too. When was the assignment due?

Note: the layout and content of the assignments are changing this year.

1.6 Topic 3: Asking effective questions online (10 min)

(5 min)

We all get stuck sometimes. If you try taking preliminary measures such as googling, you may have to turn to writing a question on a discussion board. Making your question effective is an art.

To make your question effective, the idea is to make things as easy as possible for someone to answer.

  • Will they have to dig to find a resource you’re talking about, or do you provide links?
  • If your code isn’t doing what you expect, or you don’t know how to obtain an output, do you provide a reproducible example (aka “reprex”)?
    • Ideally, someone should be able to copy and paste a chunk of code to reproduce the problem you are talking about.
  • Is your reproducible example minimal, meaning you’ve removed all the unnecessary parts to reproduce the problem?

You’ll probably find that the act of writing an effective question causes you to answer your own question!

1.6.1 Asking questions - Activity (5 min)

Commenting on some online questions

  1. My turn: Start an Issue on the Announcements repo called Asking effective questions.
  2. Your turn: Find a question/issue or two that someone has posed online. Check out Stack Overflow for inspiration.
  3. Your turn: Add a comment to the newly opened Issue with the following:
    • The URL to the thread/question
    • A few brief points on how the question is worded effectively or ineffectively. What would make it better, if anything?

We’ll talk about some examples after you’re done.

1.7 To do before next class

  • Please fill out this survey, so that we can match you to your GitHub account.
  • Be sure to complete the in-class activities listed in today’s section of the guidebook.
  • Please put up a profile photo on GitHub – it makes the STAT 545 community more personable.
  • Install the software stack for this course, as indicated below. Having trouble? Our wonderful TA’s are here to help you during office hours.

Optionally, register for the Student Developer Pack with GitHub for a bunch of free perks for students!

And remember: bring your laptop to every class, as we will always have live-coding activities.

1.7.1 Software Stack Installation

  1. Install R and RStudio.
  2. Install git (this is different from GitHub!). See happygitwithr: Section 7
    • You’ll need to work with the command line.