User:Jamesmontalvo3/Approved Revs v1.0

From mediawiki.org
MediaWiki extensions manual
Approved Revs
Release status: stable
Implementation Hook
Description Allows administrators to mark a certain revision of a page as "approved".
Author(s) Yaron Koren <yaron57@gmail.com> and others
Latest version 1.0.0 (June 2014)
MediaWiki 1.19 or greater
Database changes Yes
License GPL
Download See here
Translate the Jamesmontalvo3/Approved Revs v1.0 extension if it is available at translatewiki.net

NOTE: This is not (yet) the real Approved Revs. It is a major change which will hopefully be incorporated soon.

Approved Revs is an extension that lets users mark a certain revision of a page or file as "approved". The approved revision is the one displayed when users view the page at its main URL. When an image is displayed on a page, the approved revision is shown.

Approved Revs was designed to be a simple, lightweight alternative to the FlaggedRevs extension. FlaggedRevs is a very feature-rich, heavy-duty extension that provides not just revision approval but also reviewing and related features; it defines 4 user rights, 3 user groups, 15 global variables, 3 log types, 11 special pages and 9 database tables (by contrast, Approved Revs defines TBD user rights, no user groups, TBD global variables, TBD log type, 1 special page and 2 database tables). If you're running a large-scale wiki like, say, Wikipedia, where the decision of which revision to show as the "official" one has to be made by, or at least accepted by, many people, FlaggedRevs is most likely the right tool to use. However, if you're running a small- or medium-scale wiki, with just a few administrators, Approved Revs may be the more appropriate solution.

Even if a revision is approved, most extensions that retrieve the contents of pages will still get the last revision, and not the approved one (if the two are different). Extensions that get specific data from pages, however, such as Semantic MediaWiki and DPL, will, fortunately, display the correct (i.e., approved) data.

Download[edit]

You can download the Approved Revs code, in .zip format, here.

You can also download the code directly via Git from the MediaWiki source code repository. From a command line, you can call the following:

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/ApprovedRevs.git

To view the code online, including version history for each file, go here.

Un-nowiki this later: {{SB Extension}}

Installation[edit]

To install this extension, create an 'ApprovedRevs' directory (either by extracting a compressed file or downloading via Git), and place this directory within the main MediaWiki 'extensions' directory. Then, in the file 'LocalSettings.php', add the following line:

require_once( "$IP/extensions/ApprovedRevs/ApprovedRevs.php" );

You will also need to install two database tables for this extension called "approved_revs" and "approved_revs_files". You can do this in one of two ways: either run the script "update.php" in MediaWiki's /maintenance directory, or apply the SQL files directly to your database - they are ApprovedRevs.sql and ApprovedRevs_Files.sql.

MediaWiki's text search (i.e., the Special:Search page) will search pages based on the contents of their approved revision, if they have one. However, if you're using MediaWiki 1.19, the display of search results will still show the page's latest revision. To get this working correctly, you will have to apply a small patch to the core MediaWiki code - you can see it here.

Finally, there is one user right defined for Approved Revs: 'viewlinktolatest'. Users with this permission see a note at the top of pages that have an approved revision, explaining that what the user is seeing is not necessarily the latest revision. By default it is given to everyone (i.e, '*'), but can be modified to only be given to administrators by adding the following to LocalSettings.php below the inclusion of Approved Revs:

$wgGroupPermissions['*']['viewlinktolatest'] = false;
$wgGroupPermissions['sysop']['viewlinktolatest'] = true;

Defining Approvers[edit]

Defining who can approve pages is done at the page MediaWiki:Approvedrevs-permissions. Within this page there is a section called "configuration". If you edit the page, within this section there are settings defined within <syntaxhighlight lang="INI">...</syntaxhighlight> tags. These settings allow defining who can approve pages at the namespace, category or page level. The default is as follows:

All Pages = Group:sysop

[Namespace Permissions]
Main = 
User =
Template = 
Help = 
Project = 

[Category Permissions]

[Page Permissions]

This states that the Main, User, Template, Help and Project namespaces all require approval, but they have no special approvers listed. The "All Pages" approvals at the top state that the "sysop" group (i.e. administrators) have approval capability in all cases. No special approvals are available for categories or pages.

One special case is the user namespace: if the user namespace has approvals required (if it is listed in the [Namespace Permissions] section) then each user will have approval capability on their own pages. This includes any subpages of their main user page.

Below is a more complex example.

All Pages = Group:sysop

[Namespace Permissions]
Help = Group:Reviewers
Template =
Blog = Creator

[Category Permissions]
Approved Revision Required = Property:Subject Matter Expert

[Page Permissions]
Main Page = User:John Doe

The help namespace requires approvals and is approvable by users in the "Reviewers" group as well as the "sysop" group. The template namespace requires approvals, but is only approvable by sysops. Pages in the "Blog" namespace can be approved by the page creator as well as by sysops.

The category "Approved Revision Required" can be approved by anyone whose username is set as the "Subject Matter Expert" semantic property. For example, John Doe could approve such a page if [[Subject Matter Expert::John Doe]] was placed in the page. Using this feature requires that Semantic MediaWiki be installed. As with all pages, anyone defined in "All Pages" can also approve these pages (in this example just sysops).

For [Page Permissions], User:John Doe can approve the Main Page in addition to sysops.

Allowing File Approvals[edit]

