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@27 | 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@27 | 9 | Before installation, a special user has to be added to the wiki for the
|
paul@27 | 10 | software to function. See the "Pre-Installation Tasks" for details.
|
paul@27 | 11 |
|
paul@27 | 12 | After installation, some wiki configuration is required to make sure that the
|
paul@23 | 13 | queuing and approval mechanisms function correctly. See the "Configuration"
|
paul@23 | 14 | section below for more information.
|
paul@17 | 15 |
|
paul@19 | 16 | See pages/HelpOnApproveChanges for the documentation for this software and how
|
paul@19 | 17 | to use it.
|
paul@19 | 18 |
|
paul@17 | 19 | Pre-Installation Tasks
|
paul@17 | 20 | ----------------------
|
paul@17 | 21 |
|
paul@17 | 22 | Before installing the software, create a new user who will be responsible for
|
paul@17 | 23 | queuing untrusted changes. This user will be used by the software internally,
|
paul@17 | 24 | and it should never be necessary to log in manually as this user to perform
|
paul@17 | 25 | tasks.
|
paul@17 | 26 |
|
paul@17 | 27 | Adding a new user can be done using the moin program as follows:
|
paul@17 | 28 |
|
paul@17 | 29 | moin --config-dir=path-to-wikiconfig account create \
|
paul@17 | 30 | --name=ApprovalQueueUser --email=... --password=...
|
paul@17 | 31 |
|
paul@17 | 32 | The ... values should be substituted with acceptable values. Beware that
|
paul@17 | 33 | MoinMoin insists on distinct e-mail addresses. Beware also that providing a
|
paul@17 | 34 | password on the command line can be a risk on multi-user systems.
|
paul@17 | 35 |
|
paul@17 | 36 | Installation
|
paul@17 | 37 | ------------
|
paul@17 | 38 |
|
paul@17 | 39 | To install the software, consider using the moinsetup tool. See the
|
paul@17 | 40 | "Recommended Software" section below for more information.
|
paul@17 | 41 |
|
paul@17 | 42 | With moinsetup and a suitable configuration file, the installation is done as
|
paul@17 | 43 | follows with $ACDIR referring to the ApproveChanges distribution directory
|
paul@17 | 44 | containing this README.txt file:
|
paul@17 | 45 |
|
paul@17 | 46 | python moinsetup.py -f moinsetup.cfg -m install_extension_package $ACDIR
|
paul@17 | 47 | python moinsetup.py -f moinsetup.cfg -m install_actions $ACDIR/actions
|
paul@17 | 48 | python moinsetup.py -f moinsetup.cfg -m install_event_handlers $ACDIR/events
|
paul@17 | 49 |
|
paul@17 | 50 | The first command above uses the setup.py script provided as follows:
|
paul@17 | 51 |
|
paul@17 | 52 | python setup.py install --prefix=path-to-moin-prefix
|
paul@17 | 53 |
|
paul@17 | 54 | The second and third commands install the action and event handler
|
paul@17 | 55 | respectively.
|
paul@17 | 56 |
|
paul@17 | 57 | Useful Pages
|
paul@17 | 58 | ------------
|
paul@17 | 59 |
|
paul@17 | 60 | The pages directory contains a selection of useful pages using a syntax
|
paul@17 | 61 | appropriate for use with MoinMoin 1.6 or later. These pages can be created
|
paul@27 | 62 | through the wiki and their contents copied in from each of the files. An
|
paul@17 | 63 | easier installation method is to issue the following commands:
|
paul@17 | 64 |
|
paul@17 | 65 | python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/pages pages.zip
|
paul@17 | 66 | python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
|
paul@17 | 67 |
|
paul@17 | 68 | You may need to switch user in order to have sufficient privileges to copy the
|
paul@27 | 69 | page package into the wiki. For example:
|
paul@17 | 70 |
|
paul@17 | 71 | sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
|
paul@17 | 72 |
|
paul@17 | 73 | Resource Pages
|
paul@17 | 74 | --------------
|
paul@17 | 75 |
|
paul@27 | 76 | In order to assign wiki users to particular roles, some resource pages must be
|
paul@27 | 77 | set up in a wiki. For this purpose, the resource_pages directory contains
|
paul@17 | 78 | example pages defining the membership of two groups:
|
paul@17 | 79 |
|
paul@29 | 80 | ApprovedGroup the approved users group; users whose changes do not
|
paul@27 | 81 | need to approved and who can edit the wiki normally
|
paul@17 | 82 |
|
paul@17 | 83 | PageReviewersGroup the reviews group; users who can review the changes
|
paul@17 | 84 | made by untrusted users
|
paul@17 | 85 |
|
paul@17 | 86 | Once installed, these group pages should be populated with real user
|
paul@17 | 87 | identities or other group names. See the following page for more information:
|
paul@17 | 88 |
|
paul@17 | 89 | http://moinmo.in/HelpOnGroups
|
paul@17 | 90 |
|
paul@17 | 91 | Without any usernames in the group pages, all users who are not nominated as
|
paul@17 | 92 | superusers will have their edits intercepted by the change queuing mechanism,
|
paul@17 | 93 | and only superusers will be able to review changes.
|
paul@17 | 94 |
|
paul@17 | 95 | To install the resource pages, use the following commands:
|
paul@17 | 96 |
|
paul@17 | 97 | python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/resource_pages resource_pages.zip
|
paul@17 | 98 | python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
|
paul@17 | 99 |
|
paul@17 | 100 | You may need to switch user in order to have sufficient privileges to copy the
|
paul@27 | 101 | page package into the wiki. For example:
|
paul@17 | 102 |
|
paul@17 | 103 | sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
|
paul@17 | 104 |
|
paul@17 | 105 | Configuration
|
paul@17 | 106 | -------------
|
paul@17 | 107 |
|
paul@17 | 108 | Once the event handler has been installed, all page saving operations will be
|
paul@17 | 109 | affected by its operation. With no further configuration, it is most likely
|
paul@27 | 110 | that only superusers will be able to save changes to wiki pages, and even the
|
paul@17 | 111 | queuing of changes will not function properly.
|
paul@17 | 112 |
|
paul@27 | 113 | Thus, it becomes necessary to change the wiki configuration to enable the
|
paul@17 | 114 | successful queuing of changes by changing the acl_rights_before configuration
|
paul@17 | 115 | setting, adding the following rule:
|
paul@17 | 116 |
|
paul@17 | 117 | ApprovalQueueUser:write,admin
|
paul@17 | 118 |
|
paul@27 | 119 | This will let the special internal wiki user responsible for queuing changes
|
paul@17 | 120 | (see "Pre-Installation Tasks") save and define an ACL on a page saved by an
|
paul@17 | 121 | untrusted user. See the following page for more information on access control
|
paul@17 | 122 | lists (ACLs):
|
paul@17 | 123 |
|
paul@17 | 124 | http://moinmo.in/HelpOnAccessControlLists
|
paul@17 | 125 |
|
paul@29 | 126 | The configuration settings used by ApproveChanges are as follows:
|
paul@29 | 127 |
|
paul@29 | 128 | queued_changes_page
|
paul@29 | 129 | -------------------
|
paul@29 | 130 |
|
paul@29 | 131 | The name of the subpage used to hold a queue of unapproved changes for a
|
paul@29 | 132 | page. By default, this setting is set to ApprovalQueue.
|
paul@29 | 133 |
|
paul@29 | 134 | Thus, edits to a page called WikiPage will get saved to a subpage called
|
paul@29 | 135 | WikiPage/ApprovalQueue. See also the queued_changes_per_user setting.
|
paul@29 | 136 |
|
paul@29 | 137 | queued_changes_per_user
|
paul@29 | 138 | -----------------------
|
paul@29 | 139 |
|
paul@29 | 140 | Whether the queued changes page resides below a user-specific subpage of the
|
paul@29 | 141 | edited page. By default, this setting is set to False. When set to a true
|
paul@29 | 142 | value, the username of any logged in unapproved user will be used when
|
paul@29 | 143 | setting the name of the unapproved changes subpage.
|
paul@29 | 144 |
|
paul@29 | 145 | Thus, any edits to a page called WikiPage will get saved to a subpage called
|
paul@29 | 146 | WikiPage/User/ApprovalQueue with this setting enabled. Otherwise, the
|
paul@29 | 147 | simpler form of subpage name will be used.
|
paul@29 | 148 |
|
paul@29 | 149 | approved_editors_group
|
paul@29 | 150 | ----------------------
|
paul@29 | 151 |
|
paul@29 | 152 | This gives the name of the group page holding the names of approved wiki
|
paul@29 | 153 | users. By default, it is set to ApprovedGroup. See "Resource Pages" above.
|
paul@29 | 154 |
|
paul@29 | 155 | reviewers_group
|
paul@29 | 156 | ---------------
|
paul@29 | 157 |
|
paul@29 | 158 | This gives the name of the group page holding the names of reviewers. By
|
paul@29 | 159 | default, it is set to PageReviewersGroup. See "Resource Pages" above.
|
paul@29 | 160 |
|
paul@29 | 161 | queued_changes_user
|
paul@29 | 162 | -------------------
|
paul@29 | 163 |
|
paul@29 | 164 | This gives the name of the user who saves unapproved changes to approval
|
paul@29 | 165 | queues. By default, it is set to ApprovalQueueUser.
|
paul@29 | 166 |
|
paul@27 | 167 | Troubleshooting
|
paul@27 | 168 | ---------------
|
paul@27 | 169 |
|
paul@27 | 170 | When a user tries to save a page, they get the following error (or
|
paul@27 | 171 | equivalent):
|
paul@27 | 172 |
|
paul@27 | 173 | You can't change ACLs on this page since you have no admin rights on it!
|
paul@27 | 174 |
|
paul@27 | 175 | This is possibly caused by the absence of the ApprovalQueueUser (see
|
paul@27 | 176 | "Pre-Installation Tasks" above) and/or the acl_rights_before rule for that
|
paul@27 | 177 | user (see "Configuration" above).
|
paul@27 | 178 |
|
paul@17 | 179 | Recommended Software
|
paul@17 | 180 | --------------------
|
paul@17 | 181 |
|
paul@17 | 182 | The moinsetup tool is recommended for installation since it aims to support
|
paul@17 | 183 | all versions of MoinMoin that are supported for use with this software.
|
paul@17 | 184 |
|
paul@17 | 185 | See the following page for information on moinsetup:
|
paul@17 | 186 |
|
paul@17 | 187 | http://moinmo.in/ScriptMarket/moinsetup
|
paul@17 | 188 |
|
paul@17 | 189 | Contact, Copyright and Licence Information
|
paul@17 | 190 | ------------------------------------------
|
paul@17 | 191 |
|
paul@17 | 192 | See the following Web page for more information about this work:
|
paul@17 | 193 |
|
paul@17 | 194 | http://moinmo.in/ActionMarket/ApproveChanges
|
paul@17 | 195 |
|
paul@17 | 196 | The author can be contacted at the following e-mail address:
|
paul@17 | 197 |
|
paul@17 | 198 | paul@boddie.org.uk
|
paul@17 | 199 |
|
paul@17 | 200 | Copyright and licence information can be found in the docs directory - see
|
paul@17 | 201 | docs/COPYING.txt and docs/LICENCE.txt for more information.
|
paul@17 | 202 |
|
paul@28 | 203 | New in ApproveChanges 0.2 (Changes since ApproveChanges 0.1.1)
|
paul@28 | 204 | --------------------------------------------------------------
|
paul@28 | 205 |
|
paul@28 | 206 | * Added user-specific approval queues.
|
paul@28 | 207 |
|
paul@25 | 208 | New in ApproveChanges 0.1.1 (Changes since ApproveChanges 0.1)
|
paul@25 | 209 | --------------------------------------------------------------
|
paul@25 | 210 |
|
paul@25 | 211 | * Fixed page reviewer access to changes. Many thanks to Jakub Jedelsky for
|
paul@25 | 212 | pointing out an obvious bug in the access logic (checking approved users
|
paul@25 | 213 | instead of reviewers) and non-functioning usage of the MoinMoin 1.9 API
|
paul@25 | 214 | to access group pages.
|
paul@25 | 215 |
|
paul@17 | 216 | Release Procedures
|
paul@17 | 217 | ------------------
|
paul@17 | 218 |
|
paul@23 | 219 | Update the ApproveChangesSupport.py __version__ attribute and the setup.py
|
paul@23 | 220 | version details.
|
paul@17 | 221 | Change the version number and package filename/directory in the documentation.
|
paul@17 | 222 | Update the setup.py and PKG-INFO files.
|
paul@17 | 223 | Update the release notes (see above).
|
paul@17 | 224 | Tag, export.
|
paul@17 | 225 | Archive, upload.
|
paul@17 | 226 | Update the ActionMarket (see above for the URL).
|