Code Repository

We currently host our code on GitHub. This allows us to collaborate more easily, access code from any computer, save a record of past versions of the code, and branch off into different projects during development.

Setup

1. Go to the GitHub website and create an account.
2. Go to the Windows or Mac GitHub sites and download and install the GitHub client for your OS.
3. Ask an admin to grant you access to our team's repository.
4. Open the Github application and press the + button, then "clone" and select the current year's repository. Put the repository in a folder called Github inside your documents folder.

Committing

When you have local changes, you need to commit them before you can add them to the repository. Click where it says "[number] Uncommitted Change(s)" and enter a summary and description of the changes that you made in the appropriate boxes, then select which files you want to commit (usually you'll just commit all of them). Press the checkmark button to commit your changes. You should commit at the end of each work session (or when you finish a project).

Syncing

Syncing updates your local repository, and adds any changes that you made to the actual repository. To sync, press the "Sync" button in the upper-right corner of the GitHub application. You should sync at the beginning of each work session and every time you commit changes or merge branches.

Branching

To prevent merge conflicts, everybody should write code in a separate branch. A branch essentially keeps your version of the code separate, so that you can make changes without affecting the actual code in the repository. To create a new branch, click on the button with a plus sign and two branching lines and type the name of your new branch, then select "Create Branch." You can switch between branches by clicking on the button with the name of the current branch on it and selecting the branch you want. You should do all of your work in your own branch, then merge it into master or submit a pull request when you finish your project.

Merging

Once you finish your code, you need to merge it back into the master branch. To merge branch1 into branch2, switch to branch2 and select "Compare" > "branch1" > "Update from branch1". You should merge the master branch into your own branch every time changes are made to master, so that your version of the code stays up to date. Once you finish your project and test that it works, you can merge your branch back into master.

Breaking Off

Suppose the changes you want to make are too large for a simple manual merge. In this case, you might want to consider one of the following options:

Pull Request

If you have structural or other optional changes that compete with the master branch, like optimizations or refactoring, you might want to consider doing a pull request. This way, people can inspect, discuss, and expand on your changes. See here for more.

Fork

Suppose you want to experiment with a certain feature or go further in developing subsystem that may end up not be used in competition. In this case, you would want to create a new fork so you keep your work out of the master branch. See here for more.

Issue Tracking

Issue tracking is basically the software team's to-do list. We use issue tracking to keep track of what jobs need to be done and who is doing them. You can view our team's issue tracking page by opening the current year's repository on our team's GitHub page and selecting "Issues" from the sidebar.

Git-Shell

Git-Shell is a way to access git through the command line. Although it is much less intuitive than the Git client, it has greater functionality. You can learn Git-Shell here.