git repository structure

Sharing course code on GitHub: A guide for web-only use of GitHub

Contents

1: Introduction
2: Setting up github
3: Managing your code
4: Sharing code with a peer & pull requests

Introduction

Sharing computer code requires more thought than just exchanging a text document. We want to preserve formatting and the language of the code itself. GitHub is a tool designed not only for code sharing but also version control. For Technology Rediscovery courses, you won't be asked to fire up the full set of Git-related tools, but rather just create an account and upload your files to the account which you can download to any computer at a later date.


motorcycle

Exercise 1: Setup your account on GitHub

Exercise type: Tool Setup

  1. Devote 5 (five) measly minutes to read about this amazing tool called GitHub on Wikipedia.
  2. Navigate to https://github.com and complete the initial registration information for creating an account on GitHub's home page. I strongly suggest you use your CCAC username for your github user. This way I can easily see who you are when we are collaborating. Choose and a password that's different than your CCAC one (good practice) and that you'll remember and that is "strong" (not the name of your dog).
  3. github register
  4. After you successfully create an account, you'll be forwarded to the welcome screen with a few options to set. Make your screen look like this--which happens to be the default choices.

    warningNOTE that your account is public, meaning each and every file you post on here is viewable to the world without password restriction. This account is FREE if you keep your work public. This system encourages collaboration and sharing, and is fantastically valuable to maintaining a free and open Internet society.

  5. github register
  6. Provide some account setup information to be a good online citizen:
  7. github register
  8. You are optionally encouraged to read the startup guide for GitHub which reviews the features of the system that you hopefully will start using someday, but are not required to use for CIT111 Intro to Programming Java.
  9. At the welcome screen, click "Start A Project"
  10. github register
  11. Verify the email address you provided GitHub and sign in again with the login screen you're sent to when you click the link in your email from GitHub.
  12. Click on "Start A Project" again
  13. The next screen you land at is a chance to make your first repository on GitHub which is a collection of files that are managed as a bundle so changes can be seen, reverted to, and updated. Please Name your repository "cit111_ccac" with no caps or spaces.
  14. github register
  15. Describe your repository something useful, like the example below.
  16. Maintain the selection for your repository to be "Public".
  17. Check the box: Initialize this Repository with a README
  18. You have no files to ignore adding to the repository so you don't need to change the selection for the "add .gitignore" drop down box.
  19. Take a moment and click the little circled i to read about different code licenses. Your instructor feels passionately that you should choose to allow your code to be reused by others since we're building our course on shared code (including all of this web content, images, etc.). Two good choices are the Apache License 2.0 or the GPL v.3.0.
  20. Check your work and click "Create Repository"
  21. You'll be directed to your repository home page and then you're ready for exercise 2: Managing your files in GitHub

arrow_upward


motorcycle

Exercise 2: Managing your class code in a GitHub Repository

Screen cast of creating repo, pulling down changes, and pushing new index objects

git repo video

