Introduction
------------

The ApproveChanges action for MoinMoin, along with the queue_for_review event
handler and supporting library, provides a way for contributions to a Wiki
made by anonymous or untrusted users to be queued for review and approval by
trusted reviewers.

After installation, some Wiki configuration is required to make sure that the
queuing and approval mechanisms function correctly. See the "Configuration"
section below for more information.

See pages/HelpOnApproveChanges for the documentation for this software and how
to use it.

Pre-Installation Tasks
----------------------

Before installing the software, create a new user who will be responsible for
queuing untrusted changes. This user will be used by the software internally,
and it should never be necessary to log in manually as this user to perform
tasks.

Adding a new user can be done using the moin program as follows:

  moin --config-dir=path-to-wikiconfig account create \
       --name=ApprovalQueueUser --email=... --password=...

The ... values should be substituted with acceptable values. Beware that
MoinMoin insists on distinct e-mail addresses. Beware also that providing a
password on the command line can be a risk on multi-user systems.

Installation
------------

To install the software, consider using the moinsetup tool. See the
"Recommended Software" section below for more information.

With moinsetup and a suitable configuration file, the installation is done as
follows with $ACDIR referring to the ApproveChanges distribution directory
containing this README.txt file:

  python moinsetup.py -f moinsetup.cfg -m install_extension_package $ACDIR
  python moinsetup.py -f moinsetup.cfg -m install_actions $ACDIR/actions
  python moinsetup.py -f moinsetup.cfg -m install_event_handlers $ACDIR/events

The first command above uses the setup.py script provided as follows:

  python setup.py install --prefix=path-to-moin-prefix

The second and third commands install the action and event handler
respectively.

Useful Pages
------------

The pages directory contains a selection of useful pages using a syntax
appropriate for use with MoinMoin 1.6 or later. These pages can be created
through the Wiki and their contents copied in from each of the files. An
easier installation method is to issue the following commands:

  python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/pages pages.zip
  python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip

You may need to switch user in order to have sufficient privileges to copy the
page package into the Wiki. For example:

  sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip

Resource Pages
--------------

In order to assign Wiki users to particular roles, some resource pages must be
set up in a Wiki. For this purpose, the resource_pages directory contains
example pages defining the membership of two groups:

  ApprovedGroup:        the approved users group; users whose changes do not
                        need to approved and who can edit the Wiki normally

  PageReviewersGroup    the reviews group; users who can review the changes
                        made by untrusted users

Once installed, these group pages should be populated with real user
identities or other group names. See the following page for more information:

  http://moinmo.in/HelpOnGroups

Without any usernames in the group pages, all users who are not nominated as
superusers will have their edits intercepted by the change queuing mechanism,
and only superusers will be able to review changes.

To install the resource pages, use the following commands:

  python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/resource_pages resource_pages.zip
  python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip

You may need to switch user in order to have sufficient privileges to copy the
page package into the Wiki. For example:

  sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip

Configuration
-------------

Once the event handler has been installed, all page saving operations will be
affected by its operation. With no further configuration, it is most likely
that only superusers will be able to save changes to Wiki pages, and even the
queuing of changes will not function properly.

Thus, it becomes necessary to change the Wiki configuration to enable the
successful queuing of changes by changing the acl_rights_before configuration
setting, adding the following rule:

  ApprovalQueueUser:write,admin

This will let the special internal Wiki user responsible for queuing changes
(see "Pre-Installation Tasks") save and define an ACL on a page saved by an
untrusted user. See the following page for more information on access control
lists (ACLs):

  http://moinmo.in/HelpOnAccessControlLists

Recommended Software
--------------------

See the "Dependencies" section below for essential software.

The moinsetup tool is recommended for installation since it aims to support
all versions of MoinMoin that are supported for use with this software.

See the following page for information on moinsetup:

http://moinmo.in/ScriptMarket/moinsetup

Contact, Copyright and Licence Information
------------------------------------------

See the following Web page for more information about this work:

http://moinmo.in/ActionMarket/ApproveChanges

The author can be contacted at the following e-mail address:

paul@boddie.org.uk

Copyright and licence information can be found in the docs directory - see
docs/COPYING.txt and docs/LICENCE.txt for more information.

Release Procedures
------------------

Update the ApproveChangesSupport.py __version__ attribute and the setup.py
version details.
Change the version number and package filename/directory in the documentation.
Update the setup.py and PKG-INFO files.
Update the release notes (see above).
Tag, export.
Archive, upload.
Update the ActionMarket (see above for the URL).
