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