Difference between revisions of "Submitting problems to the OPL"
| Line 14: | Line 14: | ||
<li> create a fork of the OPL through github |
<li> create a fork of the OPL through github |
||
<li> add your problems |
<li> add your problems |
||
| − | <li> commit and push your changes back to github |
||
| + | <li> commit (if you have added files, <code>git commit -A</code> will add all new files which have appeared in your copy of the OPL) |
||
| + | <li> push your changes back to github |
||
<li> issue a pull request which is asking the OPL maintains to review your problems |
<li> issue a pull request which is asking the OPL maintains to review your problems |
||
</ol> |
</ol> |
||
| − | |||
| + | When adding problems, do not remove other parts of the OPL, even if you don't think they are relevant to you. If you do, removing the files becomes part of the pull request. |
||
| − | |||
| − | == First Steps == |
||
| − | Once your branch is created, it's time to start adding problems. Typically new contributors already have a collection of problems they've written and would like to contribute. Let us suppose that you have such a collection on your computer in a directory called webwork/ and in a subdirectory called problems_to_contribute/Chapter1/. Then the command |
||
| − | |||
| − | svn import webwork/problems_to_contribute/ <nowiki>http://svn.webwork.maa.org/npl/branches/my_branch/my_univ</nowiki> \ |
||
| − | -m "Submitting amazing new problems characterized by these properties:..." --username <username> --password <password> |
||
| − | |||
| − | will create a new subdirectory of your branch named <tt>Chapter1</tt> containing the problems in that directory. Note that if you svn import webwork/problems_to_contribute/Chapter1/ then the contents of Chapter1, but not the directory, will be imported into your repository. This may or may not be what you want, but you should be aware of this behavior so that your branch has the directory structure you intend it to have. |
||
| − | |||
| − | As with the command above, 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. Typically, you will use the command <tt>svn ci</tt> or it's longer version <tt>svn commit</tt> and this operation optionally takes a local path, but not a remote url. |
||
| − | |||
| − | Commands which do not result in writing to the repository do not require authentication. For example, to check out only your new directory do |
||
| − | svn co <nowiki>http://svn.webwork.maa.org/npl/branches/my_branch/my_univ</nowiki> |
||
| − | |||
| − | This will create a new directory <tt>my_univ</tt> in your current working directory. Note that, <tt>svn co</tt> is a short-cut for <tt>svn checkout</tt> juast as <tt>svn ci</tt> is a short cut for <tt>svn commit</tt>. |
||
| − | |||
| − | 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 <tt>subdir1</tt> under <tt>my_univ</tt>, you would use the command, executed from within the <tt>my_univ</tt> 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 [http://svnbook.red-bean.com the Subversion Book]. |
||
== Standards for problems contributed to the OPL == |
== Standards for problems contributed to the OPL == |
||
Revision as of 13:21, 6 October 2013
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 OPL, but also to maintain high standards for the problems contributed.
Note the National Problem Library, or NPL, was renamed the Open Problem Library, or OPL in 2012.
Contents
Who can contribute to the OPL?
Anybody can contribute to the OPL. 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 OPL 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 OPL. 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 OPL.
The mechanics of contributing to the OPL
The basic process is
- create a fork of the OPL through github
- add your problems
- commit (if you have added files,
git commit -Awill add all new files which have appeared in your copy of the OPL) - push your changes back to github
- issue a pull request which is asking the OPL maintains to review your problems
When adding problems, do not remove other parts of the OPL, even if you don't think they are relevant to you. If you do, removing the files becomes part of the pull request.
Standards for problems contributed to the OPL
This section focuses purely on the technical standards for problems contributed to the OPL. We also hope that the problems contributed to the OPL will adhere to very high pedagogical standards as well. However, problems contributed to the OPL are not evaluated from that point of view. We leave it to the instructors using WeBWorK to determine which OPL 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 OPL must be properly tagged.
Fixing bugs
If you plan to also use your git fork to contribute bug fixes for OPL problems, you can fix a bug and issue a pull request. If you are fixing a bug reported in Bugzilla, refer to the bug number in your pull request so the maintains can close the bug report.
Be careful of having multiple commits in a pull request. If you make a pull request, fix a bug somewhere else and try to issue another pull request before the first one gets merged, the two end up in one pull request. If the changes are connected, this makes sense. If they are unrelated, you will want to make the second set of changes in a branch. Pull requests from separate branches are automatically kept separate. This is most important if one of the pull requests is for the addition of problems since those take longer to check than bug fixes in problems.
Syncing your branch with the trunk
When using your branch to fix bugs in the OPL, 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
$ git pull upstream master
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 OPL 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.
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 OPL 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.
Using Git
The use of Github is currently being tested. Users on MacOS may want to consider downloading the free SourceTree app from the App store. SourceTree is free. With GitHub, you can push changes for WebWork to your repository there and make these changes available to others. Once uploaded to github, you can request that WebWork management pull your change into the source code.
- Go to http://github.com and set up an account. You can choose the free open source option.
- Follow the "Set up Git" instructions on the github site for setting up a ssh key. This is how you will authenticate when transferring files.
- On the github site, search for "webwork" and select openwebwork. Select the component you want to work on (webwork2, pg, libraries, etc.) and then click on "Fork"--an icon in the upper right portion of the page.
- When your fork has been created, you can choose to "Clone" a copy to your local computer using some git-compatible app (such as SourceTree).
- Make your modifications on your local computer
- When you are ready to submit your modifications "push" them to your private github.com repository
- From your github.com repository choose the "pull request" button and ask that your contribution be incorporated into the github.com/openwebwork repository for use by the WeBWorK community
