User:Ostrzyciel/GSoC 2020/manual

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.

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  with   and   parameters that specify which edits should be undone.
 * – the ID of the last revision being undone.
 * – the ID of the last "good" revision. The next revision will be the first revision being undone.

See also: Manual:Parameters to index.php

API
Undos can be performed through API using  with   and   parameters. Their behavior is the same as in.

Mechanism
All revisions from  (exclusive) to   (inclusive) are reverted. EditPage attempts to merge the inverse of these edits with the sequence of all subsequent edits. 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.

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

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  with additional parameters for ensuring the correct set of changes is being rolled back.

See also: Manual:Parameters to index.php

API
Rollbacks can be performed through API using. Their behavior is the same as in.

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.

Manual revert
The manual revert does not use any special UI or API, as it is inferred by the software automatically. Every time an edit is made, MediaWiki looks at a number of most recent revisions of the page (specified by, 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  to zero.

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  configuration variable.
 * Undo:
 * Rollback:
 * Manual revert:

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

Accessing revert information in extensions
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
In version 1.36 a new change tag is introduced –  that is used to mark reverted edits.

Scheduling and execution
The tag is applied in a job named  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:.
 * The number of reverted edits is less or equal to.
 * 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  configuration variable, auto-approval is equivalent to the edit being autopatrolled. Thus, only users with   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: ).

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.

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  service. The same service can also be used to "discard" an update in case the edit was explicitly rejected by a reviewer.


 * Approving a revision example


 * Discarding an update

And that's it. You may also want to run the above snippets in a deferred update in the "postsend" stage. This will slightly improve response times for clients and should ensure correct ordering of jobs in the queue.

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  user right.
 * The edit is a self revert.
 * The edit is otherwise eligible to be autoreviewed.