This sequence walks you through how your instructor proposes you manage and share your code in this GitHub repository. NOTE that we are going to basically use your GitHub account as a place to dump files and download them to other computers. If you are an eager coder and anticipate coding in the future, you should read the many tutorials on actually managing all your code in GitHub using the commit process.

  1. Your repository's landing page is a lot like a shared drive, with the files you've shared listed with a note next to each that contains the most recent message written with the file was "committed" which we can think of as "saving". When we click a file, we can view it first, and then choose to edit it.
  2. github register
  3. Let's go ahead and update your README.md page. Click the filename "README.md".
  4. highlightNOTE: The extension ".md" stands for "markdown" which is a simple way to create formatted documents in GitHub and other online tools. You will want to review the basics of this approach on the markdown guide page I found with an internet search for "github markdown guide"

  5. The first page you'll see is the file displayed in read only mode. Everybody in the world can see this view. We want to click the "edit" icon in the upper right.
  6. github register
  7. Now you have an editable page to add some biographical text about yourself. Remember, you very well should link your GitHub account on your social media or LinkedIn site and put it on resumes for techy jobs. So make your bio professional and INTERESTING! You can add headers by prefixing the line with ## and then a space and then text that will be formatted as a header when the page is rendered by the github file viewer.
  8. github register
  9. Once you have changed this file to your satisfaction, scroll down to the bottom of the page and commit your changes. Before you do, add a single sentence description in the single-line text entry box that describes what you changed in the file. You can add a longer description for files that you make serious changes to. When you are ready, click the green "Commit Changes".
  10. github register
  11. You'll now be directed back to your repository home page to do as you please. In our case, we want to upload our first Java file!
  12. github register
  13. Our goal here is to tell GitHub where on our computer the file is that we want to upload. Let's practice with a Java source code file we created for week4 called RoadTrip.java. Find RoadTrip.java in your project browser like in the image below:
  14. github register
  15. In order to tell GitHub where the file is, we need to know where it is! The easy way to get that specific file's location is by right clicking the file name in the project pane and selecting properties.
  16. github register
  17. Note that in my properties window, I can see the full path to my .java file. (Your instructor refuses to run proprietary software like Microsoft Corporation's Windows OS unless absolutely necessary, so you're seeing a file path for a file inside the completely free and open source Linux operating system.) But your file path will be just as instructive: it will show you the directory path to the file.
  18. github register
  19. Let's learn a little about how NetBeans organizes its files. To do this, open up Windows Explorer or a file browser and practice finding the correct location of the file we're interested in uploading to GitHub. The usual place our NetBeans files are saved is inside a subdirectory located in a directory ("folder") called NetBeansProjects which is usually located inside your user's Documents or home folder, depending on your platform.
  20. When you navigate into NetBeansProjects, you'll find directories that correspond to your project names. Inside those, you'll find directories that contain various directories: we want "src". Inside src, you'll find your java packages, each as a directory. In our sample case, the project is cit111OnlineCourse, the package called "week3" and the java file is in there called RoadTrip.java. My file browser looks like this, and yours will have the same features, but probably looks different on the surface:
  21. github register

    highlightSome of you might be thinking: What a pain all this directory stuff is!. Remember, you're now a computer programmer and we must understand what NetBeans is actually doing when we're making projects, packages, and files. There's no magic back there--just code that executes instructions. Take time to understand tools now so you can use them effectively in the future.

  22. Okay, now that we know where the file is on our computer, we can tell GitHub where it is, and it will manage the uploading. So back in GitHub, click "choose your files" and navigate the file browser window to the correct location to upload RoadTrip.java. See my example:
  23. github register
  24. If all is well, you'll see that the file name appears at the bottom of the upload block on the page. You can now add a commit message at the bottom of the screen and click "Commit Changes" when you're happy:
  25. github register
  26. When the system is done processing, you should see your recently added .java source code file in your master repository list, as shown below:
  27. github register
  28. When we click the file name in the repo home, we can see the file in read only mode:
  29. github register
  30. Let's imagine that you just finished uploading the file and realized you forgot to add a nice comment describing what your class does. You have a few options: the first is to click the edit button again like we did for the README.md file and change the code directly in GitHub. This is an okay option for folks who aren't managing their whole work in CIT111 through NetBeans, in which case the file should be changed in NetBeans and then committed locally and pushed up to the server.
  31. The best option is to change the file in your NetBeans account and re-upload the file in GitHub. If you have changed the file since you last uploaded it, by re-uploading the file, all previous changes are not shown and only the most current change is shown. This is a good solid start.
  32. Whew! Now we have code online in GitHub! Now what? When you are ready to submit code for review, you'll want to copy the URL to the file when you're viewing it in read only mode:
  33. github register
  34. Once you have the shared upload spreadsheet open, paste the URL into a row that you've populated.
  35. github register

Add code to peer project and do pull requests

  1. Become a collaborator on your peer's github account. Follow this sequence to make a peer a collaborator: log into github >> settings >> manage access >> Invite teams or people >> locate user >> select
  2. Peer must approve collaboration request via email
  3. Clone down your peer's repository to your local system
  4. Create your own branch on which to make changes to code
  5. Add changes and commit on your branch
  6. Push your changes to your peer's respository
  7. Log into github.com >> naviate to your peer's repo >> pull requests >> new pull request
  8. Select the appropriate base branch into which your changes should be mereged; select your topic branch
  9. Write a brief description of the changes you made so the reviewer is oriented to the goals of the changes
  10. Click Create Pull Request
  11. Repository owner reviews the pull request and approves changes, fully baking in the merge.
  12. Both coders can then run a git pull on the base branch, thereby completing the pull request sequence.

Page created on 19 Feb 2018 and last updated on 26 March 2020 and can be freely reproduced according to the site's content use agreement.