From WeBWorK
(Difference between revisions)
Jump to: navigation, search
(See also)
(Revision numbers)
Line 95: Line 95:
  {{SVN checkout|repo=system|branch=tags/rel-2-4-7|dir=pg}}  
  {{SVN checkout|repo=system|branch=tags/rel-2-4-7|dir=pg}}  
=== Revision numbers ===
==== Revision numbers ====
Each time a commit is made to a repository, Subversion increments the ''revision number'' of the files and directories changed by the commit. Revision numbers allow users very fine-grained control over exactly which version of the software they check out.  Subversion will report the current revision number each time a checkout is made.
Each time a commit is made to a repository, Subversion increments the ''revision number'' of the files and directories changed by the commit. Revision numbers allow users very fine-grained control over exactly which version of the software they check out.  Subversion will report the current revision number each time a checkout is made.

Revision as of 13:45, 20 June 2010

Construction.png This article is under construction. Use the information herein with caution until this message is removed.

See also: History of WeBWorK version control

WeBWorK uses the Subversion version control system. Subversion's command-line interface is similar to CVS, and was developed to both improve upon CVS but to also be very easy for CVS users to learn. All WeBWorK installations should be transferred from CVS to SVN. Instructions for doing so can be found in Converting a CVS checkout to SVN.

This article gives a brief introduction to Subversion, how to use it to download (or checkout) the WeBWorK code, and how to keep your downloaded code (your working copy) up to date. If you are a WeBWorK developer or plan to start doing WeBWorK development, please also see SVN Commit Access. For a complete guide to Subversion, read the book Version Control with Subversion. This book is especially recommended for WeBWorK developers.


Installing Subversion

To use Subversion, you have to obtain the official command line Subversion client. Most Linux distributions will have this available in their package repositories, and many install it by default. For example,

  • to install Subversion in Ubuntu do sudo apt-get install subversion
  • to install Subversion in Fedora become root and do yum install subversion

If you use another Linux distribution or a Unix distribution, please check your OS's documentation for precise instructions on installing Subversion. (Also, please feel free to add those instructions to the list above.) Command line and GUI clients are also available for the Windows and Macintosh operating systems.

The repositories

The WeBWorK subversion repositories store all of the WeBWorK code and the National Problem Library. These repositories are hosted by the MAA at and, in fact, all of the code may be viewed on the web. Subversion also stores the history of all changes to WeBWorK, and copies of all development and production releases.

There are two main WeBWorK repositories. The two repositories are

  • system containing the core WeBWorK and PG code, and
  • npl containing the National Problem Library.

These two repositories contain all of the necessary WeBWorK software and the National Problem Library. There may be a few other problem library repositories (such as rochester), but those will soon be folded into the NPL.

If you look into these repositories, you will find three main subdirectories. Each repository uses a the fairly standard hierarchy:

  • branches
  • tags
  • trunk

The primary development work is done in the trunk subdirectory. WeBWorK itself is in the webwork2 subdirectory of the trunk, and the PG code is in the pg subdirectory of the trunk. Since many WeBWorK servers run the code in this tree for production usage, patches made in this tree must not break the code. Developers should also avoid rewriting extensive portions of the trunk as well. Such work is typically done in development branches. The trunk of the system repository has many other subdirectories, but these contain specialized sub-projects.

branches is used for major coding work, testing huge patches, and testing unstable patches. Some developers may have their own branch of the code here. It is also used to prepare new stable releases. Each major stable series gets its own directory as rel-<major_version>-<minor_version> or rel-<major_version>-<minor_version>-patches. For example, the current stable release of the WeBWorK code is rel-2-4-patches.

tags is a special hierarchy used to save the state of the software at a given point in the time. You should NEVER make any change to it as this is only useful when releasing new versions. That task is handled solely by the WeBWorK release managers.

The access mechanism to the WeBWorK subversion repositories allows anonymous users to perform any operation which involves only reading data from the repository. For most users, this usually means just svn checkout and svn update, but there are many other more specialized read only subversion commands detailed in [1].

Writing data to the repository (such as modifying the WeBWorK code) requires commit access. Like most open-source projects which use a version control system for source code management, the WeBWorK developers grant commit access on a case-by-case basis to individuals who wish to get involved with WeBWorK development and have demonstrated the skills for doing so. See Commit access requests for more information on obtaining commit access, and SVN Commit Access for a discussion of how to use it for development.

Anonymous use

As mentioned above, the WeBWorK repositories are configured so that anonymous users may perform any read operation (such as svn checkout, svn update, etc.) Below, we discuss the basic use of the most common read-only operations. This article does not discuss commands useful to developers who have commit access. That information can be found in SVN Commit Access.

Check out

