View source for Manual:Reverts/zh

<languages/>
<span lang="en" dir="ltr" class="mw-content-ltr">A '''revert''' is (broadly speaking) an edit that reverses the actions of other editors.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In that process a new version of the page is created.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This page serves as an overview of various types of reverts supported and recognized by MediaWiki, mainly for developers.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It also discusses how to integrate extensions with revert-related mechanisms present in MediaWiki core.</span>

<span id="Revert_types"></span>
== 回退种类 ==

<div lang="en" dir="ltr" class="mw-content-ltr">
There are three methods of performing reverts that are recognized by MediaWiki.
</div>

<span id="Undo"></span>
=== 撤销 ===

<div lang="en" dir="ltr" class="mw-content-ltr">
==== UI ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Undos are performed using the ''undo'' link that appears in page history, diff view, recent changes list and other places.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Undo links point to <code>index.php?action=edit</code> with <code>undo</code> and <code>undoafter</code> parameters that specify which edits should be undone.
</div>

* <code>undo</code> – <span lang="en" dir="ltr" class="mw-content-ltr">the ID of the last revision being undone.</span>
* <code>undoafter</code> – <span lang="en" dir="ltr" class="mw-content-ltr">the ID of the last "good" revision.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The next revision will be the first revision being undone.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">See also:</span>
{{ll|Manual:Parameters to index.php#Edit and submit|2=<span lang="en" dir="ltr" class="mw-content-ltr">Manual:Parameters to index.php#Edit and submit</span>}}

<div lang="en" dir="ltr" class="mw-content-ltr">
==== API ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Undos can be performed through API using</span> <code>{{ll|API:Edit|action{{=}}edit}}</code> <span lang="en" dir="ltr" class="mw-content-ltr">with <code>undo</code> and <code>undoafter</code> parameters.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Their behavior is the same as in <code>index.php?action=edit</code>.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Mechanism ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">All revisions from <code>undoafter</code> (exclusive) to <code>undo</code> (inclusive) are reverted.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">More technically, {{ll|Manual:EditPage.php|EditPage}} applies the inverse of the diff between the <code>undoafter</code> and <code>undo</code> revisions to the current version of the page.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If that is not possible, a regular edit form is displayed and the edit is not counted as an undo.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">After that, the edit form is displayed to the user, where the resulting content can be further modified.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Since version [[Special:MyLanguage/1.36|1.36]], if the user performs any modifications to the content before saving, the edit '''is not marked as an undo'''.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is to prevent users from marking arbitrary edits as undos.</span>

{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">Undo is the only revert method that allows for reverting intermittent changes.</span> <span lang="en" dir="ltr" class="mw-content-ltr">It is also the only one that does not necessarily restore the page to a previous state.</span> <span lang="en" dir="ltr" class="mw-content-ltr"><code>undoafter</code> and <code>undo</code> can point to any revision, they don't have to be on the page the undo is being applied to.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This means that in theory an undo can be crafted for any arbitrary change to the page.</span>}}


<div lang="en" dir="ltr" class="mw-content-ltr">
==== Other content types ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If your extension implements a new [[Special:MyLanguage/Manual:ContentHandler|ContentHandler]], it can override the <code>getUndoContent</code> method in order to customize how undos are handled by your content type.
</div>

=== {{ll|1=Manual:Rollback|2=Rollback|nsp=no}} ===

<div lang="en" dir="ltr" class="mw-content-ltr">
==== UI ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Rollback can be performed using the ''rollback'' link that appears in page history, diff view, recent changes list and other places.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Rollback links point to <code>index.php?action=rollback</code> with additional parameters for ensuring the correct set of changes is being rolled back.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
See also: [[Special:MyLanguage/Manual:Parameters to index.php#rollback|Manual:Parameters to index.php#rollback]]
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== API ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Rollbacks can be performed through API using <code>[[Special:MyLanguage/API:Rollback|action=rollback]]</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Their behavior is the same as in <code>index.php?action=rollback</code>.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Mechanism ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Rollback reverts the last edits made by the last editor of the page.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is a commonly useful scenario when dealing with vandalism, as usually all changes made recently by one user should be reverted.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">When all revisions of the page are from the same user, it cannot be rolled back.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Manual revert ===
</div>
{{MW 1.36|+}}
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The software automatically infers (within limits) when an edit reverts the page to an older version.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Every time an edit is made, MediaWiki looks at a number of most recent revisions of the page (specified by <code>[[Special:MyLanguage/Manual:$wgManualRevertSearchRadius|$wgManualRevertSearchRadius]]</code>, 15 by default) and looks for the most recent revision with matching content.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The feature can be disabled entirely by setting <code>[[Special:MyLanguage/Manual:$wgManualRevertSearchRadius|$wgManualRevertSearchRadius]]</code> to zero.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Other revert types ===
</div>
For [[multi-content revisions]], there are two more index.php actions: <code>mcrundo</code> (which is the same as undo but works on all slots of the revision) and <code>mcrrestore</code> (which reverts all slots to an older revision).
<span lang="en" dir="ltr" class="mw-content-ltr">These are expected to go away once multi-content revisions are better integrated with the editing logic.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Revert tags ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">By default every revision considered a revert by MediaWiki is marked with an appropriate [[Special:MyLanguage/Manual:Tags|change tag]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Each of these tags can be individually disabled using the <code>[[Special:MyLanguage/Manual:$wgSoftwareTags|$wgSoftwareTags]]</code> configuration variable.</span>

* Undo: <code>mw-undo</code>
* Rollback: <code>mw-rollback</code>
* <span lang="en" dir="ltr" class="mw-content-ltr">Manual revert:</span> <code>mw-manual-revert</code>

<span lang="en" dir="ltr" class="mw-content-ltr">Since version [[Special:MyLanguage/1.36|1.36]] additional data about the revert is saved with each tag in the <code>ct_params</code> field of the <code>{{ll|Manual:change_tag table|change_tag}}</code>  table.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The data is the EditResult object associated with the edit (see the next section), encoded as JSON.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Accessing revert information in extensions ==
</div>
{{MW 1.35|+}}
<span lang="en" dir="ltr" class="mw-content-ltr">Version 1.35 introduced the {{class doclink|class=MediaWiki\Storage\EditResult|text=EditResult}} class that is constructed when saving an edit.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This object encapsulates information about the effects of the edit in the context of its page's history, most importantly:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">whether the edit was a revert,</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">which revert method was used,</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">what is the "base" revision for this revert,</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">which revisions were reverted.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This object is passed to extensions using the [[Manual:Hooks/PageSaveComplete|PageSaveComplete]] hook.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Reverted tag ==
</div>
{{MW 1.36|+}}
<span lang="en" dir="ltr" class="mw-content-ltr">In version 1.36 a new change tag is introduced – <code>mw-reverted</code> that is used to mark reverted edits.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Scheduling and execution ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The tag is applied in a job named <code>revertedTagUpdate</code> scheduled using the [[Special:MyLanguage/Manual:Job queue|job queue]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The job is added to the queue by [[Manual:DerivedPageDataUpdater.php|DerivedPageDataUpdater]] after the edit is saved.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">See [[Special:MyLanguage/Manual:Job queue|Manual:Job queue]] for details.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Conditions for execution ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The update will be scheduled after saving an edit if all of the following conditions are met:
</div>

* <span lang="en" dir="ltr" class="mw-content-ltr">The edit is a revert of any type recognized by MediaWiki.</span> <span lang="en" dir="ltr" class="mw-content-ltr">See [[#Revert types|#Revert types]].</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The number of reverted edits is less or equal to <code>[[Special:MyLanguage/Manual:$wgRevertedTagMaxDepth|$wgRevertedTagMaxDepth]]</code>.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The reverting revision itself is not marked as reverted or [[Special:MyLanguage/Manual:RevisionDelete|deleted]].</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The edit is considered ''auto-approved'', which can have different meanings depending on your setup:</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">If you have [[Special:MyLanguage/Help:Patrolled edits|patrolling]] enabled on your wiki through the <code>[[Special:MyLanguage/Manual:$wgUseRCPatrol|$wgUseRCPatrol]]</code> configuration variable, auto-approval is equivalent to the edit being autopatrolled.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Thus, only users with <code>autopatrol</code> user right will have their reverted tag applied right away.</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">If you have installed a content management extension such as [[Special:MyLanguage/Extension:FlaggedRevs|FlaggedRevs]] it can tell MediaWiki if the edit is auto-approved.</span> <span lang="en" dir="ltr" class="mw-content-ltr">How exactly is this determined depends on the extension.</span> <span lang="en" dir="ltr" class="mw-content-ltr">(See [[#Extension integration|#Extension integration]].)</span>

<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In case of patrolling, this happens when the edit is patrolled.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">See the next section for details on how to integrate with this feature in extensions.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">The <code>mw-reverted</code> tag will never be applied to {{ll|Manual:Null revision|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.</span><ref>
[[phab:T265312|T265312]]
</ref>

{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">Content management extensions like FlaggedRevs will generally override the behavior of the patrolling subsystem.</span>}}
{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">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).</span> <span lang="en" dir="ltr" class="mw-content-ltr">Reverts that are not patrolled will not be marked with the reverted tag.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Make sure your current configuration is suitable for your wiki.</span> <span lang="en" dir="ltr" class="mw-content-ltr">You can try disabling patrolling entirely or giving the <code>autopatrol</code> user right to a wider group of users.</span>|2=warn}}

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Extension integration ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">The first part of this is the [[Manual:Hooks/BeforeRevertedTagUpdate|BeforeRevertedTagUpdate]] hook.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">If the update was stopped, it can be later rescheduled by the extension using the <code>RevertedTagUpdateManager</code> service.</span>

; <span lang="en" dir="ltr" class="mw-content-ltr">Approving a revision :</span>

<syntaxhighlight lang="php">
$revertedTagUpdateManager = MediaWikiServices::getInstance()->getRevertedTagUpdateManager();
$revertedTagUpdateManager->approveRevertedTagForRevision( $acceptedRevisionId );
</syntaxhighlight>

{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">Nothing catastrophic will happen if you request the same update to be performed twice.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The update is idempotent.</span>}}

==== FlaggedRevs ====

<span lang="en" dir="ltr" class="mw-content-ltr">If you have installed the [[Special:MyLanguage/Extension:FlaggedRevs|FlaggedRevs extension]], the revert will be considered auto-approved if either:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">FlaggedRevs is configured to not be used on the page.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The user has the <code>autoreview</code> user right.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The edit is a self revert.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">The edit is otherwise eligible to be autoreviewed.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
If the revert was not auto-approved, it can be later approved by simply reviewing the edit.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== See also ==
</div>
* <span lang="en" dir="ltr" class="mw-content-ltr">[[Special:MyLanguage/Manual:Rollback|Manual:Rollback]]</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">[[m:Research:Revert]]</span>

[[Category:MediaWiki concepts{{#translation:}}]]