Updated course09b.txt

Lynn Langit authored
revision f8fdc53b12b482f4fc1d77148089669a3954309f
course09b
# Using GitHub Source Control with TKP Students

To understand the what, why, when and how of using Github, you'll need to understand some concepts in the storage/management of software source code files:

NOTE: If you already understand GitHub, skip to the 'How' section.

## What and why
![understanding-git.png](images/understanding-git.png)
Code source control systems provide an easy way to store **all** versions of all of your code files for **all time**. This capability is vital for modern software development as software is emergent. The most commonly used source control system is GitHub. This is a public website that offers free storage for public code files. It provides an interface around the git source control system.

![understanding-git.png](images/understanding-git.png)

There are a number of key learnings in this section:

* Understand source control vs. remote storage
* Save code frequently, push to source control on save
* Use source control to keep ALL VERSIONS of code
* Write meaningful check-in comments on each commit
* GitHub is the most frequently used source control system
* Use a GUI version of the local GitHub client
* Can Use GitHub Desktop
* Understand how to revert to a previously checked-in version
* Learn when you need to use the command line to pick a specific previous version
* If working alone or with a small team, commit everything to main (master) branch
* Avoid creating branches
* Use command line to resolve merge conflicts

To understand the what, why, when and how of using the code source control system Github, you'll need to understand some concepts in the storage/management of software source code files:

_NOTE: If you already understand GitHub, skip to the 'How' section to get started with the hands on activities._

## Terms