The most common use of subversion is to download or checkout the WeBWorK software. In fact, we strongly recommend that you obtain the code from subversion when installing WeBWorK. For each stable release, we also provide a compressed tarball containing all of the necessary software, but installing WeBWorK from the tarball makes in much more difficult to keep up with updates and bugfixes, and should only be done if subversion cannot be used for some reason.

First, you have to check out the WeBWorK code. To do so use the following syntax:

svn checkout some_target_directory

You can browse the code structure using the web interface (ViewVC). Under system the three folders there are used for different purposes:

  • The trunk is the main development branch.
  • The branches are used for stable versions of the core WeBWorK and PG code; and for the development of complex features.
  • The tags are used to track the released versions.

The URL structure is:

/svn/system or /svn/npl/ (or /svn/rochester/)
/trunk, or /branches/rel-2-4-patches, or /tags/rel-2-4-7
/webwork2 or /pg

Unlike the old CVS, the URL is used to specify the branch or the tag.

To check out the WeBWorK 2 development trunk into the folder "webwork":

svn co webwork

To check out the PG development trunk into the folder "webwork":

svn co webwork

To check out the National Problem Library development trunk into the folder "webwork/libraries":

svn co webwork/libraries

Many institutions run their WeBWorK installation off of the trunk, and developers are careful to allow this by ensuring changes in the trunk are incremental and do not break the code. In that case the previous three commands will get you all of the WeBWorK software you need to install the system on your machine. (See the appropriate installation manual for information on how to configure your system and complete your WeBWorK installation from here.)

Many other institutions prefer to run their WeBWorK installation off of the current stable release. Doing so will provide a bit more stability. However, updates to such releases only include bugfixes, and you may not have access to the latest features until you upgrade to a new stable release containing those features. This is a trade-off, and each institution will must this decide for themselves.

To checkout the current stable release of the webwork2 and pg code to the folder webwork, do

svn co webwork
svn co webwork

Note that the National Problem Library repository is not branched - the trunk should always be used. Updates to the NPL usually include only bugfixes in library problems, and occasionally include the addition of new problem libraries contributed from institutions which use WeBWorK. Such changes will never affect the stability or security of your WeBWorK installation, and so regardless of whether your WeBWorK installation is run from the trunk or from the current stable release, you should use the command

svn co webwork/libraries

to checkout the National Problem Library.

One final comment on branches: All stable releases of the WeBWorK 2 code can be checked out of the repository from 2.0 up to the current stable release (i.e. rel-2-0-patches, rel-2-1-patches, rel-2-2-patches, etc. up to the current stable release). Again, there are no corresponding branches for the NPL, just get the trunk.

Now we come to the third of the three main divisions in the repository: tags. Tags are simply used to mark a particular state of the files in the repository, and are generally used for development purposes or for preparing a stable release (which will appear as a branch). These tagged versions of the software can be checked out just like the trunk or any branch.

For example, the rel-2-4-7 tag is used to mark a particular point in the changes to the WeBWorK code released as version 2.4. To check out this particular version of the webwork2 and pg code do:

svn co
svn co 

Revision numbers

Each time a commit is made to a repository, Subversion increments the revision number of the files and directories changed by the commit. Revision numbers allow users very fine-grained control over exactly which version of the software they check out. Subversion will report the current revision number each time a checkout is made.

For example, to check out a specific revision in the trunk of the webwork2 code, say revision 6000, do

svn co some_target_directory
svn checkout -r 6000 some_target_directory

This can be useful, for example, if your installation is tracking the trunk, and some change is made which breaks your installation or causes unwelcome behavior (rare, but possible). In that case, you can switch to the last known good revision (or any revision) with the command

svn update -r <number>
Warning : Don't leave off the "trunk", "branch" or "tag" part of any checkout. If you leave that off you check out every revision of every file in the repo, which is pretty silly and takes a long time.

Updating your working copy

Note that in the parlance of subversion, code you have checked out from the repository is referred to as your working copy. One of the primary benefits of using a version control system such as subversion is that it becomes very easy to keep up with updates to the code, including patches, bugfixes, and even larger development changes.

And, once you have obtained a working copies of the webwork2, pg and NationalProblemLibrary you will want to keep them up to date by using subversion to regularly update them.

Happily, this is very easy to do. To update your working copy and get the latest files, switch to the directory you wish to update and use the following command:

svn update (or just: "svn up")

As mentioned above, if desired, you can easily back out of an update by switching back to the appropriate revision number. Also, note that SVN, unlike CVS, doesn't need to be told to prune removed files or create new directories. This is automagic.


This concludes our introduction to subversion and discussion of the structure of the WeBWorK subversion repositories and the two most frequently used subversion commands svn checkout and svn update. Please see the links below for additional information, particularly for those who have (or want) commit access.

See also

External links

follow us