Version 2018-Spring-1.1-Final, Revised 14 February 2018

CS-348 01, 02 — Spring 2018

GitIssueActivity

Activity for practicing with git and issues on GitHub.

For this activity, the students will practice making changes to a GitHub repository. The repository has a text file that has been "scrambled" - meaning that random words have had their characters randomly rearranged, and considered to be issues to be fixed.

The misspellings were generated by the twiddle.py program and then entered as issues by the report.py program (from this git-twiddler fork.

Prereqisites

1. Git installed and configured on your computer.
2. GitHub account created and username emailed to professor.
3. Invitation to class organization on GitHub accepted.
4. SSH key added to GitHub account.

If you have not completed these setup steps, see the instructions at the bottom of this document.

In-Class Activity

1. Fork the repository

2. Clone the repository

3. Add the original repository as an upstream remote: git remote add upstream [email protected]:CS-Worcester-CS-348-SP-2018/git-issue-activity.git

4. Repeat as often as possible during the class:

   1. Assign yourself to an issue on GitHub (e.g. issue #42)
   2. Make sure you are on the Master branch: git checkout master
   3. Pull any changes that have ocurred since your last pull, and correct merge conflicts git pull upstream master
   4. Create a branch named for the issue (e.g. issue-42), and switch to that branch: git checkout -b issue-42
   5. Edit the LICENSE.txt file to correct the issue
   6. Add the change
   7. Commit the change, with a message describing the change (include line number and correction, e.g. Correct misspelling, line 1: UGN -> GNU )
   8. Pull any changes that have ocurred since your last pull, and correct merge conflicts git pull upstream master
   9. Push the change git push origin issue-42
   10. Make a pull request to have their change merged into the original repository.
       1. On GitHub switch to the newly pushed branch.
       2. Click the New Pull Request button.
       3. Include in the pull request text a notation that it closes the assigned issue (e.g. Closes #42)
       4. Click Create Pull Request
       5. Wait for the repository owner to accept the pull request.

Instructions for Setting Up Git and GitHub

Install Git

1. Open your browser and go to: http://git-scm.com/downloads
2. The picture of the monitor on the page should show the download for your operating system. Click on the download button and save the installer.
3. Run the installer.
   1. On Windows, use the default settings, when given choices.
4. Start a command-line/terminal window, as shown below:
   1. On Windows, go to the Start menu > All Programs > Git > Git Bash
   2. On Mac OS X, go to the Applications folder > Utilities folder > Terminal
5. Configure Git, so that it knows who you are and can label your changes, and so it colors the output. Type the following commands (replacing Jane Smith and [email protected] with your own name and email address):

git config --global user.name "Jane Smith"
git config --global user.email [email protected]

Create an SSH Key Pair

SSH (Secure Shell) is a network protocol for encrypted data transmission. It is often used for password-less login to remote servers, and we will be using it to allow you to communicate with the GitLab server without having to type your password every time you want to send code changes to the server. SSH uses public-key encryption, and to use it you need to create a public-private key pair. Your public key is made available to anyone with whom you want to exchange encrypted data. Your private key is used only on your computer and should be protected carefully.

1. Create an ssh key pair by typing:
   ssh-keygen -t rsa -C [email protected]
   1. When it asks you for the filename, use the default, by hitting Enter.
   2. You should enter a passphrase when prompted. Using a passphrase will assure that no one else can use your private key, even if they gain access to the key file. When you type your passphrase, your typing will not show — not even as • or *.
2. Keep your Git Bash or Terminal window open.

Create Your GitHub Account

1. Return to your browser and go to http://github.com
2. Create an account. You may choose any username you wish, and use any email address you wish.
3. One you have completed the account creation process, let your instructor know what username you chose. You will be added to a group for the course.
4. Add your SSH key:
   1. Go to the Settings by clicking on the dropdown under your avatar at the top right of the screen. (That circle can hold a picture of you if you set an avatar under Settings")
   2. Click on the SSH and GPG Keys in the menu on the left.
   3. Clik on the green New SSH Key button.
   4. Copy your public key to the clipboard.
      1. Go back to your terminal window.
      2. On Windows type: notepad ~/.ssh/id_rsa.pub
         1. In the Notepad window, select all the text and copy it.
      3. On Mac OS X, type: pbcopy < ~/.ssh/id_rsa.pub
   5. Switch back to your browser and paste your key into the key box.
   6. Type a title for your key. (It can be anything you want.)
   7. Click the green Add SSH Key button.
   8. If you are on Windows, close Notepad.

Copyright and License

©2018 Karl R. Wurst, Worcester State University

This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.