ApproveChanges

README.txt

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