ApproveChanges

README.txt

34:5e947e093388
2013-11-10 Paul Boddie Added user blocking and the removal of all queued edits for a user. Fixed "ApprovalQueue" usage, retrieving the configured approval queue page name.
     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 See the "Dependencies" section below for essential software.
   135 
   136 The moinsetup tool is recommended for installation since it aims to support
   137 all versions of MoinMoin that are supported for use with this software.
   138 
   139 See the following page for information on moinsetup:
   140 
   141 http://moinmo.in/ScriptMarket/moinsetup
   142 
   143 Contact, Copyright and Licence Information
   144 ------------------------------------------
   145 
   146 See the following Web page for more information about this work:
   147 
   148 http://moinmo.in/ActionMarket/ApproveChanges
   149 
   150 The author can be contacted at the following e-mail address:
   151 
   152 paul@boddie.org.uk
   153 
   154 Copyright and licence information can be found in the docs directory - see
   155 docs/COPYING.txt and docs/LICENCE.txt for more information.
   156 
   157 Dependencies
   158 ------------
   159 
   160 ApproveChanges has the following basic dependencies:
   161 
   162 Packages                    Release Information
   163 --------                    -------------------
   164 
   165 MoinSupport                 Tested with 0.4.2
   166                             Source: http://hgweb.boddie.org.uk/MoinSupport
   167 
   168 New in ApproveChanges 0.2 (Changes since ApproveChanges 0.1.1)
   169 --------------------------------------------------------------
   170 
   171   * Added user-specific approval queues.
   172   * Removed the special ApprovalQueueUser. This user can be removed from
   173     existing installations since the software no longer needs it to perform
   174     the queuing of unapproved contributions.
   175   * Added usage of MoinSupport for common extension functionality.
   176 
   177 New in ApproveChanges 0.1.1 (Changes since ApproveChanges 0.1)
   178 --------------------------------------------------------------
   179 
   180   * Fixed page reviewer access to changes. Many thanks to Jakub Jedelsky for
   181     pointing out an obvious bug in the access logic (checking approved users
   182     instead of reviewers) and non-functioning usage of the MoinMoin 1.9 API
   183     to access group pages.
   184 
   185 Release Procedures
   186 ------------------
   187 
   188 Update the ApproveChangesSupport.py __version__ attribute and the setup.py
   189 version details.
   190 Change the version number and package filename/directory in the documentation.
   191 Update the setup.py and PKG-INFO files.
   192 Update the release notes (see above).
   193 Tag, export.
   194 Archive, upload.
   195 Update the ActionMarket (see above for the URL).