Upgrading WeBWorK with Github

Quick instructions for updating one of your branches

• To update one of the standard webwork branches

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

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

  git checkout release/2.7

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

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.
• 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.8
 git branch -t release/2.8 origin/release/2.8
   Branch release/2.7x set up to track remote branch release/2.8 from origin.
  

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

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

• 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.

• Update webwork-open-problem-library in the same way
• Run /opt/webwork/webwork2/bin/OPL-update to update the library database.

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.
• For releases which add new fields to the database to support new question features it will be necessary for the site administrator to run "Upgrade courses" from the "admin course". This will add the extra fields to the database.

If you switch back to an earlier version of WeBWorK after upgrading then on the upgrade courses page you will see warnings about "extra" fields in the course database tables which are not in the schema. These extra fields are simply ignored and do not interfere with the normal behavior of WeBWorK.

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.