Extension:Approved Revs

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
Crystal Clear action run.svg
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 0.8 (April 2018)
MediaWiki 1.23 or greater
Database changes Yes
License GNU General Public License 2.0 or later
Download
Added rights
viewlinktolatest, approverevisions, viewapprover
Hooks used
ArticleDeleteComplete
ArticleEditUpdates
ArticleFromTitle
ArticleViewHeader
BeforeParserFetchTemplateAndtitle
DisplayOldSubtitle
EditPage::showEditForm:initial
LoadExtensionSchemaUpdates
MagicWordwgVariableIDs
OutputPageBodyAttributes
PageContentSaveComplete
PageHistoryBeforeList
PageHistoryLineEnding
ParserBeforeTidy
PersonalUrls
SearchResultInitFromTitle
SkinTemplateNavigation
ArticleAfterFetchContentObject
wgQueryPages
ParserFirstCallInit
ImagePageFileHistoryLine
BeforeParserFetchFileAndTitle
ImagePageFindFile
FileDeleteComplete
AdminLinks
PageForms::HTMLBeforeForm
Hooks provided
ApprovedRevsPageIsApprovable
ApprovedRevsFileIsApprovable
ApprovedRevsRevisionApproved
ApprovedRevsRevisionUnapproved
Translate the Approved Revs extension if it is available at translatewiki.net
Check usage and version matrix.
Issues Open tasks · Report a bug

Approved Revs is an extension that lets administrators mark a certain revision of a page as "approved". The approved revision is the one displayed when users view the page at its main URL.

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 3 user rights, no user groups, 6 global variables, 1 log type, 1 special page and 1 database table). 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 Cargo, Semantic MediaWiki and DynamicPageList, 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/p/mediawiki/extensions/ApprovedRevs.git

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

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 either one of the following lines:

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

You will also need to install a database table for this extension, also called "approved_revs". You can do this in one of two ways: either run the script "update.php" in MediaWiki's /maintenance directory, or call the SQL directly in your database - you can find it in the file ApprovedRevs.sql.

If you were running a version of Approved Revs older than 0.8, and are upgrading to version 0.8 or higher, you will need to call update.php again, in order to have the latest DB table structure.

Finally, there are three user rights defined for Approved Revs: 'approverevisions' and 'viewlinktolatest':

  • 'approverevisions' is the permission to approve and unapprove revisions of pages. By default it is given to all members of the 'sysop' group.
  • 'viewlinktolatest' is the "permission" to 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, '*').
  • 'viewapprover' is the "permission" to see another note at the top of pages that have an approved revision, stating who last approved it. By default it is given to all members of the 'sysop' group.

You can modify the set of users who have any of these permissions. For example, to have the "view most recent revision" link show up only for administrators, you could add the following, below the inclusion of Approved Revs:

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

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, Andrew Engelbrecht, hashar, Anomie, Mark Hershberger, Flo, Addshore, James Montalvo, Fodagus and others.

Usage[edit]

A history page, with "approve" links, plus a star and an "unapprove" link for the approved revision

Once the extension is installed, anyone with the 'approverevisions' permission 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 an "approve" link next to every other revision, along with an "unapprove" link for the approved revision; the approved revision's row will also have a star next to it. 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 'approverevisions' permission 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 'approverevisions' permission 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 'approverevisions' permission 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.

Special:ApprovedRevs page[edit]

Approved Revs defines a special page, "Special:ApprovedRevs" which shows four separate lists:

  • pages whose approved revision is not their latest
  • all pages with an approved revision
  • "unapproved pages" (all pages without an approved revision)
  • pages with invalid approvals (such as pages in a namespace that was previously approvable but no longer is).

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;

Storage of approval information[edit]

Information about approvals - who made them, and when they were made - is stored in the "Revision approval" log, which can be viewed at the page Special:Log. Recent approvals are also shown in Special:RecentChanges.

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;

Setting pages as approvable[edit]

Some wiki pages can have their revisions approved, while others cannot; this is determined in one of three ways.

Setting all pages in a namespace as approvable[edit]

A global variable, $egApprovedRevsEnabledNamespaces, exists, that determines which namespaces are handled by the extension. This variable is an array, and by default it holds six namespaces: NS_MAIN (the main namespace), NS_USER (user pages), NS_FILE (files), NS_TEMPLATE (templates), NS_HELP (help pages) and NS_PROJECT (the project namespace, which usually has the same name as the wiki). You can add additional namespaces to this set - after the inclusion of Approved Revs in LocalSettings.php, add something like:

$egApprovedRevsNamespaces[NS_USER_TALK] = true;

It is not recommended to add the Category or MediaWiki namespaces to this array, because, due to their special implementation in MediaWiki, approvals will not work correctly on those pages.

To remove default namespaces as approvable, do the following:

$egApprovedRevsNamespaces[NS_FILE] = false;

This removes the file namespace as approvable. The file namespace was not approvable prior to Approved Revs v1.0.

Setting pages approvable via parser function #approvable_by[edit]

Since version 1.0, Approved Revs provides the #approvable_by parser function. This parser function does two things: (1) it allows to define otherwise unapprovable pages to be approved (similar to the magic word described below) and (2) it allows specifying individual users and groups to be able to approve the page. For example, the following could be added to a page:

{{#approvable_by: users = Alice Jones | groups = bureaucrat,sysop }}

This would allow users Alice Jones to approve the page, as well as users in the Bureaucrat and Sysop groups. If the page does not yet have an approval after the above wikitext is added, then any of these users can approve this revision. If it already had an approved revision then only users who were able to approve revisions prior revisions would be able to approve the new revision with the parser function. For further example, suppose the above wikitext is added to the page, and someone approves that revision. Alice Jones would then be able to approve any revision to the page. However, if she approved a revision prior to the one that gave her approval capability she would no longer be able to approve revisions (assuming she didn't have approval rights from some other method). Next, say user Bob Smith changes the above wikitext to:

{{#approvable_by: users = Alice Jones, Bob Smith | groups = bureaucrat,sysop }}

Bob Smith would not be able to approve revisions yet, but if Alice Jones approved this revision then he would be able.

Setting pages approvable via magic word[edit]

Individual pages not within one of the specified namespaces can also be made approvable, by adding the __APPROVEDREVS__ magic word anywhere within the page. It is recommended to add in this magic word to pages via a template. If __APPROVEDREVS__ is added directly to a page, just be careful not to approve a revision of the page from before that string was added; this could lead to unexpected behavior.

Letting non-administrators "own" pages[edit]

Sometimes it's helpful to allow those without the general 'approverevisions' permission to be able to approve revisions of certain pages - in other words, to have ownership of certain pages. An obvious example is user pages - it makes sense to allow each user to be able to approve revisions on their own user pages. For namespaces other than "User", you can choose to have the user who originally created any page in that namespace be designated as the page owner, who then has revision-approval permission for that page.

To have this kind of "ownership" for a specific namespace, you need to add the namespace to the variable $egApprovedRevsSelfOwnedNamespaces. To allow users to "own", i.e. be able to approve, pages in the main and user namespaces, for instance, you should add the following to LocalSettings.php:

$egApprovedRevsSelfOwnedNamespaces = array( NS_MAIN, NS_USER );

A namespace needs to belong to $egApprovedRevsNamespaces before it can be added to $egApprovedRevsSelfOwnedNamespaces.

API[edit]

Approved Revs defines an API action, "approve", which lets you either approve or (if the extra parameter "unapprove" is added) unapprove any revision via the MediaWiki API. See here for an explanation of the syntax for this API.

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.

File approvals[edit]

Selecting version of a file to be approved

Approved Revs v1.0 added the capability to approve file revisions. One distinction must be made clear, however: The file revisions themselves are approvable, but the revisions to the wikitext of the file pages are not approvable. As such, approval of files is not done by clicking the "view history" link in the top-right of the file's page. Instead, scroll to the "File history" section near the bottom of the file page, and click "approve" on the right of the file history table.

When a version of an image is approved, that version is displayed when the image is included on other pages. For non-image uploads (e.g. PDFs), any links directly to the file will go to the approved version, not the latest.

Version history[edit]

Approved Revs is currently at version 0.8. See the entire version history.

Breaking change in v1.0[edit]

The current released version of Approved Revs is 0.8, but v1.0 will be released soon. Due to changes in MediaWiki, it was required to change from using the $egApprovedRevsNamespaces variable to using the new $egApprovedRevsEnabledNamespaces variable. Please see the section above "Setting all pages in a namespace as approvable" for info on how to use this variable for configuring approvable namespaces.

Known issues[edit]

  • Approved Revs does not seem to work with the AccessControl extension - approving a revision leads to a "Deny_action" error.

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 Approved Revs 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.

See also[edit]