ATutor

Learning Management System


  1. Home
  2. ATutor LMS
  3. Documentation

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

4.4 Reviewing and merging pull requests into ATutor master branch

This section is only for ATutor committers who have commit access to ATutor project repository. 

  1. Make sure the local master branch is up to date and clean.

    git checkout master                                        // move to the local master branch
git status                                                 // check the status of the master branch and make sure no new changes
git pull upstream master                                   // bring the local master branch up to date with ATutor center repository

  2. Add the developer's ATutor project repository as a remote. This only needs to be performed once.

    git remote add developerA git@github.com:developerA/ATutor.git        // replace "developerA" with an actual name

  3. Base off the master branch and create a test branch for this pull request.

    git checkout master                            // move to the local master branch
git checkout -b ATutor-test-developerA         // create and move to a test branch. 
                                               // Replace "ATutor-test-developerA" with a name that's more sensible to you
git merge developerA/branch-to-be-reviewed     // Merge in the pull request. 
                                               // Replace "developerA" with proper remote repo name added in step 2. 
                                               // Replace "branch-to-be-reviewed" with the developer's branch.

  4. Test and review the branch.

  5. Now, the pull request can be merged into the master.

    git checkout master                                         // make sure there is no accidental commits in the master branch
git log master ^upstream/master 
git merge --no-ff --log developerA/branch-to-be-reviewed    // merge into the local master branch with proper options
git push origin master                                      // push up to your own github “origin” first
                                                            // make sure everything looks good
git push upstream master                                    // push up to upstream github repository
                                                            // make sure everything looks good