A major change in version 1.0 of Approved Revs is the ability to mark file revisions as approved. As such, it is possible to add the file namespace to [Namespace Permissions], file pages to [Page Permissions] or add approvable categories to file pages.

Restrictions[edit]

It is not recommended that you add MediaWiki or Category namespaces to the [Namespace Permissions] section due to their special implementation in MediaWiki. Approvals will not work correctly on those pages.

Usage[edit]

A history page, with "approve" links, plus highlighting, a star and an "unapprove" link for the approved revision
Same view as above, but for user without approval rights

Once the extension is installed (and any changes to MediaWiki:Approvedrevs-permissions have been made), anyone with approval permissions for a given page will see a link that reads "(approve)" on each row of a page history page. Clicking on that link will set that revision as the approved one. If you then go back to the history page, you will see the revision you just approved is now highlighted green and is marked with a star and the text "Approved Revision". The approved revision also has an "unapprove" link on the far right. Every other revision has an "approve" link. Clicking "approve" for any other revision will re-set the approval to that revision; while clicking "unapprove" will mean that there will no longer be an approved revision for this page.

Users without approval capability will see nothing special in the history page, other than a star icon on the approved revision's row.

By default, if a user with approval capability makes an edit to a page that already has an approved revision, that edit, i.e. the latest revision of the page, gets automatically marked as approved. By contrast, if a page has no approved revision (this of course includes new pages), automatic approvals will not be applied.

You can eliminate automatic approvals, thus requiring that every approval has to be done manually, by adding the following to LocalSettings.php below the inclusion of Approved Revs:

$egApprovedRevsAutomaticApprovals = false;

Conversely, if you set $egApprovedRevsBlankIfUnapproved to true in LocalSettings.php (see below), every edit made by a user with approval capability becomes approved - even edits to pages that don't have an approved revision.

Manual revision approvals and unapprovals get stored in the 'approval' log; though approvals that happen automatically, as a result of someone with approval power editing a page, do not.

Approving Files[edit]

File approvals are performed in a slightly different manner from pages: instead of going to the "history" page for the file, simply go to the file page and scroll down the the "File History" section. Select a revision of the file from this table to be the approved revision in the same manner you would do for a page.

Once a file revision is approved, that revision will be what shows up on pages where the file is included. So the approved revision of images will be displayed and direct links (e.g. [[Media:...]] links) to PDFs or other documents will go to the approved revision.

Special:ApprovedRevs page[edit]

Approved Revs defines a special page, Special:ApprovedRevs, which can show two sets of lists: one for pages and one for files. Each set includes: all pages that have an approved revision, all pages whose approved revision is not their latest revision, all pages that do not have an approved revision, and pages considered "grandfathered". The grandfathered pages list shows pages that have approvals even though they do not meet the requirements laid out on MediaWiki:Approvedrevs-permissions. Generally this list should be blank, but is included in order to list pages which should perhaps be unapproved.

For the third list, of pages with no approved revision, you can optionally include a link for each page to mark that page's latest revision as approved. To include such links, add the following to LocalSettings.php:

$egApprovedRevsShowApproveLatest = true;

Displaying unapproved pages as blank[edit]

If you want to, you can have pages that have no approved revision show up as blank - users will still be able to see all the revisions if they click on the "history" tab, but the main display will be a blank page. To do that, just add the following line to LocalSettings.php, anywhere after the inclusion of Approved Revs:

$egApprovedRevsBlankIfUnapproved = true;

Indicating unapproved pages[edit]

By default, pages with no approved revision simply show up normally, with no indication of their status. You can have such pages display a message at the top saying, "This is the latest revision of this page; it has no approved revision." To do that, add the following line to LocalSettings.php:

$egApprovedRevsShowNotApprovedMessage = true;

Marking all pages as approved[edit]

For pages that do not yet have an approved revision, you may want to automatically approve their latest revision, as a way to quickly initialize their content. For that, you can use the command line script 'ApprovedRevs/maintenance/approveAllPages.php'. This script approves the latest revision of all pages that can be approved but do not have an approved revision.

Authors[edit]

Approved Revs was written by Yaron Koren. Important code contributions were also made by Raimond Spekking, Siebrand Mazeland, Jeroen De Dauw, Eli Handel and James Montalvo.

Version history[edit]

Approved Revs is currently at version 1.0. See the entire version history. Note that there are several deprecations from version 0.7:

  • The __APPROVEDREVS__ magic word should not be used any longer and is maintained only for backwards compatibility. In later revisions this magic word may be removed. Instead use the [Page Permissions] section of MediaWiki:Approvedrevs-permissions.

Known issues[edit]

  • When using MediaWiki 1.19, the "approve" link does not show up for all revisions in the history page, when viewing the page with the Google Chrome or Safari browsers.

Contributing to the project[edit]

Bugs and feature requests[edit]

Send any bug reports and requests to Yaron Koren, at yaron57 -at- gmail.com.

Contributing patches to the project[edit]

If you found some bug and fixed it, or if you wrote code for a new feature, please either do a Git commit for it, or create a patch by going to the "ApprovedRevs" directory, and typing:

git diff > descriptivename.patch

If you create a patch, please send it, with a description, to Yaron Koren.

Translating[edit]

Translation of ApprovedRevs is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Un-nowiki this when released: [[Category:Revision management extensions]]