paul@17 | 1 | Introduction
|
paul@17 | 2 | ------------
|
paul@17 | 3 |
|
paul@17 | 4 | The ApproveChanges action for MoinMoin, along with the queue_for_review event
|
paul@17 | 5 | handler and supporting library, provides a way for contributions to a Wiki
|
paul@17 | 6 | made by anonymous or untrusted users to be queued for review and approval by
|
paul@17 | 7 | trusted reviewers.
|
paul@17 | 8 |
|
paul@17 | 9 | After installation, some Wiki configuration is required to make sure that the
|
paul@17 | 10 | queuing and approval mechanisms function correctly. See "Configuration" below
|
paul@17 | 11 | for more information.
|
paul@17 | 12 |
|
paul@17 | 13 | Pre-Installation Tasks
|
paul@17 | 14 | ----------------------
|
paul@17 | 15 |
|
paul@17 | 16 | Before installing the software, create a new user who will be responsible for
|
paul@17 | 17 | queuing untrusted changes. This user will be used by the software internally,
|
paul@17 | 18 | and it should never be necessary to log in manually as this user to perform
|
paul@17 | 19 | tasks.
|
paul@17 | 20 |
|
paul@17 | 21 | Adding a new user can be done using the moin program as follows:
|
paul@17 | 22 |
|
paul@17 | 23 | moin --config-dir=path-to-wikiconfig account create \
|
paul@17 | 24 | --name=ApprovalQueueUser --email=... --password=...
|
paul@17 | 25 |
|
paul@17 | 26 | The ... values should be substituted with acceptable values. Beware that
|
paul@17 | 27 | MoinMoin insists on distinct e-mail addresses. Beware also that providing a
|
paul@17 | 28 | password on the command line can be a risk on multi-user systems.
|
paul@17 | 29 |
|
paul@17 | 30 | Installation
|
paul@17 | 31 | ------------
|
paul@17 | 32 |
|
paul@17 | 33 | To install the software, consider using the moinsetup tool. See the
|
paul@17 | 34 | "Recommended Software" section below for more information.
|
paul@17 | 35 |
|
paul@17 | 36 | With moinsetup and a suitable configuration file, the installation is done as
|
paul@17 | 37 | follows with $ACDIR referring to the ApproveChanges distribution directory
|
paul@17 | 38 | containing this README.txt file:
|
paul@17 | 39 |
|
paul@17 | 40 | python moinsetup.py -f moinsetup.cfg -m install_extension_package $ACDIR
|
paul@17 | 41 | python moinsetup.py -f moinsetup.cfg -m install_actions $ACDIR/actions
|
paul@17 | 42 | python moinsetup.py -f moinsetup.cfg -m install_event_handlers $ACDIR/events
|
paul@17 | 43 |
|
paul@17 | 44 | The first command above uses the setup.py script provided as follows:
|
paul@17 | 45 |
|
paul@17 | 46 | python setup.py install --prefix=path-to-moin-prefix
|
paul@17 | 47 |
|
paul@17 | 48 | The second and third commands install the action and event handler
|
paul@17 | 49 | respectively.
|
paul@17 | 50 |
|
paul@17 | 51 | Useful Pages
|
paul@17 | 52 | ------------
|
paul@17 | 53 |
|
paul@17 | 54 | The pages directory contains a selection of useful pages using a syntax
|
paul@17 | 55 | appropriate for use with MoinMoin 1.6 or later. These pages can be created
|
paul@17 | 56 | through the Wiki and their contents copied in from each of the files. An
|
paul@17 | 57 | easier installation method is to issue the following commands:
|
paul@17 | 58 |
|
paul@17 | 59 | python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/pages pages.zip
|
paul@17 | 60 | python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
|
paul@17 | 61 |
|
paul@17 | 62 | You may need to switch user in order to have sufficient privileges to copy the
|
paul@17 | 63 | page package into the Wiki. For example:
|
paul@17 | 64 |
|
paul@17 | 65 | sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
|
paul@17 | 66 |
|
paul@17 | 67 | Resource Pages
|
paul@17 | 68 | --------------
|
paul@17 | 69 |
|
paul@17 | 70 | In order to assign Wiki users to particular roles, some resource pages must be
|
paul@17 | 71 | set up in a Wiki. For this purpose, the resource_pages directory contains
|
paul@17 | 72 | example pages defining the membership of two groups:
|
paul@17 | 73 |
|
paul@17 | 74 | ApprovedGroup: the approved users group; users whose changes do not
|
paul@17 | 75 | need to approved and who can edit the Wiki normally
|
paul@17 | 76 |
|
paul@17 | 77 | PageReviewersGroup the reviews group; users who can review the changes
|
paul@17 | 78 | made by untrusted users
|
paul@17 | 79 |
|
paul@17 | 80 | Once installed, these group pages should be populated with real user
|
paul@17 | 81 | identities or other group names. See the following page for more information:
|
paul@17 | 82 |
|
paul@17 | 83 | http://moinmo.in/HelpOnGroups
|
paul@17 | 84 |
|
paul@17 | 85 | Without any usernames in the group pages, all users who are not nominated as
|
paul@17 | 86 | superusers will have their edits intercepted by the change queuing mechanism,
|
paul@17 | 87 | and only superusers will be able to review changes.
|
paul@17 | 88 |
|
paul@17 | 89 | To install the resource pages, use the following commands:
|
paul@17 | 90 |
|
paul@17 | 91 | python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/resource_pages resource_pages.zip
|
paul@17 | 92 | python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
|
paul@17 | 93 |
|
paul@17 | 94 | You may need to switch user in order to have sufficient privileges to copy the
|
paul@17 | 95 | page package into the Wiki. For example:
|
paul@17 | 96 |
|
paul@17 | 97 | sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
|
paul@17 | 98 |
|
paul@17 | 99 | Configuration
|
paul@17 | 100 | -------------
|
paul@17 | 101 |
|
paul@17 | 102 | Once the event handler has been installed, all page saving operations will be
|
paul@17 | 103 | affected by its operation. With no further configuration, it is most likely
|
paul@17 | 104 | that only superusers will be able to save changes to Wiki pages, and even the
|
paul@17 | 105 | queuing of changes will not function properly.
|
paul@17 | 106 |
|
paul@17 | 107 | Thus, it becomes necessary to change the Wiki configuration to enable the
|
paul@17 | 108 | successful queuing of changes by changing the acl_rights_before configuration
|
paul@17 | 109 | setting, adding the following rule:
|
paul@17 | 110 |
|
paul@17 | 111 | ApprovalQueueUser:write,admin
|
paul@17 | 112 |
|
paul@17 | 113 | This will let the special internal Wiki user responsible for queuing changes
|
paul@17 | 114 | (see "Pre-Installation Tasks") save and define an ACL on a page saved by an
|
paul@17 | 115 | untrusted user. See the following page for more information on access control
|
paul@17 | 116 | lists (ACLs):
|
paul@17 | 117 |
|
paul@17 | 118 | http://moinmo.in/HelpOnAccessControlLists
|
paul@17 | 119 |
|
paul@17 | 120 | Recommended Software
|
paul@17 | 121 | --------------------
|
paul@17 | 122 |
|
paul@17 | 123 | See the "Dependencies" section below for essential software.
|
paul@17 | 124 |
|
paul@17 | 125 | The moinsetup tool is recommended for installation since it aims to support
|
paul@17 | 126 | all versions of MoinMoin that are supported for use with this software.
|
paul@17 | 127 |
|
paul@17 | 128 | See the following page for information on moinsetup:
|
paul@17 | 129 |
|
paul@17 | 130 | http://moinmo.in/ScriptMarket/moinsetup
|
paul@17 | 131 |
|
paul@17 | 132 | Contact, Copyright and Licence Information
|
paul@17 | 133 | ------------------------------------------
|
paul@17 | 134 |
|
paul@17 | 135 | See the following Web page for more information about this work:
|
paul@17 | 136 |
|
paul@17 | 137 | http://moinmo.in/ActionMarket/ApproveChanges
|
paul@17 | 138 |
|
paul@17 | 139 | The author can be contacted at the following e-mail address:
|
paul@17 | 140 |
|
paul@17 | 141 | paul@boddie.org.uk
|
paul@17 | 142 |
|
paul@17 | 143 | Copyright and licence information can be found in the docs directory - see
|
paul@17 | 144 | docs/COPYING.txt and docs/LICENCE.txt for more information.
|
paul@17 | 145 |
|
paul@17 | 146 | Release Procedures
|
paul@17 | 147 | ------------------
|
paul@17 | 148 |
|
paul@17 | 149 | Update the ApproveChanges.py __version__ attribute and the setup.py version
|
paul@17 | 150 | details.
|
paul@17 | 151 | Change the version number and package filename/directory in the documentation.
|
paul@17 | 152 | Update the setup.py and PKG-INFO files.
|
paul@17 | 153 | Update the release notes (see above).
|
paul@17 | 154 | Tag, export.
|
paul@17 | 155 | Archive, upload.
|
paul@17 | 156 | Update the ActionMarket (see above for the URL).
|