Github

WeBWorK software download

WeBWorK online homework software is located at http://github.com/openwebwork.

webwork2 -- the instructor and user interface
pg       -- the macros for rendering questions
webwork-open-problem-library  -- library of 35K+ homework questions

Github Overview

The page Github Overview provides a more conceptual description of git and Github.com. It has instructions for using git and github as a developer as well as additional advanced tricks and shortcuts for keeping a WeBWorK installation up to date.

Quick instructions for updating WeBWorK to the GitHub version

• Upgrading_WeBWorK_with_Github more recent version of these notes for those already using github.
• Category:Release_Notes
• You will need root access to the apache webserver via "sudo" in order follow the instructions below.
• You will need to prepend "sudo" to many of the commands below in order to obtain the permissions needed to make these changes.

Quick instructions for using other branches of webwork

You may want to use the current stable candidate release branch of WeBWorK instead of using the "master" branch. You might want to do this because the upcoming release branch has a new feature that you want to use right away, or you might like to help out with the final testing of the new branch. These instructions tell you how to download the new branch, how to switch to it, and how to easily revert back to the original "master" branch if there are difficulties or when you are done testing.

• These instructions tell you how to obtain recent branches of the webwork2 repository. The analogous procedures on the pg directory will obtain the various branches of the pg repository.
• You can view the WeBWorK repository online to see what is available.
• 6/17/2013: we have just merged the release/2.7 branch into the stable master branch at tag WeBWorK-2.7 and for PG at tag PG-2.7. Within a few weeks we should have candidate release branches for PG (which updates more frequently) and shortly after that release/2.8 for WW.
• First use git to download the information about the branches of WeBWorK in addition to the master branch.

 cd /opt/webwork/webwork2
 git remote -v
      origin	https://github.com/openwebwork/webwork2 (fetch)
      origin	https://github.com/openwebwork/webwork2 (push)

This is the default setup. The reply to the remote command says that "origin" is connected to the standard repo at github.com.

 git fetch origin
 git branch -a
   * master
    remotes/origin/HEAD -> origin/master
    remotes/origin/develop
    remotes/origin/master
    remotes/origin/release/2.8
 git branch -t release/2.8 origin/release/2.8
    Branch release/2.8 set up to track remote branch        release/2.8 from origin.
 git branch
    * master
    release/2.8

• This sequence of commands does the following
  • Obtain information about all of the branches at the "origin" repository.
  • List all of the branches available. The * indicates that we are currently using the "master" branch.
  • The "git branch -t..." sets up a local branch which tracks (syncs with) the current release candidate (which is "release/2.8" in this case)
  • The final check "git branch" shows that you now have access to two versions on the software, downloaded to your machine. The * indicates that you are currently using the master version.
• Update pg (for some version changes it is necessary to update both pg and webwork2 but often they can be updated independently. The pg and webwork2 version numbers do not always match since pg is updated more frequently.)

 cd /opt/webwork/pg
 git remote -v
      origin	https://github.com/openwebwork/pg (fetch)
      origin	https://github.com/openwebwork/pg (push)
 git fetch origin
 git branch -a
   * master
    remotes/origin/HEAD -> origin/master
    remotes/origin/develop
    remotes/origin/master
    remotes/origin/release/2.7x
 git branch -t release/2.7x origin/release/2.7x
   Branch release/2.7x set up to track remote branch        release/2.7x from origin.
  

• Switch over the webwork2 release candidate release/2.8 and to pg version release/2.7x

  cd /opt/webwork/webwork2
  git branch
    * master
    release/2.8
  git checkout release/2.8
  cd /opt/webwork/pg
  git checkout release/2.7x

• Run /opt/webwork/webwork2/bin check_modules.pl to make sure that you have the required CPAN modules installed.
• Now restart your apache server (the command for this might be "sudo apachectl graceful")
• Go to the webwork admin page http://your.server.edu/webwork2/admin and upgrade the relevant course databases.

Notice: Configuration updates to webwork2 become relatively painless once you start using the new configuration files.

• In most cases you will no longer have to update any configuration files.
• Default configurations for new features will be automatically provided in the defaults.config.dist file.
• Your local directory configuration structures remain unchanged in sites.conf as do your local overrides in localOverrides.conf.
• Always customize configurations in default.config.dist by using localOverrides.conf.
• You should seldom, if ever, modify default.config.dist. If you do, you become responsible for managing and merging changes to that file.

It is also easy to back out to a previous release.

• To switch back

  git branch
    master
    * release/2.8
  git checkout master

and restart your apache server.

What could possibly go wrong

• You get what look like database errors of some kind -- missing fields in tables, etc. when looking at a course.
  • Most likely you didn't upgrade the course databases from the web using the WeBWorK admin page
• You get a long message about "not finding HTML::Scrubber" looking in ..... various directories
  • The message looks scary but simply indicates that some required CPAN module has not been installed on your site. Perhaps you forgot to run check_modules.pl or perhaps the maintainers neglected to include a required module in the new version of check_modules.pl. (If this is the case please report the bug.) They are easily installed using the cpan command or by importing them from your distributions packages.

Quick instructions for updating one of your branches

• To update one of the standard webwork branches

 cd /opt/webwork/webwork2
 git branch 
    * master
 git pull

This updates the current branch "master" to agree with any changes that have been made on the openwebwork repo. If you wish t o update the release/2.8 which is tracking release/2.7 on the openwebwork repo then follow the same procedure but first switch to the release/2.8 branch using the command

  git fetch origin     # update index information about branches on github.com/openwebwork
  git branch -t release/2.8 origin/release/2.8  # create a local branch which "tracks" release/2.8
  git checkout release/2.8 # change to 2.8 branch
  git pull    # to update from release/2.8
  git checkout master   # return to the master branch.

• Those wishing to update from other sources than github.com/openwebwork should read the WeBWorK developer instructions for using the advanced features of git.

Github Overview

References for GitHub and Git

For those who are ready for complete immersion into all things git -- here are several references.

• Pro Git book http://progit.org/

(unreviewed at the moment -- YMVV)

• http://gitref.org/ quick reference
• https://help.github.com/articles/using-pull-requests
• https://github.com/blog/966-improved-subversion-client-support
• git cheat sheet: http://byte.kde.org/~zrusin/git/git-cheat-sheet-medium.png
• Version Control by Example by Eric Sink which is available at http://www.ericsink.com/vcbe/
• http://nvie.com/posts/a-successful-git-branching-model/ a potential workflow model for WeBWorK development -- we're still working on refining a workflow
• see also Git for more references