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 Installation
20 ------------
21
22 To install the software, consider using the moinsetup tool. See the
23 "Recommended Software" section below for more information.
24
25 With moinsetup and a suitable configuration file, the installation is done as
26 follows with $ACDIR referring to the ApproveChanges distribution directory
27 containing this README.txt file:
28
29 python moinsetup.py -f moinsetup.cfg -m install_extension_package $ACDIR
30 python moinsetup.py -f moinsetup.cfg -m install_actions $ACDIR/actions
31 python moinsetup.py -f moinsetup.cfg -m install_event_handlers $ACDIR/events
32
33 The first command above uses the setup.py script provided as follows:
34
35 python setup.py install --prefix=path-to-moin-prefix
36
37 The second and third commands install the action and event handler
38 respectively.
39
40 Useful Pages
41 ------------
42
43 The pages directory contains a selection of useful pages using a syntax
44 appropriate for use with MoinMoin 1.6 or later. These pages can be created
45 through the wiki and their contents copied in from each of the files. An
46 easier installation method is to issue the following commands:
47
48 python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/pages pages.zip
49 python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
50
51 You may need to switch user in order to have sufficient privileges to copy the
52 page package into the wiki. For example:
53
54 sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
55
56 Resource Pages
57 --------------
58
59 In order to assign wiki users to particular roles, some resource pages must be
60 set up in a wiki. For this purpose, the resource_pages directory contains
61 example pages defining the membership of two groups:
62
63 ApprovedGroup the approved users group; users whose changes do not
64 need to approved and who can edit the wiki normally
65
66 PageReviewersGroup the reviews group; users who can review the changes
67 made by untrusted users
68
69 Once installed, these group pages should be populated with real user
70 identities or other group names. See the following page for more information:
71
72 http://moinmo.in/HelpOnGroups
73
74 Without any usernames in the group pages, all users who are not nominated as
75 superusers will have their edits intercepted by the change queuing mechanism,
76 and only superusers will be able to review changes.
77
78 To install the resource pages, use the following commands:
79
80 python moinsetup.py -f moinsetup.cfg -m make_page_package $ACDIR/resource_pages resource_pages.zip
81 python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
82
83 You may need to switch user in order to have sufficient privileges to copy the
84 page package into the wiki. For example:
85
86 sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package resource_pages.zip
87
88 Configuration
89 -------------
90
91 Once the event handler has been installed, all page saving operations will be
92 affected by its operation. With no further configuration, it is most likely
93 that only superusers will be able to save changes to wiki pages, and the edits
94 of all other users will be queued.
95
96 The configuration settings used by ApproveChanges are as follows:
97
98 queued_changes_page
99 -------------------
100
101 The name of the subpage used to hold a queue of unapproved changes for a
102 page. By default, this setting is set to ApprovalQueue.
103
104 Thus, edits to a page called WikiPage will get saved to a subpage called
105 WikiPage/ApprovalQueue. See also the queued_changes_per_user setting.
106
107 queued_changes_per_user
108 -----------------------
109
110 Whether the queued changes page resides below a user-specific subpage of the
111 edited page. By default, this setting is set to False. When set to a true
112 value, the username of any logged in unapproved user will be used when
113 setting the name of the unapproved changes subpage.
114
115 Thus, any edits to a page called WikiPage will get saved to a subpage called
116 WikiPage/User/ApprovalQueue with this setting enabled. Otherwise, the
117 simpler form of subpage name will be used.
118
119 approved_editors_group
120 ----------------------
121
122 This gives the name of the group page holding the names of approved wiki
123 users. By default, it is set to ApprovedGroup. See "Resource Pages" above.
124
125 reviewers_group
126 ---------------
127
128 This gives the name of the group page holding the names of reviewers. By
129 default, it is set to PageReviewersGroup. See "Resource Pages" above.
130
131 Recommended Software
132 --------------------
133
134 The moinsetup tool is recommended for installation since it aims to support
135 all versions of MoinMoin that are supported for use with this software.
136
137 See the following page for information on moinsetup:
138
139 http://moinmo.in/ScriptMarket/moinsetup
140
141 Contact, Copyright and Licence Information
142 ------------------------------------------
143
144 See the following Web page for more information about this work:
145
146 http://moinmo.in/ActionMarket/ApproveChanges
147
148 The author can be contacted at the following e-mail address:
149
150 paul@boddie.org.uk
151
152 Copyright and licence information can be found in the docs directory - see
153 docs/COPYING.txt and docs/LICENCE.txt for more information.
154
155 New in ApproveChanges 0.2 (Changes since ApproveChanges 0.1.1)
156 --------------------------------------------------------------
157
158 * Added user-specific approval queues.
159 * Removed the special ApprovalQueueUser. This user can be removed from
160 existing installations since the software no longer needs it to perform
161 the queuing of unapproved contributions.
162
163 New in ApproveChanges 0.1.1 (Changes since ApproveChanges 0.1)
164 --------------------------------------------------------------
165
166 * Fixed page reviewer access to changes. Many thanks to Jakub Jedelsky for
167 pointing out an obvious bug in the access logic (checking approved users
168 instead of reviewers) and non-functioning usage of the MoinMoin 1.9 API
169 to access group pages.
170
171 Release Procedures
172 ------------------
173
174 Update the ApproveChangesSupport.py __version__ attribute and the setup.py
175 version details.
176 Change the version number and package filename/directory in the documentation.
177 Update the setup.py and PKG-INFO files.
178 Update the release notes (see above).
179 Tag, export.
180 Archive, upload.
181 Update the ActionMarket (see above for the URL).
