How to work with version control using GitHub
Discover Summer Research Grant: NiC
Step 1: Create a Github account.
Step 2: Download Github app for your computer.
Step 3: Clone the repo you want to work with into your own account.
Step 4: Identify a place to put this cloned repo.
Step 5: Synchronize your working version and the github staging ground.
Step 6: Do your work in eXide.
Step 7: Commit your changes to your forked version of the repo.
Step 8: Understanding the pull request.
Step 9: Pull request.
Step 10: Do more work…and have fun!
Step 11: What happens to your pull request behind the scenes?
Log in, and find me at /tonyahowe/NiC, then in the upper right hand portion of the screen, click the “fork” icon to “fork” a copy of this master to your own Github account.
Step 1b: You should see this happen!
Use the GUI--it’s simpler! https://mac.github.com/ or https://windows.github.com/. Connect into your Github account. From here, you will need to create your own local repository from the one you forked on Github. In your local Github, click + to create a repository.
This creates a “fork” of that repo, and it is the copy of the repo you’ll be working on. Click “clone,” and you should there see the forked version of NiC as an option. Select that forked repo and click CLONE NiC when it becomes available.
This is NOT the one you’ll be working on, but it is where you’ll copy your changes once you’ve made/are happy with them in eXide. This is the one that will interface with github, on the one hand, and eXide, on the other. Think of it as a staging ground.
When you are prompted, select the GITHUB folder--this is where all the stuff you might work on that you found on github goes. Mine is at C:\users\Tonya\Documents\GitHub. Think of this space as a staging ground for anything you are collaborating on via GitHub. (You can read a blog post on my learning process here: http://cerisia.cerosia.org/?p=1118.)
Now, from eXide, you need to synchronize your working version of the app to your github staging ground. You can do this automatically: open a file from the NiC app, and then click APPLICATION-->SYNCHRONIZE. When prompted, fill in the address for your local github repository for NiC (mine is users\Tonya\Documents\GitHub\NiC), and click the “synchronize automatically” box. Now, when you make changes in exide, it will automatically sync to your local github repo--it may take a few moments to read everything.
When you’ve gotten some good work done and want to back it up onto your github space (which is where eventually the team leader will pull your edits from), you’ll open github, commit your changes, and then sync it to the web. Finally, you’ll issue a pull request, which is basically you asking me to pull your changes into the master. I will have to have added you to the repository as collaborators in order for pull requests to work. Note that none of this will change the one live at http://nic.cerosia.org--that is something I’ll update periodically.
In your github app, you should see a number next to changes; this indicates the number of files changed, which need to be committed. Here, I’ve made only one change, but you can make as many changes as you want before you commit them to your forked master repo.
Note that I have added some information in the summary and description boxes. This is important, as it is how your collaborators know what you’ve done in a quick and straightforward way! Click commit, and you’ll see a response like this:
Once you feel as though you have enough changes to make a difference and you’re ready for them to be reviewed by the team leader, you make your pull request. Start the pull request by comparing the two branches. Be sure you’re comparing the right two branches. The one you’ve forked into your own account and are working on is the head branch, and the one where you think your changes should be applied is the base branch. Github help puts it this way: “the base branch is where you think changes should be applied, the head branch is what you would like to be applied.” Usually, the defaults are correct. Read more online here: https://help.github.com/articles/using-pull-requests/.
Click the “pull request” icon, which you can do either from the github app on your laptop, or on the web. On the web, it looks like this:
Note that when you click on the pull request button, you will be prompted to explain your changes and include images of the result of your work. These should be screenshots, for instance, so the team leader or other collaborators can see what you see. This is an essential part of your pull request--do not omit it!
Your team leader will look at the pull requests and merge them into the master branch of the repository.
When the team leader logs in to github the next time, she’ll see a notification about your pull request. I’ll click on that, read about your commits, and then decide what to pull into the master branch of the project. It will look something like this: