Help:Extension:FlaggedRevs

is an extension to the MediaWiki software that allows a wiki to monitor the changes that are made to pages, and to control more carefully the content that is displayed to the wiki's readers. Pages can be flagged by certain "editors" and "reviewers" to indicate that they have been reviewed and found to meet whichever criteria the wiki requires. Each subsequent version of the page can be "flagged" by those users to review new changes. A wiki can use a scale of such flags, with only certain users allowed to set each flag.

The ability to flag revisions makes it easier to co-ordinate the process of maintaining a wiki, since it is much clearer which edits are new (and potentially undesirable) and which have been accepted as constructive. It is possible, however, to configure pages so that only revisions that are flagged to a certain level are visible when the page is viewed by readers; hence, changes made by users who cannot flag the resulting version to a high enough level remain in a "draft" form until the revision is flagged by another user who can set a higher flag.

FlaggedRevs is extremely flexible and can be used in a wide range of configurations; it can be discreet enough to be almost unnoticeable, or it can be used to very tightly control a wiki's activity.

Terminology
FlaggedRevs introduces some new terminology relating to users and editing. While each term is fully customizable to allow for language differences or per-wiki customisation, some terminology is generally universal.


 * Flags and flagging

FlaggedRevs allows wikis to define "flags" that can be applied to revisions of a page to indicate the quality or other attributes of that version. Flags are grouped into hierarchical "scales"; while some wikis use only one scale, others may use multiple scales to indicate different attributes of a page. For instance, the default configuration of FlaggedRevs defines three scales, "Accuracy", "Depth" and "Readability", with each scale containing four flags.


 * Markers

Markers are more abstract groupings of flags that identify articles as generally of a particular quality. There are three markers available, "checked", "quality" and "pristine". By default, any revision that has been flagged to any level on all of the flag scales that the wiki uses, qualifies for the "reviewed" marker. The default settings for the "quality" marker are level-1 for accuracy and depth, and level-2 for readability. For the "pristine" marker, a revision must (by default) be reviewed at the highest level on all three scales. Most wikis will define their own custom flag scales and so these settings will differ.


 * Stable and current versions

A page on which FlaggedRevs has been enabled is available in two 'aliases': the "current version" and the "stable version".

Current version
 * The current version is, as expected, the most recent version including the most recent edits, whether or not those edits were constructive.
 * The current version is also referred to as the draft of a page.

Stable version
 * The stable version is the most recent version of the page that has been reviewed

You can always link directly to the current or stable versions of a page, by appending &stable=0 or &stable=1 to the url, respectively.

Viewing


FlaggedRevs allows a wiki to mark each revision of a page with a flag to indicate its quality or validity, and to control which revisions are shown by default on a page. Each page where FlaggedRevs is enabled is effectively given two alternative aliases; these are the "stable" version, which is the latest version that has been flagged to a sufficiently high level, and the "current" version, which is the most recent revision, flagged or not. Readers can access either version of the page by adding &stable= to the URL in the address bar, setting &stable=0 for the current version, and &stable=1 for the stable version. On each alias, there is an explanation and a link to the other version.

Wiki developers can control which alias is displayed to users and readers by default, and which flags allow a version to be considered 'stable'. Registered users can customise which alias they see by default in their User Preferences. Editors are also made aware of which alias they are viewing by the "" tab, which instead displays.

Editing


FlaggedRevs does not affect a user's ability to edit a page; only the way the resulting version is handled by the wiki. Whenever a user edits a page, the contents of the edit window are always the wikimarkup for the current version, to prevent revision forks from accumulating. When there are unreviewed changes made since the last stable version, a diff is provided above the edit window to highlight any changes. This is important as the text being edited may not be the same as the page the user viewed before clicking the "" link (if the user was viewing the stable version); and it allows any changes to be immediately reviewed and modified or reverted if necessary.



If the user will not be able to see their changes in the default alias, an additional warning message is displayed,. Other than this the editing process is unchanged by FlaggedRevs; edits are made, previewed and saved in the normal manner.

Users who are capable of reviewing edits are encouraged to do so both during and after they edit. There is an option next to the "" and "" checkboxes to immediately review the version resulting from that edit, although this option is unchecked by default. Once a reviewer has made an edit, they are returned to the article as normal, but are presented with a diff of all changes, including theirs, since the last stable version, with the option to immediately review the changes.

