Subversion

From WeBWorK
(Difference between revisions)
Jump to: navigation, search
(External links)
 
(46 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:UnderConstruction}}
+
{{Historical}}
 +
 
 +
{{Deprecated | 2.6. Since then we have been using [[Github]] for version control. The SVN repository is no longer being updated.}}
  
 
''See also:'' [[History of WeBWorK version control]]
 
''See also:'' [[History of WeBWorK version control]]
  
WeBWorK uses the [http://subversion.tigris.org/ Subversion] version control system. To use it, you have to download the [http://subversion.tigris.org/ official command line Subversion client]. Most Linux distributions will have this available in their package repositories, and many install it by default.  For example,  
+
WeBWorK uses the [http://subversion.tigris.org/ Subversion] version control system. Subversion's command-line interface is similar to [http://www.nongnu.org/cvs/ 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 [http://svnbook.red-bean.com/ Version Control with Subversion]. This book is especially recommended for WeBWorK developers.
 +
 
 +
== Installing Subversion ==
 +
 
 +
To use Subversion, you have to obtain the [http://subversion.tigris.org/ 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 <code>sudo apt-get install subversion</code>
 
* to install Subversion in Ubuntu do <code>sudo apt-get install subversion</code>
 
* to install Subversion in Fedora become root and do <code>yum install subversion</code>
 
* to install Subversion in Fedora become root and do <code>yum install subversion</code>
  
You can also use alternative clients, such as the graphical [http://tortoisesvn.tigris.org/ TortoiseSVN] for Windows.
+
Command line and GUI clients are also available for the Windows and Macintosh operating systems.  For Windows users, [http://tortoisesvn.tigris.org/ TortiseSVN] is recommended.  
  
Subversion's command-line interface is similar to [http://www.nongnu.org/cvs/ CVS]. This is a '''basic''' and partial guide of the most useful commands. For a complete guide, use the book [http://svnbook.red-bean.com/ Version Control with Subversion]. If you have a write access to the server, it's strongly recommended that you read it and know about the advanced features of Subversion, because you might use them sooner or later.
+
Binary installation packages and/or instructions for obtaining those packages for very many different operating systems can be found at http://subversion.apache.org/packages.html.
 +
 
 +
Information on installing Subversion from source is provided at http://subversion.apache.org/source-code.html.
  
 
== The repositories ==
 
== The repositories ==
  
There are two main WeBWorK repositories, all hosted at http://wwrk.maa.org/svn/. The two repositories are
+
The WeBWorK subversion repositories store all of the WeBWorK code and the National Problem Library.  These repositories are hosted by the [http://www.maa.org MAA] at <nowiki>http://svn.webwork.maa.org/</nowiki> and, in fact, all of the code may be [http://webwork.maa.org/viewvc viewed on the web]. Subversion also stores the history of all changes to WeBWorK, and copies of all development and production releases. 
  
* [http://wwrk.maa.org/viewvc/system/ <tt>system</tt>] containing the core WeBWorK and PG code, and
+
There are two main WeBWorK repositories. The two repositories are
* [http://wwrk.maa.org/viewvc/npl/ <tt>npl</tt>] 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 [http://wwrk.maa.org/viewvc/rochester/ <tt>rochester</tt>], but those will soon be folded into the NPL.
+
* [http://webwork.maa.org/viewvc/system/ <tt>system</tt>] containing the core WeBWorK and PG code, and
 +
* [http://webwork.maa.org/viewvc/npl/ <tt>npl</tt>] containing the National Problem Library.
  
Each repository uses a more or less standard hierarchy:
+
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 [http://wwrk.maa.org/viewvc/rochester/ <tt>rochester</tt>]), 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:
  
 
* <tt>branches</tt>
 
* <tt>branches</tt>
Line 27: Line 39:
 
* <tt>trunk</tt>
 
* <tt>trunk</tt>
  
Pre-production work is made in the <tt>trunk</tt> tree. Since many WeBWorK servers run the code in this tree for production usage, patches made in this tree '''must not break the code'''. You should also avoid rewriting extensive portions of the trunk as well. WeBWorK itself is in the <tt>'''webwork2'''</tt> subdirectory of the trunk, and the PG code is in the <tt>'''pg'''</tt> subdirectory of the trunk.  The trunk of the <tt>system</tt> repository has many other subdirectories, but these contain special sub-projects used for development and testing.
+
The primary development work is done in the <tt>trunk</tt> subdirectory. WeBWorK itself is in the <tt>'''webwork2'''</tt> subdirectory of the trunk, and the PG code is in the <tt>'''pg'''</tt> 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 <tt>branches</tt>.  The trunk of the <tt>system</tt> repository has many other subdirectories, but these contain specialized sub-projects.
 +
 
 +
<tt>branches</tt> 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 <tt>rel-2-4-patches</tt>.
 +
 
 +
<tt>tags</tt> 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.
  
<tt>branches</tt> 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 (through the well-known beta &rarr; release candidate &rarr; security & maintenance fix cycle). 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 <tt>rel-2-4-patches</tt>.
+
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 <tt>svn checkout</tt> and <tt>svn update</tt>, but there are many other more specialized read only subversion commands detailed in [http://svnbook.red-bean.com/ the official Subversion book].  
  
<tt>tags</tt> 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.
+
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 ==
 
== Anonymous use ==
 
+
As mentioned above, the WeBWorK repositories are configured so that anonymous users may perform any read operation (such as <tt>svn checkout</tt>, <tt>svn update</tt>, 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]]. Note that '''unlike CVS''' Subversion does not require developers to check out an authenticated working copy in order to commit changes. Access control is only used for commits.
The WeBWorK repositories are configured so that anonymous users may perform any read operation (such as <tt>checkout</tt>, <tt>update</tt>, etc.) Developers who have commit access should see the section below on [[Subversion#Developer_use|Developer use]] for basic information on how to commit changes to the WeBWorK repositories.
+
  
 
=== Check out ===
 
=== Check out ===
First, you have to check out the WeBWorK code. To do so use the following syntax:
+
The most common use of subversion is to download or ''checkout'' the WeBWorK software. In fact, we strongly recommend that you obtain the code via Subversion when installing WeBWorK. For each stable release, we also provide a compressed [[wp:Tar_(file_format)|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. ([http://sourceforge.net/projects/openwebwork/files/ Click here] to get the tarball if you want it.)
  <nowiki>svn checkout http://wwrk.maa.org/svn/folders_to_download</nowiki> some_target_directory
+
  
You can browse the code structure using the [http://wwrk.maa.org/svn/viewvc/ web interface] ([http://www.viewvc.org/ ViewVC]). Under <tt>system</tt> the three folders there are used for different purposes:
+
To checkout the WeBWorK code and the National Problem Library, you will issue commands with the following syntax. (Note that "co" is short for "checkout" and either may be used.)
* The [http://wwrk.maa.org/viewvc/system/trunk trunk] is the main development branch.
+
{{SVN checkout|repo=<repository>|branch=<trunk, branch or tag>|dir=<files>}} target_directory
* The [http://wwrk.maa.org/viewvc/system/branches branches] are used for stable versions of the core WeBWorK and PG code; and for the development of complex features.
+
* The [http://wwrk.maa.org/viewvc/system/tags tags] are used to track the released versions.
+
  
The URL structure is:
+
In other words, after the base url <tt>http://svn.webwork.maa.org</tt>, you must first specify the '''repository''' (in most cases either <tt>/system</tt> or <tt>/npl</tt>). The repository is followed by <tt>trunk</tt> or a specification of the '''branch''' or '''tag''' you wish to obtain, and following that you must specify the particular files you wish to download. (The files are typically specified simply by referring to a subdirectory of the repository, such as <tt>webwork2</tt>, <tt>pg</tt> or <tt>NationalProblemLibrary</tt>.)
  
; transport : http://wwrk.maa.org
+
The <tt>target_directory</tt> is where in your file system you wish to place the code. [[:Category:Installation Manuals|Standard installation instructions]] recommend that the '''webwork2''' code go in <tt>/opt/webwork/webwork2</tt>, the '''pg''' code go in <tt>/opt/webwork/pg</tt> and the National Problem Library go in <tt>/opt/webwork/libraries/NationalProblemLibrary</tt>.  If <tt>target_directory</tt> is omitted, the files will be placed in a subdirectory of your current working directory.
; repositories : /svn/system or /svn/npl/ (or /svn/rochester/)
+
; branch/tag : /trunk, or /branches/rel-2-4-patches, or /tags/rel-2-4-7
+
; files : /webwork2 or /pg
+
  
Unlike the old CVS, the URL is used to specify the branch or the tag.
+
So, to review, the required URL structure is:
  
To check out the WeBWorK 2 development trunk into the folder "webwork":
+
; transport : http://svn.webwork.maa.org,
<nowiki>svn checkout http://wwrk.maa.org/svn/system/trunk/webwork2 webwork</nowiki>
+
; repository : /system or /npl (or /rochester/),
To check out the PG development trunk into the folder "webwork":
+
; trunk, branch or tag : /trunk, or e.g., /branches/rel-2-4-patches, or /tags/rel-2-4-7, etc.,
<nowiki>svn checkout http://wwrk.maa.org/svn/system/trunk/pg webwork</nowiki>
+
; files : /webwork2 or /pg (in the <tt>system</tt> repo) or /NationalProblemLibrary (in the <tt>npl</tt> repo).
To check out the National Problem Library development trunk into the folder "webwork":
+
<nowiki>svn checkout http://wwrk.maa.org/svn/npl/trunk/NationalProblemLibrary webwork</nowiki>
+
  
To check out the latest bits in some particular release branch:
+
You can browse the code structure using the [http://webwork.maa.org/viewvc/ web interface] ([http://www.viewvc.org/ ViewVC]). Browsing the <tt>system</tt> repository, you will notice three subdirectories under <tt>system</tt>:
svn checkout http://wwrk.maa.org/svn/system/branches/rel-2-4-patches/webwork2 some_target_directory
+
* the [http://webwork.maa.org/viewvc/system/trunk trunk], which is the main development branch.
svn checkout http://wwrk.maa.org/svn/system/branches/rel-2-4-patches/pg some_target_directory
+
* the [http://webwork.maa.org/viewvc/system/branches branches], which are used for stable versions of the core WeBWorK and PG code; and for the development of complex features.
 +
* and the [http://webwork.maa.org/viewvc/system/tags tags], which are used to track changes in the released versions.
  
To check out a specific version of the software:
+
Note that unlike the old CVS, the URL is used to specify the branch or the tag.
svn checkout http://wwrk.maa.org/svn/tags/rel-2-4-7/webwork2 some_target_directory
+
svn checkout http://wwrk.maa.org/svn/tags/rel-2-4-7/pg some_target_directory
+
  
Each time a commit is made to a repository, Subversion increments the ''revision number'' of the repository. To check out a specific revision of the webwork2 code, say revision 6000, do
+
Here are some common examples:
  
  <nowiki>svn checkout http://wwrk.maa.org/svn/system/trunk/webwork2@6000 some_target_directory</nowiki>
+
To check out the WeBWorK 2 development trunk into the folder "webwork":
''or''
+
  {{SVN checkout|repo=system|branch=trunk|dir=webwork2}} webwork
  <nowiki>svn checkout -r 6000 http://wwrk.maa.org/svn/system/trunk/webwork2@6000 some_target_directory</nowiki>
+
To check out the PG development trunk into the folder "webwork":
or, if you want to switch to that revision, use the update command:
+
  {{SVN checkout|repo=system|branch=trunk|dir=pg}} webwork
  svn update -r <number>
+
To check out the National Problem Library development trunk into the folder "webwork/libraries":
 +
  {{SVN checkout|repo=npl|branch=trunk|dir=NationalProblemLibrary}} webwork/libraries
  
'''Don't leave off the "trunk" or branch part!''' If you leave that off you check out every revision of every file in the repo, which is pretty silly.
+
Many institutions run their WeBWorK installation off of the <tt>trunk</tt>, 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 [[:Category:Installation Manuals|installation manual]] for information on how to configure your system and complete your WeBWorK installation from here.)
  
=== Updating the working copy ===
+
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 update your working copy and get the latest files, use the following command:
+
  
svn update (or just: "svn up")
+
To checkout the stable release 2.5.0 (September 2011) of the <tt>webwork2</tt> and <tt>pg</tt> code, go to the folder <tt>webwork</tt> and do
 +
{{SVN checkout|repo=system|dir=webwork2}} webwork
 +
{{SVN checkout|repo=system|dir=pg}} webwork
  
Note that SVN, unlike CVS, doesn't need to be told to prune removed files or create new directories. This is automagic.
+
To obtain more recent releases of the <tt>webwork2</tt> and <tt>pg</tt> code using svn go to the folder<tt>webwork</tt> and do
 +
svn co http://github.com/openwebwork/webwork2
 +
svn co http://github.com/openwebwork/pg
  
For a simple way to keep abreast of changes, one could use e.g.,
+
Note that the National Problem Library repository is not branched - the <tt>trunk</tt> 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 <tt>trunk</tt> or from the current stable release, you should use the command 
cp RELEASE-NOTES /tmp && svn up && diff /tmp RELEASE-NOTES
+
  
;What happens if I change some file, then do "svn up" and it was changed upstream too?
+
  {{SVN checkout|repo=npl|branch=trunk|dir=NationalProblemLibrary}} webwork/libraries
;:Don't worry. You will see
+
  Conflict discovered in 'lib/WeBWorK/WeBWorK.pm'.
+
Select: (p) postpone, (df) diff-full, (e) edit, (h) help for more options:
+
  
=== Making a diff ===
+
to checkout the National Problem Library.
Diffs, or patches, are text files which include all the changes done in the working copy. If you suggest a new feature in [http://wwrk.maa.org/bugzilla3/ Bugzilla] and would like to suggest a change which fixes it, upload a patch.
+
  
To create a diff from the current repository, use the following command:
+
One final comment on <tt>branches</tt>: 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. <tt>rel-2-0-patches</tt>, <tt>rel-2-1-patches</tt>, <tt>rel-2-2-patches</tt>, etc. up to the current stable release). Again, there are no corresponding branches for the NPL, just get the trunk.
  
  svn diff
+
Now we come to the third of the three main divisions in the repository: <tt>tags</tt>. 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.  
  
Normally, unlike CVS, you don't have to tell SVN which files you changed; however, you may like to diff only a part of the repository. To do that, specify the files to diff:
+
For example, the <tt>rel-2-4-7</tt> 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 <tt>webwork2</tt> and <tt>pg</tt> code do:
 +
{{SVN checkout|repo=system|branch=tags/rel-2-4-7|dir=webwork2}}
 +
{{SVN checkout|repo=system|branch=tags/rel-2-4-7|dir=pg}}
  
  svn diff webwork2/lib/WeBWorK/MyAwesomeWorK.pm
+
==== 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 of the repository as a whole each time a checkout is made.
  
Note that SVN defaults to the "unified" diff format, so the "-u" option doesn't have to be passed.
+
For example, to check out a specific revision in the trunk of the webwork2 code, say revision 6000, do
  
=== Applying a diff ===
+
{{SVN checkout|repo=system|version=trunk|dir=webwork2@6000}} some_target_directory
Subversion does not contain a built in command to apply diffs to the current working copy (for example, to review or commit diffs published in Bugzilla); instead, you can use the regular [[:en:Patch (Unix)|patch]] unix utility:
+
or
  patch -p0 < patch_file
+
  <nowiki>svn checkout -r 6000 http://svn.webwork.maa.org/system/trunk/webwork2 some_target_directory</nowiki>
  
=== Changing file structure ===
+
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
You can add files or folders to the working copy, to be included in the next diff or commit, using the command:
+
  svn update -r <number>
  svn add file.name
+
  
If you add a folder, it will add all the files included in the folder, except for files in the ignored list.
+
{{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.}}
  
You can delete files or folders from the working copy, to be deleted in the next commit or marked as such in the next diff, using the command (which will automatically '''delete''' the files from the working copy, but won't delete folders in such way):
+
=== Updating your working copy ===
  svn delete file.name
+
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.  
  
Make sure the file or folder do not have local modifications, else they won't be deleted unless you force the deletion.
+
And, once you have obtained a working copies of the <tt>webwork2</tt>, <tt>pg</tt> and <tt>NationalProblemLibrary</tt> you will want to keep them up to date by using subversion to regularly update them.
  
=== Reverting your changes ===
+
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:
If your changes in the working copy are not useful in your opinion, you can revert them using the following command:
+
svn revert
+
  
You must use parameters for this command. To revert all your changes in the working copy, use:
+
  svn update (or just: "svn up")
  svn revert -R .
+
  
To revert the changes in a specific file, use:
+
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.
  svn revert file.name
+
  
Reverting can also remove added files (they won't be deleted, just removed and considered "unknown files", just like you didn't use <code>svn add</code> at first), and restore deleted files (both deleted by hand and deleted by <code>svn delete</code>).
+
== Conclusion ==
 +
This concludes our introduction to subversion and discussion of the structure of the WeBWorK subversion repositories and the two most frequently used subversion commands <tt>svn checkout</tt> and <tt>svn update</tt>.
  
=== Checking the status of the working copy ===
+
As mentioned above, there are many more read-only commands available to anonymous users.  [[SVN Commit Access]] primarily discusses commit operations, but also contains a discussion of some read-only operations which may be of interest to those who have made changes to their local working copy of the WeBWorK code but who have not yet begun managing those changes through the central WeBWorK subversion repository or contributing those changes back to the WeBWorK project.  
You can check the status of your working copy using the following command:
+
  svn status
+
  
These are several important letters in the first column of the item, which show the status:
+
If you are actively modifying WeBWorK to improve it or add new features, we encourage you to make those changes available to all WeBWorK developers and users by managing your development through a branch in the WeBWorK SVN repositories.  Doing so is the easiest way for the lead developers to see how your changes can be incorporated into the current code base and the quickest way for your improvements to have wide usage and benefit the students and instructors who use WeBWorK.  (Also, they are very talented and might be able to help ''you''!)
* M = the item was modified by you
+
* A = the item was added by you (using <code>svn add</code>)
+
* D = the item was deleted by you (using <code>svn delete</code>)
+
* ? = the item is not under the version control, but exists
+
* ! = the item is missing (under the version control, but does not exist - probably deleted without using <code>svn delete</code>) or incomplete
+
  
== Developer use ==
+
Please see the links below for additional information, particularly for those who have (or want) commit access.
 
+
=== Auto properties ===
+
See [[Subversion/auto-props]] for how to enable automatic line-ending conversion for files you add. Every developer should use it.
+
 
+
=== Commits ===
+
Commits, or check ins, are the action of applying your changes from the working copy to the web repository. Assuming you have commit access with username <tt><user_name></tt> and password <tt><password></tt>, then you may use either of the following commands to do that:
+
svn commit --username <user_name> --password <password> --message="This is the log comment."
+
svn commit --username <user_name> --password <password> --file=file_with_log_comment
+
 
+
You may also abbreviate <tt>commit</tt> as <tt>ci</tt>.
+
 
+
Please note that Subversion requires you to enter a log message for every commit.  Also note that in your log message, if you refer to variables using Perl's '$' notation, remember to escape them from the shell.
+
 
+
== Converting a CVS checkout to SVN ==
+
Assuming you don't want to keep any local changes to files in the repository, it's easy to just overwrite everything with a fresh checkout. This will keep your local files, such as global.conf.
+
 
+
svn co <nowiki>http://wwrk.maa.org/svn/system/trunk/webwork2</nowiki> temp-checkout
+
rsync -a temp-checkout/ /path/to/webwork2 directory/
+
rm -rf temp-checkout
+
 
+
Repeat this for the pg and NationalProblemLibrary directories and you will have converted your WeBWorK CVS installation to a Subversion installation. You may now update your installation using Subversion as described above.
+
 
+
Also, if you want to get rid of the old CVS dirs:
+
 
+
find . -type d -name CVS -print0 | xargs -0r rm -rf
+
 
+
This should be done from the top level directory containing your WeBWorK installation (typically /opt/webwork). Be careful with that one because if that command is executed from any higher directory, it may delete CVS directories from other projects which you did not intend. ;)
+
  
 
== See also ==
 
== See also ==
 +
* [[History of WeBWorK version control]]
 +
* [[Converting a CVS checkout to SVN]]
 
* [[Commit access requests]]
 
* [[Commit access requests]]
 +
* [[SVN Commit Access]]
 
* [[Development policy]]
 
* [[Development policy]]
* [[Download from SVN]]
 
* [[Making Subversion faster]] - Includes instructions for checking out with svnsync and SVK
 
  
 
== External links ==
 
== External links ==
* [http://wwrk.maa.org/viewvc/ Subversion Web access]
+
* [http://webwork.maa.org/viewvc/ Subversion Web access]
 
* [http://svnbook.red-bean.com/ Version Control with Subversion] book
 
* [http://svnbook.red-bean.com/ Version Control with Subversion] book
 +
* [http://www.open.collab.net/community/subversion/articles/SvnQuickReferenceCard.html Subversion Quick Reference Card]
  
 
 
<!-- [[Category:WeBWorK Development|Subversion]] --!>
 
 
[[Category:SVN]]
 
[[Category:SVN]]
 +
[[Category:Administrators]]
 +
[[Category:Developers]]
 +
[[Category:Installation]]

Latest revision as of 17:17, 4 June 2013

This article has been retained as a historical document. It is not up-to-date and the formatting may be lacking. Use the information herein with caution.
This deprecated feature should no longer be used, but is still available for reasons of backwards compatibility.

This feature was deprecated in version 2.6. Since then we have been using Github for version control. The SVN repository is no longer being updated..


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.

Contents

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

Command line and GUI clients are also available for the Windows and Macintosh operating systems. For Windows users, TortiseSVN is recommended.

Binary installation packages and/or instructions for obtaining those packages for very many different operating systems can be found at http://subversion.apache.org/packages.html.

Information on installing Subversion from source is provided at http://subversion.apache.org/source-code.html.

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 http://svn.webwork.maa.org/ 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 the official Subversion book.

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. Note that unlike CVS Subversion does not require developers to check out an authenticated working copy in order to commit changes. Access control is only used for commits.

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 via 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. (Click here to get the tarball if you want it.)

To checkout the WeBWorK code and the National Problem Library, you will issue commands with the following syntax. (Note that "co" is short for "checkout" and either may be used.)

svn co http://svn.webwork.maa.org/<repository>/<trunk, branch or tag>/<files> target_directory 

In other words, after the base url http://svn.webwork.maa.org, you must first specify the repository (in most cases either /system or /npl). The repository is followed by trunk or a specification of the branch or tag you wish to obtain, and following that you must specify the particular files you wish to download. (The files are typically specified simply by referring to a subdirectory of the repository, such as webwork2, pg or NationalProblemLibrary.)

The target_directory is where in your file system you wish to place the code. Standard installation instructions recommend that the webwork2 code go in /opt/webwork/webwork2, the pg code go in /opt/webwork/pg and the National Problem Library go in /opt/webwork/libraries/NationalProblemLibrary. If target_directory is omitted, the files will be placed in a subdirectory of your current working directory.

So, to review, the required URL structure is:

transport 
http://svn.webwork.maa.org,
repository 
/system or /npl (or /rochester/),
trunk, branch or tag 
/trunk, or e.g., /branches/rel-2-4-patches, or /tags/rel-2-4-7, etc.,
files 
/webwork2 or /pg (in the system repo) or /NationalProblemLibrary (in the npl repo).

You can browse the code structure using the web interface (ViewVC). Browsing the system repository, you will notice three subdirectories under system:

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

Note that unlike the old CVS, the URL is used to specify the branch or the tag.

Here are some common examples:

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

svn co http://svn.webwork.maa.org/system/trunk/webwork2 webwork

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

svn co http://svn.webwork.maa.org/system/trunk/pg webwork

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

svn co http://svn.webwork.maa.org/npl/trunk/NationalProblemLibrary 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 stable release 2.5.0 (September 2011) of the webwork2 and pg code, go to the folder webwork and do

svn co http://svn.webwork.maa.org/system/trunk/webwork2 webwork
svn co http://svn.webwork.maa.org/system/trunk/pg webwork

To obtain more recent releases of the webwork2 and pg code using svn go to the folderwebwork and do

svn co http://github.com/openwebwork/webwork2
svn co http://github.com/openwebwork/pg

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 http://svn.webwork.maa.org/npl/trunk/NationalProblemLibrary 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 http://svn.webwork.maa.org/system/tags/rel-2-4-7/webwork2
svn co http://svn.webwork.maa.org/system/tags/rel-2-4-7/pg 

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 of the repository as a whole 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 http://svn.webwork.maa.org/system/trunk/webwork2@6000 some_target_directory

or

svn checkout -r 6000 http://svn.webwork.maa.org/system/trunk/webwork2 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>
Error creating thumbnail: /var/lib/mediawiki/bin/ulimit4.sh: line 4: rsvg: command not found
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.

Conclusion

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.

As mentioned above, there are many more read-only commands available to anonymous users. SVN Commit Access primarily discusses commit operations, but also contains a discussion of some read-only operations which may be of interest to those who have made changes to their local working copy of the WeBWorK code but who have not yet begun managing those changes through the central WeBWorK subversion repository or contributing those changes back to the WeBWorK project.

If you are actively modifying WeBWorK to improve it or add new features, we encourage you to make those changes available to all WeBWorK developers and users by managing your development through a branch in the WeBWorK SVN repositories. Doing so is the easiest way for the lead developers to see how your changes can be incorporated into the current code base and the quickest way for your improvements to have wide usage and benefit the students and instructors who use WeBWorK. (Also, they are very talented and might be able to help you!)

Please see the links below for additional information, particularly for those who have (or want) commit access.

See also

External links

follow us