1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README.txt Sat Oct 15 19:20:52 2011 +0200
1.3 @@ -0,0 +1,156 @@
1.4 +Introduction
1.5 +------------
1.6 +
1.7 +The ApproveChanges action for MoinMoin, along with the queue_for_review event
1.8 +handler and supporting library, provides a way for contributions to a Wiki
1.9 +made by anonymous or untrusted users to be queued for review and approval by
1.10 +trusted reviewers.
1.11 +
1.12 +After installation, some Wiki configuration is required to make sure that the
1.13 +queuing and approval mechanisms function correctly. See "Configuration" below
1.14 +for more information.
1.15 +
1.16 +Pre-Installation Tasks
1.17 +----------------------
1.18 +
1.19 +Before installing the software, create a new user who will be responsible for
1.20 +queuing untrusted changes. This user will be used by the software internally,
1.21 +and it should never be necessary to log in manually as this user to perform
1.22 +tasks.
1.23 +
1.24 +Adding a new user can be done using the moin program as follows:
1.25 +
1.26 + moin --config-dir=path-to-wikiconfig account create \
1.27 + --name=ApprovalQueueUser --email=... --password=...
1.28 +
1.29 +The ... values should be substituted with acceptable values. Beware that
1.30 +MoinMoin insists on distinct e-mail addresses. Beware also that providing a
1.31 +password on the command line can be a risk on multi-user systems.
1.32 +
1.33 +Installation
1.34 +------------
1.35 +
1.36 +To install the software, consider using the moinsetup tool. See the
1.37 +"Recommended Software" section below for more information.
1.38 +
1.39 +With moinsetup and a suitable configuration file, the installation is done as
1.40 +follows with $ACDIR referring to the ApproveChanges distribution directory
1.41 +containing this README.txt file:
1.42 +
1.43 + python moinsetup.py -f moinsetup.cfg -m install_extension_package $ACDIR
1.44 + python moinsetup.py -f moinsetup.cfg -m install_actions $ACDIR/actions
1.45 + python moinsetup.py -f moinsetup.cfg -m install_event_handlers $ACDIR/events
1.46 +
1.47 +The first command above uses the setup.py script provided as follows:
1.48 +
1.49 + python setup.py install --prefix=path-to-moin-prefix
1.50 +
1.51 +The second and third commands install the action and event handler
1.52 +respectively.
1.53 +
1.54 +Useful Pages
1.55 +------------
1.56 +
1.57 +The pages directory contains a selection of useful pages using a syntax
1.58 +appropriate for use with MoinMoin 1.6 or later. These pages can be created
1.59 +through the Wiki and their contents copied in from each of the files. An
1.60 +easier installation method is to issue the following commands:
1.61 +
1.62 + python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/pages pages.zip
1.63 + python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
1.64 +
1.65 +You may need to switch user in order to have sufficient privileges to copy the
1.66 +page package into the Wiki. For example:
1.67 +
1.68 + sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
1.69 +
1.70 +Resource Pages
1.71 +--------------
1.72 +
1.73 +In order to assign Wiki users to particular roles, some resource pages must be
1.74 +set up in a Wiki. For this purpose, the resource_pages directory contains
1.75 +example pages defining the membership of two groups:
1.76 +
1.77 + ApprovedGroup: the approved users group; users whose changes do not
1.78 + need to approved and who can edit the Wiki normally
1.79 +
1.80 + PageReviewersGroup the reviews group; users who can review the changes
1.81 + made by untrusted users
1.82 +
1.83 +Once installed, these group pages should be populated with real user
1.84 +identities or other group names. See the following page for more information:
1.85 +
1.86 + http://moinmo.in/HelpOnGroups
1.87 +
1.88 +Without any usernames in the group pages, all users who are not nominated as
1.89 +superusers will have their edits intercepted by the change queuing mechanism,
1.90 +and only superusers will be able to review changes.
1.91 +
1.92 +To install the resource pages, use the following commands:
1.93 +
1.94 + python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/resource_pages resource_pages.zip
1.95 + python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
1.96 +
1.97 +You may need to switch user in order to have sufficient privileges to copy the
1.98 +page package into the Wiki. For example:
1.99 +
1.100 + sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
1.101 +
1.102 +Configuration
1.103 +-------------
1.104 +
1.105 +Once the event handler has been installed, all page saving operations will be
1.106 +affected by its operation. With no further configuration, it is most likely
1.107 +that only superusers will be able to save changes to Wiki pages, and even the
1.108 +queuing of changes will not function properly.
1.109 +
1.110 +Thus, it becomes necessary to change the Wiki configuration to enable the
1.111 +successful queuing of changes by changing the acl_rights_before configuration
1.112 +setting, adding the following rule:
1.113 +
1.114 + ApprovalQueueUser:write,admin
1.115 +
1.116 +This will let the special internal Wiki user responsible for queuing changes
1.117 +(see "Pre-Installation Tasks") save and define an ACL on a page saved by an
1.118 +untrusted user. See the following page for more information on access control
1.119 +lists (ACLs):
1.120 +
1.121 + http://moinmo.in/HelpOnAccessControlLists
1.122 +
1.123 +Recommended Software
1.124 +--------------------
1.125 +
1.126 +See the "Dependencies" section below for essential software.
1.127 +
1.128 +The moinsetup tool is recommended for installation since it aims to support
1.129 +all versions of MoinMoin that are supported for use with this software.
1.130 +
1.131 +See the following page for information on moinsetup:
1.132 +
1.133 +http://moinmo.in/ScriptMarket/moinsetup
1.134 +
1.135 +Contact, Copyright and Licence Information
1.136 +------------------------------------------
1.137 +
1.138 +See the following Web page for more information about this work:
1.139 +
1.140 +http://moinmo.in/ActionMarket/ApproveChanges
1.141 +
1.142 +The author can be contacted at the following e-mail address:
1.143 +
1.144 +paul@boddie.org.uk
1.145 +
1.146 +Copyright and licence information can be found in the docs directory - see
1.147 +docs/COPYING.txt and docs/LICENCE.txt for more information.
1.148 +
1.149 +Release Procedures
1.150 +------------------
1.151 +
1.152 +Update the ApproveChanges.py __version__ attribute and the setup.py version
1.153 +details.
1.154 +Change the version number and package filename/directory in the documentation.
1.155 +Update the setup.py and PKG-INFO files.
1.156 +Update the release notes (see above).
1.157 +Tag, export.
1.158 +Archive, upload.
1.159 +Update the ActionMarket (see above for the URL).