Submitting problems to the OPL
One of WeBWorK's most attractive features is the National Problem Library, a collection of over 20,000 problem files contributed to the project by faculty from a wide variety academic institutions. The procedures outlined here are intended to encourage others to contribute problems to the NPL, but also to maintain high standards for the problems contributed.
Contents
Who can contribute to the NPL?
Anybody can contribute to the NPL. However, generally speaking, prospective contributors should be familiar with WeBWorK and have a reasonably good understanding of the PG language and the MathObjects framework. Contributors are typically faculty at academic institutions which use WeBWorK, or under the direction of such faculty. At a minimum, prospective contributors must be registered users on this wiki; ideally, prospective contributors will be active members of the WeBWorK community or have been in the past. The characteristics listed here aren't intended to exclude anyone from contributing, but to give an idea of the background of the contributors who have collectively built the NPL into the valuable resource it has become.
If you have already written a collection of high-quality WeBWorK problems and tagged them properly, we will gladly consider the collection for inclusion in the NPL. A collection of problems can be submitted all at once, when the collection is complete, or the collection can be built over time in a dedicated subdirectory of the WeBWorK NPL Subversion repository (a so-called "branch" of the repository). There are many advantages to this second approach. One particular advantage is that your problem collection can be reviewed and tested as problems are added. This incremental review is generally more efficient and more thorough than is possible for collections contributed all at once. As a result, problem collections built through a Subversion branch can be added to the main development trunk of the NPL soon after they are complete, whereas there may be a substantial delay for problem collections contributed all at once.
The mechanics of contributing to the NPL
If you have a completed problem collection to contribute, simply contact the WeBWorK developers to let them know and they will work with you to review your collection and prepare it for inclusion in the NPL. You can contact the WeBWorK developers by email or by posting in the Moodle forums. (The forums are probably the best place to do this.)
If you wish to build a problem collection in a branch of the NPL Subversion repository, you will also need to contact the WeBWorK developers to request this. Again, this can be done by email or in the forums. (Again, the forums are the preferred...uh...forum). When your request is approved, you will be given a branch of the npl repository at http://svn.webwork.maa.org/npl. If your branch is called my_branch, then it will be located at
http://svn.webwork.maa.org/npl/branches/my_branch
Initially, your commit access will be restricted to your branch of the npl repository. This is intended to give new contributors space to learn how to use SVN without worrying that they might somehow ruin some established part of the NPL or even the WeBWorK system code. Since you can only write changes to your branch, you can't ruin anything outside of that branch. And, you can't even really ruin anything inside your branch either because any change you make can be reverted and SVN stores the entire development history in its database. (For example, right now you could, if you wanted, get a copy of WeBWorK exactly as it was on March 3, 2005 - or any arbitrary date since WeBWorK started using version control).
Now, generally, branches are considered temporary. When your problem collection is complete and ready to be formally contributed to the NPL, your branch will be merged into the trunk of the npl repository and the branch will be deleted. You will then be given authorization to contribute your work to the trunk of the npl repository. If you later start to do development on the WeBWorK system code, you can then also be given commit access to the system repository.
First Steps
Once your branch is created, you will want to set it up so that it is easy to merge back into the NPL trunk.
To get started, first create a sub-directory to the NationalProblemLibrary directory on the server to hold the problems you create. We ask that your subdirectory be named after your institution. Have a look at the current subdirectories of the NationalProblemLibrary directory to get an idea of an appropriate name for your subdirectory. Supposing you decide on my_univ, then add it as follows:
svn mkdir http://svn.webwork.maa.org/npl/branches/my_branch/NationalProblemLibrary/my_univ \ -m "Creating initial my_univ directory" --username <username> --password <password>
Whenever you issue a subversion command which results in writing to the repository you must enter a log message and provide your credentials. Ordinarily, you will not use such commands to operate directly on urls as shown here. We did so in this case so that you may now decide either to checkout the NPL from your branch along with your new directories or just check out your new directory. You may wish to also checkout all or part of the NPL to help with fixing bugs.
To check out only your new directory do
svn co http://svn.webwork.maa.org/npl/branches/my_branch/NationalProblemLibrary/my_univ
This will create a new directory my_univ in your current working directory. Leaving off my_univ/ would check out the NPL copy in your branch. You may append a path to that command to control the location of your checkout. If you have already written problems that you would like to add to your branch, you can now do so by changing to the my_univ directory (or wherever your branch was checked out to) and adding those problem files with the command:
svn add /path/to/problems
Then
svn ci -m "Log message"
will upload your problem files and add them to your branch (with the existing directory structure, but under the my_univ directory). Note that svn ci is a short cut for svn commit and can be remembered as check in. Also, svn co is a short-cut for svn checkout.
Now, this is important but is easy to forget at first: Whenever you want to change the structure or organization of your problem collection by, for example, creating a new subdirectory, moving (or renaming) a file or subdirectory, or deleting files or subdirectories, you must do so using a Subversion subcommand. For example, to create a new directory subdir1 under my_univ, you would use the command, executed from within the my_univ directory,
svn mkdir subdir1
An overview of the svn commands most frequently used in during development is given in SVN Commit Access. That article should get you started, but eventually you will also want to read at least Chapters 1 and 2 of the Subversion Book.
Standards for problems contributed to the NPL
This section focuses purely on the technical standards for problems contributed to the NPL. We also hope that the problems contributed to the NPL will adhere to very high pedagogical standards as well. However, problems contributed to the NPL are not evaluated from that point of view. We leave it to the instructors using WeBWorK to determine which NPL problems will have the most pedagogical value in their particular circumstances.
Firstly, authors should make every effort to ensure that the problems they contribute have no bugs. In particular, authors should test problems using multiple seed values. Ideally, the problems contributed will actually have been used in a live class for a semester or more.
Secondly, authors should adhere to best practices for problem authoring. This includes use of MathObjects for defining and manipulating the mathematical objects in the problem and the use of PG language constructions for display constants and other formatting issues. In particular, authors should generally avoid direct use of HTML to format problems since this makes it impossible to print hard copy versions of the problems. The authoring documentation in this wiki has extensive information about this, including a very helpful index of problem techniques which illustrate best practices.
Thirdly, problem collections submitted to the NPL must be properly tagged.
Fixing bugs
If you plan to also use your Subversion branch to contribute bug fixes for NPL problems, you should first familiarize yourself with Bugzilla and review the list of bugs filed against the problem libraries. Please only fix bugs listed in Bugzilla. If you believe something is a bug, but it is not listed in Bugzilla, then first report it in Bugzilla, ideally along an offer to fix it. Once the bug is confirmed and assigned to you, only then fix it. You should not alter NPL problems for any reason other than to fix a reported and confirmed bug. However, you can fix bugs that are not assigned to you. Remember, this is all happening in your own branch of the NPL repository. The assignee will see that you committed a fix, review it to check that it does fix the bug, and assuming there are no problems he can merge the change into the trunk.
Syncing your branch with the trunk
When using your branch to fix bugs in the NPL, you will want to make sure that your branch stays in sync with any changes to the trunk so you don't fix bugs that were already fixed. Also, new changes to the trunk will not automatically filter into your branch. To sync your branch with the trunk proceed as follows:
First, commit any recent changes to your branch. If your branch has any uncommitted local modifications, then the merging will fail. Then make sure you are in the root directory of your branch
$ pwd /home/user/my_branch
and run
$ svn merge http://svn.webwork.maa.org/npl/trunk
After running this, your branch working copy now contains new local modifications, and these new local modifications are duplications of all of the changes that have happened on the trunk since you first created your branch or since your last merge. Usually this will complete without any trouble and you can then commit the new changes to your branch. However, if you changed an NPL problem in your branch before the merge, and somebody else committed a change to that same problem in the trunk, then you will probably have to resolve a conflict. See SVN Commit Access for guidelines for handling that.
Once you have resolved any conflicts you now have a working copy of the software on your machine which incorporates your changes and the changes in the trunk. The final step in the process is to commit your working copy to update your branch in the repository.
svn commit -m "Merged latest trunk changes to my_branch."
It's a very good idea to do this regularly, and especially to do this immediately before fixing a bug in an NPL problem.
Reporting bug fixes
When you do fix a bug, be sure to say in the commit message "Fixed bug #XYZW". In fact, that is all you need to say. Then, find the bug again in Bugzilla, and add a comment on the bug to inform the assignee and anyone subscribed to that bug that you committed a fix. Be sure to indicate that the fix was committed in your branch and give the revision number. Once the fix is merged back into the trunk, the assignee will then close out the bug in Bugzilla.
