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@17 | 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@27 | 126 | Troubleshooting
|
paul@27 | 127 | ---------------
|
paul@27 | 128 |
|
paul@27 | 129 | When a user tries to save a page, they get the following error (or
|
paul@27 | 130 | equivalent):
|
paul@27 | 131 |
|
paul@27 | 132 | You can't change ACLs on this page since you have no admin rights on it!
|
paul@27 | 133 |
|
paul@27 | 134 | This is possibly caused by the absence of the ApprovalQueueUser (see
|
paul@27 | 135 | "Pre-Installation Tasks" above) and/or the acl_rights_before rule for that
|
paul@27 | 136 | user (see "Configuration" above).
|
paul@27 | 137 |
|
paul@17 | 138 | Recommended Software
|
paul@17 | 139 | --------------------
|
paul@17 | 140 |
|
paul@17 | 141 | See the "Dependencies" section below for essential software.
|
paul@17 | 142 |
|
paul@17 | 143 | The moinsetup tool is recommended for installation since it aims to support
|
paul@17 | 144 | all versions of MoinMoin that are supported for use with this software.
|
paul@17 | 145 |
|
paul@17 | 146 | See the following page for information on moinsetup:
|
paul@17 | 147 |
|
paul@17 | 148 | http://moinmo.in/ScriptMarket/moinsetup
|
paul@17 | 149 |
|
paul@17 | 150 | Contact, Copyright and Licence Information
|
paul@17 | 151 | ------------------------------------------
|
paul@17 | 152 |
|
paul@17 | 153 | See the following Web page for more information about this work:
|
paul@17 | 154 |
|
paul@17 | 155 | http://moinmo.in/ActionMarket/ApproveChanges
|
paul@17 | 156 |
|
paul@17 | 157 | The author can be contacted at the following e-mail address:
|
paul@17 | 158 |
|
paul@17 | 159 | paul@boddie.org.uk
|
paul@17 | 160 |
|
paul@17 | 161 | Copyright and licence information can be found in the docs directory - see
|
paul@17 | 162 | docs/COPYING.txt and docs/LICENCE.txt for more information.
|
paul@17 | 163 |
|
paul@28 | 164 | New in ApproveChanges 0.2 (Changes since ApproveChanges 0.1.1)
|
paul@28 | 165 | --------------------------------------------------------------
|
paul@28 | 166 |
|
paul@28 | 167 | * Added user-specific approval queues.
|
paul@28 | 168 |
|
paul@25 | 169 | New in ApproveChanges 0.1.1 (Changes since ApproveChanges 0.1)
|
paul@25 | 170 | --------------------------------------------------------------
|
paul@25 | 171 |
|
paul@25 | 172 | * Fixed page reviewer access to changes. Many thanks to Jakub Jedelsky for
|
paul@25 | 173 | pointing out an obvious bug in the access logic (checking approved users
|
paul@25 | 174 | instead of reviewers) and non-functioning usage of the MoinMoin 1.9 API
|
paul@25 | 175 | to access group pages.
|
paul@25 | 176 |
|
paul@17 | 177 | Release Procedures
|
paul@17 | 178 | ------------------
|
paul@17 | 179 |
|
paul@23 | 180 | Update the ApproveChangesSupport.py __version__ attribute and the setup.py
|
paul@23 | 181 | version details.
|
paul@17 | 182 | Change the version number and package filename/directory in the documentation.
|
paul@17 | 183 | Update the setup.py and PKG-INFO files.
|
paul@17 | 184 | Update the release notes (see above).
|
paul@17 | 185 | Tag, export.
|
paul@17 | 186 | Archive, upload.
|
paul@17 | 187 | Update the ActionMarket (see above for the URL).
|