Upgrading WeBWorK with Github

Updating to the Latest Version of WeBWorK

If you are updating to the current release of WeBWorK, check the Release Notes for the current version.

Using Other Versions of WeBWorK

You should always use matching versions of WeBWorK and PG. In most cases different versions will not be compatible with one another.

The webwork2 and pg repositories typically contain three branches:

• main: The current stable release.
• WeBWorK-2.xx and PG-2.xx: If these branches are present, then they represent the release candidate for the next version of WeBWorK. This indicates that this version is ready for testing and early adoption.
• develop>: This branch has the latest code for the software. This branch is intended to always compile, but some features may not be fully tested or stable.

WeBWorK also maintains a tag for each previous release of WeBWorK. It is not recommended to install old versions of WeBWorK unless absolutely necessary.

• 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 main 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
   * main
    remotes/origin/HEAD -> origin/main
    remotes/origin/WeBWorK-2.20
    remotes/origin/develop
    remotes/origin/main
 git branch -t WeBWorK-2.20 origin/WeBWorK-2.20
    Branch WeBWorK-2.20 set up to track remote branch WeBWorK-2.20 from origin.
 git branch
    * main
    WeBWorK-2.20

• 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 "main" branch.
  • The "git branch -t..." sets up a local branch which tracks (syncs with) the current release candidate (which is "WeBWorK-2.20" 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 main version.
• Update pg

 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
   * main
    remotes/origin/HEAD -> origin/main
    remotes/origin/PG-2.20
    remotes/origin/develop
    remotes/origin/main
 git branch -t PG-2.20 origin/PG-2.20
   Branch PG-2.20 set up to track remote branch PG-2.20 from origin.
  

• You now have the WeBWorK-2.20 and PG-2.20 release candidates available on your server. You can switch over them using:

  cd /opt/webwork/webwork2
  git branch
    * main
    WeBWorK-2.20
  git checkout WeBWorK-2.20
  cd /opt/webwork/pg
  git checkout PG-2.20

Any time you change branches you should do the following

• Run /opt/webwork/webwork2/bin/check_modules.pl to make sure that you have the required perl modules installed.
  • If any modules are missing, you can install them either by following the relevant Installation Guide or directly from CPAN.
• Update the web dependencies for both WeBWorK and PG:

 cd /opt/webwork/webwork2/htdocs
 npm ci
 cd /opt/webwork/pg/htdocs
 npm ci

• Check the site.conf.dist file to see if there are any new settings that need to be added to your site.conf file.
• Restart the service(s) (as of WeBWorK 2.18 you will probably need to run the commands sudo systemctl restart webwork2 and sudo systemctl restart webwork2-job-queue).
• Go to the WeBWorK admin page http://your.server.edu/webwork2/admin (note that as of WeBWorK 2.19 the location of the admin page is customizable in site.conf) and click on "Upgrade Courses" on the left.

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. You will be given the option to delete these columns. If you do, then you will lose any data relating to features from the later version of WeBWorK which are not in the earlier version.

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

• To switch back

  git branch
    main
    * WeBWorK-2.20
  git checkout main

and follow the same steps listed above.

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 perl 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 cpanm command or by importing them from your distributions packages (see the Installation Guide for the version you are installing).

Updating the Open Problem Library

The WeBWorK Open Problem Library only maintains a current release. You can obtain the latest release by running /opt/webwork/webwork2/bin/OPL-update.