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