1. **Source Code Files** - these are your code files, for TKPJava, for example 'SimpleSquare.java'
1. **IDE / Code Editor** - this is where you write your code, we use Eclipse or Codenvy
1. **Open Source Code Files** - if you copy your code files to a public open source system (website), this is called OSS development.
1. **Source Control Systems** - rather than using a file system, source control systems allow you to store, see and revert to any version of any line of all stored code file. They have a client (on your machine) and optionally a server (on a remote machine, can be on the internet) interface.
1. **Repository** - container, like a local drive (i.e. 'C:/' that holds all of the folders, code files and any other files need for your project, other files can be images, text files, etc...
1. **Open Source Code Source Control Systems** - the server interface is on the internet. The most popular is OSS is GitHub.
1. **Git** - a popular code source control tool, which can be installed both locally and on a remote server. The interface to work with Git is via the command line. The git client tools can be downloaded [here](https://git-scm.com/downloads), the git server can be installed on any remote machine, this includes remote machines hosted on the public internet. Git itself is free and open source.
1. **GitHub**:octocat: - a popular open source control system which provides a GUI (and additional features) on top of Git. GitHub is a public website. It's services, hosting public code repositories is free. GitHub also has a commercial offering, which allows clients to have private code repositories. Users can install and either git (command-line) or a GitHub GUI client to connect to the GitHub server.
1. **Tools for GitHub**- Many code IDEs include git client IDE integration (command line and/or GUI add-ins) for code source control - example Eclipse, Codenvy, VSCode...

##HowSteps in Getting Started
Because learning version control systems is a somewhat daunting task, even for professional developers, we at TKP have decided to take the 'minimum viable source control' approach to guide teachers in _getting starting_ using GitHub with their TKPJava students.

Here's a step-by-step guide:
- **Register** for an account on [GitHub.com](https://github.com/)
- **Download and Install** [GitHub Desktop](https://desktop.github.com/) - be sure to get the version for your OS (i.e. either Windows or OSX). Sign in to GitHub Desktop with your GitHub account.
- **Create a Repository** on the GitHub site - [step-by-step here](https://help.github.com/articles/create-a-repo/). If you wish to commit a change to GitHub, follow the instructions at the bottom of this link to make your first commit.
- **Link your Repository** on GitHub to a local folder using the GitHub Desktop client.
- **Write code** using your IDE and save your changes into that folder.
- **Push (or commit) your code** to your new repository via your GitHub GUI client, do this by entering a commit message, and then clicking the 'Commit and Sync master' button on the GUI, next click on the upper right 'Sync' button to send your code to GitHub

- **Use your programming tools** - here are some free code editors
- [Eclipse](https://eclipse.org/downloads/) the TKP source files include a customized set of settings for Eclipse
- [VS Code](https://code.visualstudio.com/download) simple and useful code editor
- [Beaker Notebook](http://beakernotebook.com/) great for data science languages
- [Eclipse Che](http://www.eclipse.org/che/) powerful Eclipse replacement
- [Sublime](https://www.sublimetext.com/download) basic text editor
- [Atom](https://atom.io/) hackable editor

_Note: Students must be age 13 or older to be permitted to [use GitHub directly](https://help.github.com/articles/github-terms-of-service/)._

_TIP: Here's a list of items to install to use GitHub, listed [here](https://services.github.com/checklists/)_

# GitHub QuickStart For TKP Teachers

The goal for this step-by-step guide is TKP teacher preparation to teach the TKP lesson for ***students*** ‘Intro to GitHub’:
* * *

1. **Create a folder** on your local machine for your own example repository (repo).
1. Navigate to the root C: drive, or an alternate location, i.e. ‘Downloads’ folder if you can't access C:
2. Make a new folder named ‘hello-world’ in the that location
2. **Register for a free account** on [GitHub.com](https://github.com/)
1. Note your credentials, you’ll need them for the next step
2. Leave GitHub.com open for use in subsequent steps of this guide
3. **Download & Install the free** [GitHub Desktop](https://desktop.github.com/) tool for your OS (i.e. Win or OSX).
Setup instructions below are for *first-time* use for ‘GitHub Desktop for Windows’
1. In the ‘Welcome’ dialog box
1. **Log in** with your Github.com Username and Password
2. **Configure git** by entering your email and click ‘Continue’
3. **Repositories** - you will see ‘No local repositories found’
4. **Click on ‘Dashboard’** to go on
2. In the GitHub Desktop Dashboard
1. **Delete** the default ‘Tutorial’ repo by right-clicking->remove
3. **Add** our ‘hello-world’ folder as a new local GitHub Repo
1. **Click** on the big **‘+’ (plus)** sign in the upper-left corner of the Dashboard
3. **Click** on **‘Add’**.
4. **Click** on ‘Browse’ (or 'Choose' if using a Mac) and then navigate to the ‘hello-world’ folder. Mine is on my C drive but you may need to click ‘This PC’ in order to be able to see the C: drive. My final path is: C:\hello-world
6. **Click** on the blue words, **‘C****reate & Add Repository’** and then click on ‘**Create Repository**’
4. **See** your ‘hello-world’ folder appear on the left column as a git repository, but, right now it only exists locally (on your computer). This is indicated by the little icon to the left of the words ‘hello-world’ appearing as a computer monitor. We want to sync our local repo with a remote version (copy) of itself in the GitHub.com cloud. To create a remote repo on GitHub.com we need to ‘Publish’ our local ‘hello-world’ repo.
6. **Verify** that ‘hello-world’ is not yet created remotely in your GitHub.com account, go to your GitHub.com account and look to see if you notice a repository there named ‘hello-world’. You will not see it there yet.
7. **Click** on the dark ‘Publish’ button on the upper-right side of the Dashboard.
NOTE: if you are prompted to Log in to GitHub, enter your [GitHub.com](http://github.com/) credentials
8. **Add** a ‘Description’. Type something like, ‘trying my first GitHub repo’.
9. **Click** ‘Publish hello-world’. GitHub Desktop syncs your local repo to a newly created ‘hello-world’ repo and changes the Dashboard icon from a monitor to a little book with a bookmark icon when the sync is done
11. **Refresh** your online GitHub.com account page in your browser
12. **Verify** that you can now see your remote ‘hello-world’ repo in your online [GitHub.com](http://github.com/) account.
If you don’t, go back to GitHub Desktop Dashboard and notice that the ‘Publish’ button has changed to say ‘Sync’. Go ahead and click ‘Sync’. Now you should see the repo on GitHub.com.
14. Congratulations! You’ve just created your first GitHub repository with a both a local and remote copy! We’re going to be using GitHub to get our students code up into the GitHub.com cloud as well. That’s the next step.

TIPS & NOTES: If you are using this with K-12 students, note the following:
- GitHub requires that students are 13 years old or older
guide with K-12 students:
- GitHub **requires** that students are 13 years old or older to use their service

- Students need 'install' permissions (usually administrator) on their computer to install GitHub Desktop
* * *
##Best Practices and More Information and Links:

- **Contribute to open source projects** on [GitHub](https://github.com/)
- See 5 minute intro [here](https://github.github.com/on-demand/intro-to-github/)
- Get desktop client [here](https://desktop.github.com/)
- Get the ['student developer pack' here](https://education.github.com/pack)
- See 15 minute on-line tutorial [here](https://try.github.io/levels/1/challenges/1)
- GitHub getting started guide [[here]](https://guides.github.com/activities/hello-world/)
- 4 short 'Commit yourself GitHub' screencasts [[here](https://www.youtube.com/watch?v=HmYaZWU97GM)]

##Next Steps
Git includes many other concepts, including making distributed copies via forking and branching. These concepts are often used by professional software developer teams. For a concise explanation - [see this link](https://guides.github.com/introduction/flow/).

Happy OSS Programming!

The TKP Team