Manual:Reverts

A revert is (broadly speaking) an edit that reverses the actions of other editors. In that process a new version of the page is created.

This page serves as an overview of various types of reverts supported and recognized by MediaWiki, mainly for developers. It also discusses how to integrate extensions with revert-related mechanisms present in MediaWiki core.

Revert types

There are three methods of performing reverts that are recognized by MediaWiki.

Undo

UI

Undos are performed using the undo link that appears in page history, diff view, recent changes list and other places.

Undo links point to index.php?action=edit with undo and undoafter parameters that specify which edits should be undone.

• undo – the ID of the last revision being undone.
• undoafter – the ID of the last "good" revision. The next revision will be the first revision being undone.

See also: Manual:Parameters to index.php#Edit and submit

API

Undos can be performed through API using action=edit with undo and undoafter parameters. Their behavior is the same as in index.php?action=edit.

Mechanism

All revisions from undoafter (exclusive) to undo (inclusive) are reverted. More technically, EditPage applies the inverse of the diff between the undoafter and undo revisions to the current version of the page. If that is not possible, a regular edit form is displayed and the edit is not counted as an undo.

After that, the edit form is displayed to the user, where the resulting content can be further modified.

Since version 1.36, if the user performs any modifications to the content before saving, the edit is not marked as an undo. This is to prevent users from marking arbitrary edits as undos.

Undo is the only revert method that allows for reverting intermittent changes. It is also the only one that does not necessarily restore the page to a previous state. undoafter and undo can point to any revision, they don't have to be on the page the undo is being applied to. This means that in theory an undo can be crafted for any arbitrary change to the page.

Other content types

If your extension implements a new ContentHandler, it can override the getUndoContent method in order to customize how undos are handled by your content type.

Rollback

UI

Rollback can be performed using the rollback link that appears in page history, diff view, recent changes list and other places.

Rollback links point to index.php?action=rollback with additional parameters for ensuring the correct set of changes is being rolled back.

See also: Manual:Parameters to index.php#rollback

API

Rollbacks can be performed through API using action=rollback. Their behavior is the same as in index.php?action=rollback.

Mechanism

Rollback reverts the last edits made by the last editor of the page. This is a commonly useful scenario when dealing with vandalism, as usually all changes made recently by one user should be reverted.

When all revisions of the page are from the same user, it cannot be rolled back.

Manual revert

MediaWiki version:

≥ 1.36

The manual revert does not use any special UI or API, someone just edits the page in a way that returns it to an older version. Sometimes this is done by navigating to an old revision of the page in the page history, clicking edit (which opens the normal edit form but prepopulates it with the content of that revision) and saving; sometimes by just editing the latest revision by hand (especially when reverting a small change). The software automatically infers (within limits) when an edit reverts the page to an older version. Every time an edit is made, MediaWiki looks at a number of most recent revisions of the page (specified by $wgManualRevertSearchRadius, 15 by default) and looks for the most recent revision with matching content. If such a revision is found, the edit is marked as a "manual revert", i.e. an edit restoring the page to an exact previous state.

The feature can be disabled entirely by setting $wgManualRevertSearchRadius to zero.

Other revert types

For multi-content revisions, there are two more index.php actions: mcrundo (which is the same as undo but works on all slots of the revision) and mcrrestore (which reverts all slots to an older revision). These are expected to go away once multi-content revisions are better integrated with the editing logic.

Revert tags

By default every revision considered a revert by MediaWiki is marked with an appropriate change tag. Each of these tags can be individually disabled using the $wgSoftwareTags configuration variable.

• Undo: mw-undo
• Rollback: mw-rollback
• Manual revert: mw-manual-revert

Since version 1.36 additional data about the revert is saved with each tag in the ct_params field of the change_tag table. The data is the EditResult object associated with the edit (see the next section), encoded as JSON.

Accessing revert information in extensions

MediaWiki version:

≥ 1.35

Version 1.35 introduced the EditResult class that is constructed when saving an edit. This object encapsulates information about the effects of the edit in the context of its page's history, most importantly:

• whether the edit was a revert,
• which revert method was used,
• what is the "base" revision for this revert,
• which revisions were reverted.

This object is passed to extensions using the PageSaveComplete hook.

Reverted tag

MediaWiki version:

≥ 1.36

In version 1.36 a new change tag is introduced – mw-reverted that is used to mark reverted edits.

Scheduling and execution

The tag is applied in a job named revertedTagUpdate scheduled using the job queue. The job is added to the queue by DerivedPageDataUpdater after the edit is saved.

If your wiki has a busy job queue and you encounter significant delays between making reverts and the tag being applied, you may want to execute the job in a separate queue or prioritize it, depending on your setup. See Manual:Job queue for details.

Conditions for execution

The update will be scheduled after saving an edit if all of the following conditions are met:

• The edit is a revert of any type recognized by MediaWiki. See #Revert types.
• The number of reverted edits is less or equal to $wgRevertedTagMaxDepth.
• The reverting revision itself is not marked as reverted or deleted.
• The edit is considered auto-approved, which can have different meanings depending on your setup:
  • If you have patrolling enabled on your wiki through the $wgUseRCPatrol configuration variable, auto-approval is equivalent to the edit being autopatrolled. Thus, only users with autopatrol user right will have their reverted tag applied right away.
  • If you have installed a content management extension such as FlaggedRevs it can tell MediaWiki if the edit is auto-approved. How exactly is this determined depends on the extension. (See #Extension integration.)

If the reverted tag update is stopped by the patrol subsystem or an extension, it can be later rescheduled when the edit is approved by a different user. In case of patrolling, this happens when the edit is patrolled. See the next section for details on how to integrate with this feature in extensions.

Tracked in Phabricator
Task T265312

The mw-reverted tag will never be applied to null revisions corresponding to log actions (e.g. page moves and protection changes), even if they appear in the middle of the series of reverted edits, in order to avoid suggesting that the relevant action has been undone.

Content management extensions like FlaggedRevs will generally override the behavior of the patrolling subsystem.

Patrolling is enabled by default, but some wikis that have it enabled do not utilize it or use it only partially (many edits are never patrolled). Reverts that are not patrolled will not be marked with the reverted tag. Make sure your current configuration is suitable for your wiki. You can try disabling patrolling entirely or giving the autopatrol user right to a wider group of users.

Extension integration

Extensions that involve some kind of revision approval mechanism can hook into the reverted tag feature to let MediaWiki know when to perform the reverted tag update.

The first part of this is the BeforeRevertedTagUpdate hook. It is called before the update is scheduled and extensions can use this hook to prevent the update from running if the edit is not considered auto-approved and needs further review.

If the update was stopped, it can be later rescheduled by the extension using the RevertedTagUpdateManager service.

Approving a revision

$revertedTagUpdateManager = MediaWikiServices::getInstance()->getRevertedTagUpdateManager();
$revertedTagUpdateManager->approveRevertedTagForRevision( $acceptedRevisionId );

Nothing catastrophic will happen if you request the same update to be performed twice. The update is idempotent.

FlaggedRevs

If you have installed the FlaggedRevs extension, the revert will be considered auto-approved if either:

• FlaggedRevs is configured to not be used on the page.
• The user has the autoreview user right.
• The edit is a self revert.
• The edit is otherwise eligible to be autoreviewed.

If the revert was not auto-approved, it can be later approved by simply reviewing the edit.

See also

• Manual:Rollback
• m:Research:Revert