Difference between revisions of "Submitting problems to the OPL"

From WeBWorK_wiki
Jump to navigation Jump to search
 
(38 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
[[Category:Problem Libraries]] [[Category:National Problem Library]] [[Category:Authors]] [[Category:Subversion]]
 +
[[Category:Problem Libraries]] [[Category:Open_Problem_Library]] [[Category:Authors]] [[Category:Github]]
−
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.
 +
One of WeBWorK's most attractive features is the Open 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.
   
−
== Who can contribute to the NPL? ==
  
  +
Note the National Problem Library, or NPL, was renamed the Open Problem Library, or OPL in 2012.
−
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 [http://webwork.maa.org/viewvc/npl 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.
  
  +
== Who can contribute to the OPL? ==
  +
Anybody can contribute to the OPL. Typically, contributors are familiar with WeBWorK and have a reasonably good understanding of the PG language and the MathObjects framework.
   
−
== The mechanics of contributing to the NPL ==
  
  +
If you have already written a collection of WeBWorK problems and want to share them with other WeBWorK users, we will gladly include the collection to the problems distributed with the Open Problem Library. 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. Initially, problems are put in the Contrib portion of the OPL. Selected problems may then be copied to the part of the OPL which gets indexed by the Library Browser.
−
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 <tt>npl</tt> repository at <nowiki>http://svn.webwork.maa.org/npl</nowiki>. If your branch is called <tt>my_branch</tt>, then it will be located at
 
  +
== Overview of contributing to the OPL ==
−
<nowiki>http://svn.webwork.maa.org/npl/branches/my_branch</nowiki>
  
  +
There are two parts of the OPL confusingly named "OpenProblemLibrary" and "Contrib". When users install the OPL, they get both parts. The differences are
   
−
Initially, your ''commit access'' will be restricted to your branch of the <tt>npl</tt> 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).
  
  +
* problems in OpenProblemLibrary are tagged and indexed in a database on the webwork server so users can search for them with the Library Browser based on a three-tier taxonomy (Subject/Chapter/Section).
  +
* Contrib problems can be tagged, but they are not indexed. Individual sites can make them visible in the Library Browser where they are browsed by subdirectory.
  +
* problems in OpenProblemLibrary are maintained by a group of OPL editors. They may modify problems so that they conform to stylistic guidelines, or removed problems which are too similar to other OpenProblemLibrary problems.
  +
* Contrib problems are maintained by their original contributors. Problems in Contrib will not be changed or removed by editors.
  +
* OpenProblemLibrary editors review problems in Contrib, and copy selected problems into the OpenProblemLibrary.
  +
* Problems offered to Contrib are accepted as is.
   
−
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 <tt>npl</tt> repository and the branch will be deleted. You will then be given authorization to contribute your work to the trunk of the <tt>npl</tt> repository. If you later start to do development on the WeBWorK system code, you can then also be given commit access to the <tt>system</tt> repository.
  
  +
So, problems can be added to Contrib for two purposes. If a problem author wants to share their work with other WeBWorK instructors, they can have them added to Contrib, all WeBWorK sites will get the problems when they update their copies of the OPL, and the problems will always be exactly as the problem author wants them. Secondly, problems in Contrib can be considered for addition to the OpenProblemLibrary. If the problems are copied in the OpenProblemLibrary, they will be more visible to users, but they may be modified over time by the OPL editors.
   
−
== First Steps ==
  
  +
== The mechanics of contributing to the OPL and Contrib ==
−
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
  
  +
The basic process is
   
−
svn import webwork/problems_to_contribute/ <nowiki>http://svn.webwork.maa.org/npl/branches/my_branch/my_univ</nowiki> \
  
  +
* Create an account on GitHub. (There are good instructions: http://github.com )
−
-m "Submitting amazing new problems characterized by these properties:..." --username <username> --password <password>
  
  +
* create a fork (copy) of the OPL through GitHub. The common OPL resides at http://github.com/openwebwork/webwork-open-problem-library Your copy will reside at <code>http://github.com/yourHandleHere/webwork-open-problem-library</code>.
  +
* clone a copy of the OPL on your desktop or laptop.
  +
git clone http://github.com/yourHandleHere/webwork-open-problem-library.git
  +
cd webwork-open-problem-library
  +
git remote add upstream http://github.com/openwebwork/webwork-open-problem-library.git
  +
* add and edit your problems to the Contrib subdirectory of <code>webwork-open-problem-library</code>
  +
* do '''not''' delete other problems in the repository (even if they are not needed for your site)
  +
* commit (if you have added files, <code>git commit -a -m 'Descriptive message here'</code> will add all new files which have appeared in your copy of the OPL)
  +
* push your changes back to YOUR GitHub copy <code> git push https://github.com/yourHandleHere/webwork-open-problem-library</code>
  +
* issue a pull request to github.com/openwebwork/ which asks the OPL maintainers to review your problems
  +
*:You do this from the web by visiting <code>https://github.com/yourHandleHere/webwork-open-problem-library</code> and looking for the pull request icon.
   
−
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.
  
  +
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.
   
−
Commands which do not result in writing to the repository do not require authentication. For example, to check out only your new directory do
  
  +
This procedure sounds more complicated than it is in practice. Once you have set up the accounts new problems can
−
svn co <nowiki>http://svn.webwork.maa.org/npl/branches/my_branch/my_univ</nowiki>
 
  +
be added to your local file, uploaded to your github and submitted for consideration by the openwebwork OPL maintainers with just a few commands.
   
−
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>.
 
  +
== Identifying your contributions ==
  +
The way github works you appear to be cloning and resubmitting the entire library although behind the scenes software is transmitting only your changes. This ensures that if you change both a macro file and a problem then they will both be uploaded and everything will stay in sync. It is also the reason why you should not delete other portions of the OPL which you are not touching. If you have changed other parts of the OPL your pull request will not be accepted.
   
−
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,
  
  +
For most contributors your best practice is to create a directory under Contrib (Contrib/myNewProblems) in your downloaded clone and add your problems there. "myNewProblems" is often the name of your institution but it could be your own name or handle if you prefer that. Inside Contrib/myNewProblems, please add a text file named README stating who is contributing the problems, and which github usernames are allowed to modify problems in Contrib/myNewProblems. This file should also contain any special information (if any) which sites should know when using these problems.
−
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 NPL ==
  
  +
Problems submitted in the Contributor's directory are accepted quickly and not extensively checked for tagging, duplication and other editorial requirements. It is a good way to get your questions quickly viewed by the general public. Those curating the Open Problem Library will often select and possibly modify items in the Contrib directory for inclusion elsewhere in the OPL hierarchy. Editing and curating is not a quick process however so placing your contributions in the Contrib directory will get them "published" faster. They will also remain exactly as you uploaded them, while the copies moved into the other directories of the OPL may be modified to conform to editorial practices.
   
−
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.
  
  +
You can see the current organization of the Contrib directory here: https://github.com/openwebwork/webwork-open-problem-library/tree/master/Contrib
   
−
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.
  
  +
== Indicating that you want your problems to be considered for the OPL ==
  +
  +
All new problems are submitted to the Contrib directory. If the person submitting problems wants their contribution to be considered for the OPL,
  +
* say that you want the problems considered for the OPL in your pull request
  +
* be sure that your problems are tagged. An editor will need to review the problems, and this helps us match problems with editors.
  +
* if a problem is similar to other problems in the OPL, add a MLT tag so the problem will be associated to a more-like-this group (to match the MLT tag in the similar problems)
  +
* give a brief explanation as to why these problems provide something not already present in the OPL
  +
  +
Note, improvements of existing OPL problems should be submitted by changing the current problem and making a pull request through github, rather than by creating a new problem.
  +
  +
== Submitting 'similar' or 'modifications' to existing OPL problems ==
  +
  +
If <code>Library/original/problem.pg</code> is the original problem and <code>Contrib/modify/problem.pg</code> is your revised problem:
  +
# Check <code>Library/original/problem.pg</code> for an <code>## MLT(<<name>>)</code> tag -- ''if'' one exists.
  +
# Copy-paste the MLT tag line from <code>Library/original/problem.pg</code> into <code>Contrib/modify/problem.pg</code> and skip the remaining steps.
  +
# If no MLT tag exists, add an <code>## MLT(<<new_unique_name>>)</code> tag line to both <code>Library/original/problem.pg</code> and <code>Contrib/modify/problem.pg</code> (the chosen <code>new_unique_name</code> must be different from all other existing MLT names to ensure that a new MLT group is formed)
  +
# Add the line <code>## MLTleader(1)</code> to <code>Library/original/problem.pg</code> '''only'''.
  +
  +
If you have command-line access, the following command can help confirm whether or not you have a unique MLT name:
  +
  +
<code>grep -r 'MLT(possibly_unique_name)' /opt/webwork/libraries/webwork-open-problem-library</code>
  +
  +
For example, if you perform the above action for <code>MLT(WorkProblem)</code>, you should see that there are already problems in the OPL using this MLT name, so using 'WorkProblem' would ''not'' create a new MLT group. On the other hand, if you get '''no''' results from the grep command, then your chosen MLT name '''is''' unique.
  +
  +
''note:'' MLT group names should not include any spaces; rather you should use underscores, hyphens, or CamelCase to deal with multiple words.
  +
  +
== 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, and in hardcopy. 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 [[:Category:Authors|authoring documentation]] in this wiki has extensive information about this, including a very helpful [[:Category:Problem Techniques|index of problem techniques]] which illustrate best practices.
  
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 [[:Category:Authors|authoring documentation]] in this wiki has extensive information about this, including a very helpful [[:Category:Problem Techniques|index of problem techniques]] which illustrate best practices.
   
−
Thirdly, problem collections submitted to the NPL must be [[Tagging Problems|properly tagged]].
 +
Thirdly, problem collections submitted to the OPL must be [[Tagging Problems|properly tagged]].
   
 
== Fixing bugs ==
  
== 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 [http://bugs.webwork.maa.org/buglist.cgi?quicksearch=%3AProblem+Libraries 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.
 
  +
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 ===
  
=== 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:
 +
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
  
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
Line 58: Line 102:
   
 
and run
  
and run
−
$ svn merge <nowiki>http://svn.webwork.maa.org/npl/trunk</nowiki>
  
  +
$ 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 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.
 +
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.
  
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."
 +
git 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.
 +
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 ===
  
=== Reporting bug fixes ===
Line 71: Line 115:
   
 
== Using Git ==
  
== 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.
 +
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.
 
*Go to http://github.com and set up an account. You can choose the free open source option.
−
*Once you have set up an account, 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.
+
*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.
 +
*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).
  
*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
   
 
== See also ==
  
== See also ==
−
* [[Subversion]]
  
−
* [[SVN Commit Access]]
  
 
* [[:Category:Authors]]
  
* [[:Category:Authors]]
 
* [[Bugzilla]]
  
* [[Bugzilla]]
−  
  +
* [[Category:Open_Problem_Library]]
−
== External Links ==
  
−
* [http://svnbook.red-bean.com/ The Subversion Book]
  

Latest revision as of 11:14, 20 August 2021

One of WeBWorK's most attractive features is the Open 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.

Who can contribute to the OPL?

Anybody can contribute to the OPL. Typically, contributors are familiar with WeBWorK and have a reasonably good understanding of the PG language and the MathObjects framework.

If you have already written a collection of WeBWorK problems and want to share them with other WeBWorK users, we will gladly include the collection to the problems distributed with the Open Problem Library. 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. Initially, problems are put in the Contrib portion of the OPL. Selected problems may then be copied to the part of the OPL which gets indexed by the Library Browser.

Overview of contributing to the OPL

There are two parts of the OPL confusingly named "OpenProblemLibrary" and "Contrib". When users install the OPL, they get both parts. The differences are

  • problems in OpenProblemLibrary are tagged and indexed in a database on the webwork server so users can search for them with the Library Browser based on a three-tier taxonomy (Subject/Chapter/Section).
  • Contrib problems can be tagged, but they are not indexed. Individual sites can make them visible in the Library Browser where they are browsed by subdirectory.
  • problems in OpenProblemLibrary are maintained by a group of OPL editors. They may modify problems so that they conform to stylistic guidelines, or removed problems which are too similar to other OpenProblemLibrary problems.
  • Contrib problems are maintained by their original contributors. Problems in Contrib will not be changed or removed by editors.
  • OpenProblemLibrary editors review problems in Contrib, and copy selected problems into the OpenProblemLibrary.
  • Problems offered to Contrib are accepted as is.

So, problems can be added to Contrib for two purposes. If a problem author wants to share their work with other WeBWorK instructors, they can have them added to Contrib, all WeBWorK sites will get the problems when they update their copies of the OPL, and the problems will always be exactly as the problem author wants them. Secondly, problems in Contrib can be considered for addition to the OpenProblemLibrary. If the problems are copied in the OpenProblemLibrary, they will be more visible to users, but they may be modified over time by the OPL editors.

The mechanics of contributing to the OPL and Contrib

The basic process is 

   git clone http://github.com/yourHandleHere/webwork-open-problem-library.git
   cd webwork-open-problem-library
   git remote add upstream http://github.com/openwebwork/webwork-open-problem-library.git
  • add and edit your problems to the Contrib subdirectory of webwork-open-problem-library
  • do not delete other problems in the repository (even if they are not needed for your site)
  • commit (if you have added files, git commit -a -m 'Descriptive message here' will add all new files which have appeared in your copy of the OPL)
  • push your changes back to YOUR GitHub copy git push https://github.com/yourHandleHere/webwork-open-problem-library
  • issue a pull request to github.com/openwebwork/ which asks the OPL maintainers to review your problems
    You do this from the web by visiting https://github.com/yourHandleHere/webwork-open-problem-library and looking for the pull request icon.


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.

This procedure sounds more complicated than it is in practice. Once you have set up the accounts new problems can be added to your local file, uploaded to your github and submitted for consideration by the openwebwork OPL maintainers with just a few commands.

Identifying your contributions

The way github works you appear to be cloning and resubmitting the entire library although behind the scenes software is transmitting only your changes. This ensures that if you change both a macro file and a problem then they will both be uploaded and everything will stay in sync. It is also the reason why you should not delete other portions of the OPL which you are not touching. If you have changed other parts of the OPL your pull request will not be accepted.

For most contributors your best practice is to create a directory under Contrib (Contrib/myNewProblems) in your downloaded clone and add your problems there. "myNewProblems" is often the name of your institution but it could be your own name or handle if you prefer that. Inside Contrib/myNewProblems, please add a text file named README stating who is contributing the problems, and which github usernames are allowed to modify problems in Contrib/myNewProblems. This file should also contain any special information (if any) which sites should know when using these problems.

Problems submitted in the Contributor's directory are accepted quickly and not extensively checked for tagging, duplication and other editorial requirements. It is a good way to get your questions quickly viewed by the general public. Those curating the Open Problem Library will often select and possibly modify items in the Contrib directory for inclusion elsewhere in the OPL hierarchy. Editing and curating is not a quick process however so placing your contributions in the Contrib directory will get them "published" faster. They will also remain exactly as you uploaded them, while the copies moved into the other directories of the OPL may be modified to conform to editorial practices.

You can see the current organization of the Contrib directory here: https://github.com/openwebwork/webwork-open-problem-library/tree/master/Contrib

Indicating that you want your problems to be considered for the OPL

All new problems are submitted to the Contrib directory. If the person submitting problems wants their contribution to be considered for the OPL,

  • say that you want the problems considered for the OPL in your pull request
  • be sure that your problems are tagged. An editor will need to review the problems, and this helps us match problems with editors.
  • if a problem is similar to other problems in the OPL, add a MLT tag so the problem will be associated to a more-like-this group (to match the MLT tag in the similar problems)
  • give a brief explanation as to why these problems provide something not already present in the OPL

Note, improvements of existing OPL problems should be submitted by changing the current problem and making a pull request through github, rather than by creating a new problem.

Submitting 'similar' or 'modifications' to existing OPL problems

If Library/original/problem.pg is the original problem and Contrib/modify/problem.pg is your revised problem:

  1. Check Library/original/problem.pg for an ## MLT(<<name>>) tag -- if one exists.
  2. Copy-paste the MLT tag line from Library/original/problem.pg into Contrib/modify/problem.pg and skip the remaining steps.
  3. If no MLT tag exists, add an ## MLT(<<new_unique_name>>) tag line to both Library/original/problem.pg and Contrib/modify/problem.pg (the chosen new_unique_name must be different from all other existing MLT names to ensure that a new MLT group is formed)
  4. Add the line ## MLTleader(1) to Library/original/problem.pg only.

If you have command-line access, the following command can help confirm whether or not you have a unique MLT name:

grep -r 'MLT(possibly_unique_name)' /opt/webwork/libraries/webwork-open-problem-library

For example, if you perform the above action for MLT(WorkProblem), you should see that there are already problems in the OPL using this MLT name, so using 'WorkProblem' would not create a new MLT group. On the other hand, if you get no results from the grep command, then your chosen MLT name is unique.

note: MLT group names should not include any spaces; rather you should use underscores, hyphens, or CamelCase to deal with multiple words.

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, and in hardcopy. 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. 

git 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

See also

Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=Submitting_problems_to_the_OPL&oldid=22433"