ApproveChanges

README.txt

30:623d4bb10f11
2013-11-05 Paul Boddie Removed the ApprovalQueueUser, making use of a special security policy instead.
     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).