ApproveChanges

Annotated README.txt

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