Reviewing


Reviewing versions is the primary new activity introduced by FlaggedRevs. With the exception of the "review this edit" checkbox on the edit screen, all methods of reviewing versions use the same interface. At the bottom of a draft page, a series of radio buttons or checkboxes allows the reviewer to select which flags to apply to the revision, and there is the option to provide a comment that will appear in the review log.

Users can review any version, including versions that have already been reviewed by others. In this instance the newest review overrides previous reviews: if the new reviewer flags the version at a higher level than the previous reviewer, it is considered a normal "approve" review, while 'confirming' another reviewer's assessment by flagging the version to the same level is recorded as a "re-review". By flagging a previously-reviewed version as 'unassessed', reviewers can effectively 'unflag' a revision; these "deprecations" can be seen in a separate stream in.

Finding unreviewed versions
FlaggedRevs is designed to encourage eligible editors to review versions quickly and efficiently, and so links are provided in most common locations to review changes by editors who cannot flag the versions themselves. Edits that have resulted in an unreviewed version are marked with an exclamation mark ! in the watchlist and the RecentChanges feed, with a link to review the changes. When viewing a page that has unreviewed edits, a banner is also added to indicate the number of edits since the last stable version, the age of the stable version, and a link to review the changes.



The FlaggedRevs extension also creates a number of new special pages that can be used to find and manage reviewed and unreviewed pages:


 *  - pages which have a stable version


 * ' (called ' on some wikis) - pages that have pending changes from the stable version.


 *  - pages that have pending changes from the stable version that also have recent changes tags.


 *  - pages that have no reviewed stable version.

The latter two pages also include the number of users who have each page on their watchlist, so that 'backwater' articles can be identified and monitored; because of this slightly sensitive information, access to pages is usually restricted to users who have the ability to review versions. is sorted by the time since the last revision was flagged, oldest first.

General oversight
In addition to these pages, several other reports give general oversight over the reviewing process. is a list of pages where the default display settings have been overridden by administrators to either always show readers the "stable" alias by default or always show readers the "current" alias by default, depending on the wiki's FlaggedRevs settings.

 provides an aggregated log of all reviews made on the wiki. These events are also added in a new 'stream' to the main log at Special:Log, at Special:Log/review. However, the report at can be filtered by marker type, namespace, whether the action was to review, unreview or re-review the revision, and whether the review was automatic or manual.

Finally,  provides a summary of how thoroughly each content namespace has been reviewed, and other useful data about the reviewing process.

Autopromotion
Wikis can configure FlaggedRevs to automatically grant editors the ability to review versions when they meet certain thresholds of activity. Wikis need to judge carefully how best to configure the autopromotion feature (if at all) to be as confident as possible that the user is a constructive editor, without making them wait too long to be promoted. Thresholds can be set on a number of attributes, including:


 * How old the user's account is (number of days since they registered)


 * Their total editcount
 * It can be required that these edits have been made consistently over a time period, eg 20 edits spread over a period of 20 days would qualify, but 20 edits all at once would not
 * Edits from the last X days can be excluded from the count (giving admins time to look at them)
 * A certain number of these edits can also be required to be in "content" namespaces


 * The number of separate content pages the user has edited


 * The number of edits the user has made that include an edit summary
 * Whether the user has a user page, and how substantial it is (bytecount)


 * Whether the user has ever been blocked


 * The number of reverted edits the user has (not counting self-reverts)


 * How many times the user made an edit summary (including automatic ones)

The autopromotion mechanism can be overridden by administrators, either to promote a user who does not meet the criteria, or to demote a user who has abused the reviewing ability.

Administrators' abilities


While a wiki's developers can define default settings for which alias is presented to each user group by default, these settings can be customised by individual users and for individual pages. Each registered user can set in their preferences whether they wish to see the "current" or "stable" alias by default when viewing an article.

Some group on the wiki, usually administrators, have the ability to use the special page  to override the default display for unregistered users. Administrators can set a page to display the stable version by default, and can also control how the stable version is selected, choosing which marker is preferred.

Administrators also have the ability to grant users the ability to review edits, and to revoke that permission in case of abuse, by using the Special:UserRights interface. This explicit assignment overrides any permissions automatically given to the user by the autopromote feature – if an administrator has explicitly revoked a user's reviewing permissions, the autopromote feature will not grant them back, and vice versa.