Using GitHub

The ATutor source code is maintained in a GitHub repository, a public version control system that provides "Social Coding" capabilities, making it relatively easy for ATutor developers to have work added to ATutor's public source code. Developers will need to become familiar with Git and GitHub if they wish to participate in ATutor development. There is plenty of documentation on using Git and GitHub. You might read through the book at Git Pro, or review the GitHub Help documentation.

4.1 Setting up a Git Development Environment

Though there are a variety of Git client applications available, working from a command prompt issuing Git commands is relatively easy to learn. Knowing a small set of Git commands is all you required to get up and running, and contributing code through GitHub.

For Mac users there is GitHub for Mac, which can be installed to setup Git on your Mac. It provides a graphical client through which GitHub can be accessed.

Windows users have a variety of GitHub clients available. A quick search will turn up many. One popular client for Windows is SmartGit. Another is Cygwin

Linux users also have a variety of Github clients available, such as Git Cola or Giggle, among others. And, of course, if you prefer to just work from the command prompt, just install git itself. Most, probably all, Linux systems have a Git package available that can be installed through their package management system. On Ubuntu or Debian for instance, as the root user issue the command apt-get install git at the command prompt.

4.2 Creating and Maintaining a Git Fork

All developers outside the core development team will work in their own fork of the ATutor source code located on GitHub. Creating a fork is pretty straight forward. Once your Github account is setup, and you have logged in, search for the atutor/ATutor repository. At the top of the screen while viewing the repository, click on the "Fork" button to create a fork of the master source code. You will now have a copy of the source code linked to your account, something like [username]/ATutor, where [username] is your GitHub login.

Now you will want to clone the fork you created into your local development environment. Using your Git client you can then find its "clone" features to generate a local copy, or at the command prompt issue the following commands:

Create a clone

git clone git@github.com/username/ATutor.git                    // create a local copy, or clone, of the fork you created on GitHub
cd ATutor                                                       // move into the cloned repository
git remote add upstream git://github.com/atutor/ATutor.git      // for later fetching upstream changes from the main ATutor repository to keep your code current

Create a branch to work in

git checkout -b new_feature                                     // to create a working branch and switch to that branch. give the branch a descriptive name.
git branch                                                      // to list the branches

Edit, create, add copies of file as you would during development

git status                                                      // to list modified files

git diff [filename]                                             // to compare and list the differences on the given script between the working branch and the main ATutor repository
git add [filename]                                              // to stage modified file, or "git add *" to stage all modified files
Repeat the above 2 steps on all the modified scripts to ensure all the modifications are what you desire and add them into the future commit.

git status                                                      // to list staged files)
git commit -m "describe the changes in a log message"           // to save the staged file to the new_feature branch you created above
git log (to list changes that were committed)

Keep your branch up-to-date

Perform these operations often

git checkout master                                             // switch to the local master branch
git pull upstream master                                        // update your local master branch with code from the main ATutor repository
git checkout new_feature                                        // switch to the local new_feature branch
git merge master                                                // merge updates in the local master to your working branch, then resolve any conflicts

After pulling from the ATutor master repository, review the latest SQL upgrade file to ensure your database structure is up-to-date (in the install/db/ directory ). The file will contain schema changes of the current pre-released source. Example: If the current working source will be version 1.9, then the upgrade file to keep track of will be named atutor_upgrade_x.y.z_to_1.9.sql, where x.y.z is the version of the currently available stable release.

4.3 Submitting code for review and addition to ATutor

git push origin new_feature                                      // push your new_feature branch to your own GitHub repository

*Go to https://github.com, login, then under "switch branches" select the new_feature branch you just pushed.
*Click on the Pull Request button, to send your code for review.
*Read through the pull request to ensure it is correct, for example "You're asking atutor to pull [1] commit into atutor:master from username:new_feature"
*Press Send pull request to finish your code submission.

Clean up when you're done

After the code has been reviewed, accepted, and merged into the ATutor master branch:

git branch master                                                // move into a branch other than the one to be deleted
git branch -D new_feature                                        // delete the branch from your local repository
git push origin :new_feature                                     // remove the branch from GitHub

Also see: Using Git and GitHub