{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# GitHub Basics\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Why are we using GitHub? \n",
"\n",
"_**Note: I use Windows and will be of less help for Mac users. The TA, however, uses Mac and will be more helpful when issues stem from OS differences. GitHub, in particular, might be finicky if you have outdated versions of Safari or any other browser.**_\n",
"\n",
"We will be using [GitHub](https://github.com) a lot in this course:\n",
"\n",
"- All of your course-related work will go on GitHub.\n",
"- Discussion / help / announcements will happen on GitHub. (Yes, announcements!)\n",
"- This entire textbook is on GitHub!\n",
"- Assignments are \"posted\" and \"submitted\" on GitHub.\n",
"\n",
"But why GitHub? Because it's tremendously effective for developing projects. It is used by [Apple](https://github.com/apple), [Uber](https://github.com/uber), [Netflix](https://github.com/Netflix), Google, Microsoft, Bitcoin, CERN, Chinese censors (wait, what?), and many more large, sophisticated, multi-billion dollar entities.\n",
"\n",
"It's useful for \n",
"1. cloud storage,\n",
"2. collaboration,\n",
"3. and version control.\n",
"\n",
"Let's get started!\n",
"\n",
"### GitHub as cloud storage\n",
"\n",
"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:\n",
"\n",
"- __Repositories (aka \"repo\")__: All files must be organized into _repositories_. A repo is just a folder for a **self-contained** project. Repos can either be _public_ (like [this textbook](https://github.com/LeDataSciFi/ledatascifi-2022/)) or _private_ (like your assignments).\n",
"- All repositories belong to a __user account__ or an __organization account (aka \"org\")__: \n",
" - A _user account_ is the account you just made, and typically holds repositories related to your own work. [Here is mine.](https://github.com/donbowen/)\n",
" - An _organization_ account can be owned by multiple people, and typically holds repositories relevant to a group. The [LeDataSciFi organization](https://github.com/LeDataSciFi/) account is owned by me, and contains the textbook and all of our assignments.\n",
"\n",
"Examples: \n",
"\n",
"- The [`awesome-python`](https://github.com/vinta/awesome-python) repo is a \"curated list of awesome Python frameworks, libraries, software and resources\" \n",
"- The [`ledatascifi-2022`](https://github.com/LeDataSciFi/ledatascifi-2022) repo, within its corresponding [LeDataSciFi](https://github.com/LeDataSciFi) Org contains this textbook. \n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### GitHub for collaboration \n",
"\n",
"The \"traditional\" way to collaborate involves sending files over email. But emails get buried, and, also... who has the most recent version, and what is it?\n",
"\n",
"\n",
"\n",
"Git(Hub) solves this! \n",
"\n",
"Git (just \"Git\") is a distributed version control system. Basically: \"Imagine if Dropbox and the \"Track changes\" feature in MS Word had a baby. Git would be that baby.\" It's great for us because it's optimized for code. \n",
"\n",
"GitHub (not just \"Git\") is built on top of the Git system. Among the many added features that make collaboration easier, three are worth highlighting:\n",
"\n",
"1. The repo hosted on GitHub's servers is the \"remote\" version. \n",
" - You and collaborators can download (\"fetch\") the remote repo to your computer. The folder and files on your computer are called the \"local\" version.\n",
" - You work on the files on your computer. When you're done, you upload (\"push\") your work back to the cloud to update the remote version.\n",
" - If you've ever used a shared Dropbox folder, fetching and pushing are done automatically by Dropbox.\n",
" - We have to do these steps manually using GitHub Desktop, but for good reason. \n",
" - Use the [GitHub Workflow](#github-for-version-control) to make sure you and your collaborators don't make conflicting changes to a file. \n",
"2. [GitHub Issues](https://guides.github.com/features/issues/) make it easier to track project tasks than using email. \n",
" - Each repo has an _Issues_ tab that functions as a discussion board.\n",
" - One \"thread\" is called an Issue. \n",
" - You can tag other GitHub users by typing `@username`. E.g. using `@donbowen`. \n",
" - You get email notifications if you are tagged, or are `Watch`ing a repository.\n",
" - As an example, check out the Issues in the [`ggplot2`](https://github.com/tidyverse/ggplot2/issues) repository. People raise issues of all kinds, and then when they are solved, \"Close\" the issue. \n",
" - [You can create issues on the repo for _this_ textbook to point out errors or suggest edits. Contributions are appreciated and rewarded!](https://github.com/LeDataSciFi/ledatascifi-2022/issues)\n",
"3. GitHub orgs have \"team\" discussion boards. Our class has one! \n",
"\n",
"```{tip}\n",
"When you have a question about your grades or a private question about an assignment, you can open that repo, click on the \"Issues\" tab, and create a new issue. Make sure to tag me and the TA in the text so we see your post.\n",
"```\n",
"\n",
"We will talk more about specific methods of collaboration later in the class. Suffice it to say, managing group tasks is of paramount importance in virtually all jobs you might have after college."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### GitHub for version control \n",
"\n",
"Version control is a time machine! \n",
"\n",
"- Instead of the awful \"file naming conundrum\" in the comic above, you just keep one file, \"FINAL.doc\"!\n",
"- Delete stuff and recover it later easily \n",
"- Leave a breadcrumb trail for troubleshooting - if some update broke your code, you can go back and see what changed when it broke\n",
"- \"Undo\" and navigate a previous state\n",
"- Helps you define your work and show contributions.\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Using GitHub\n",
"\n",
"### Necessary skills\n",
"\n",
"These skills require a mix of using the GitHub.com website and the GitHub Desktop app. We will cover these in class, by example. You should have all these covered by the third class:[^adv]\n",
"\n",
"```{margin}\n",
"I think you can use these check boxes to track your progress, if you'd like. \n",
"```\n",
"\n",
"[^adv]: Students with GitHub experience, or those looking into issues later, will notice I am skipping past forks, branching, and using `git` commands. This is because GitHub is a means to getting the class going and not the target skill for the course. \n",
"\n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
" \n",
"\n",
"\n",
"### Necessary exercises\n",
"\n",
"In class, I'll give you a handout with a list of steps to follow. In summary, before the second class, you should have\n",
"\n",
"1. Cloned the textbook to our computers _(fetching this repo after each class will download the slides as I post them)_\n",
"1. Created your own \"Class Notes\" repo, and \n",
" - Invited me and the TA to it\n",
" - Created a file named README.md, and added useful content to it from the GitHub browser page for the repo\n",
" - Cloned it to your computer and worked on it there\n",
" - Synced your work back to the cloud\n",
"1. **It is VERY IMPORTANT to join the classmates \"team\" so you GET ANNOUNCEMENTS!** Do these:\n",
" 1. Click on the \"gradebook\" or \"assignment 1\" links in coursesite. Wait for an email.\n",
" 2. When I invite you to the LeDataSciFi organization, accept it. \n",
" 1. [Find the `classmates` team within the LeDataSciFi org](https://github.com/orgs/LeDataSciFi/teams/classmates-2022https://github.com/orgs/LeDataSciFi/teams/classmates-2022). This is where class announcements will be posted. **Make sure you are \"watching\" it.** You should now get an email notification whenever an Issue is posted by myself, the TA, or if your classmates ask a question.\n",
"1. Introduced yourself to your classmates on the team discussion board. Look for the \"introductions\" topic. \n",
"1. **Download a file from GitHub.com:** Go to any repo, and click on any file. On the next page that opens, right click the \"Raw\" button and \"Save Link As\". \n",
"\n",
"### Optional exercises \n",
"\n",
"When you push changes to a repo, Git doesn't upload the whole file. It sends \"commits\", which are records of _changes_ to files in the repo (called a _diff_). This reduces bandwidth needs and makes it easier to track specific changes.\n",
"\n",
"These exercises will help you with the time-machine aspects of GitHub:\n",
"1. View commit history of the [LeDataSciFi.github.io](https://github.com/LeDataSciFi/LeDataSciFi.github.io) repository by clicking on the \"commits\" button on the repo home page. (You'll end up [here](https://github.com/LeDataSciFi/LeDataSciFi.github.io/commits/master).)\n",
"1. View a recent \"diff\" by clicking on the description of the commit or the button with the _SHA_ or _hash_ code (something like `990cf9a`).\n",
" - **This is also useful for collaborators to see exactly what you changed.**\n",
"1. View the repository from a while back with the `<>` button.\n",
" - Before the `990cf9a` commit, this folder looked VERY different!\n",
"1. View the history of a file by clicking on the any, then clicking \"History\".\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Credits\n",
"\n",
"- I have drawn heavily from [STAT545](https://stat545.stat.ubc.ca/)\n",
"- [QuantEcon.org](https://quantecon.org/QuantEcon.org)\n",
"- [EC607](https://raw.githack.com/uo-ec607/lectures/master/01-intro/01-Intro.html#1)\n"
]
}
],
"metadata": {
"celltoolbar": "Tags",
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.12"
}
},
"nbformat": 4,
"nbformat_minor": 4
}