Merge "Make the documentation of change tags easier to access"

includes/DefaultSettings.php

@@ -7474,21 +7474,20 @@ $wgDisableAnonTalk = false;
 $wgUseTagFilter = true;
 
 /**
- * List of core tags to enable. Available tags are:
- * - 'mw-contentmodelchange': Edit changes content model of a page
- * - 'mw-new-redirect': Edit makes new redirect page (new page or by changing content page)
- * - 'mw-removed-redirect': Edit changes an existing redirect into a non-redirect
- * - 'mw-changed-redirect-target': Edit changes redirect target
- * - 'mw-blank': Edit completely blanks the page
- * - 'mw-replace': Edit removes more than 90% of the content
- * - 'mw-rollback': Edit is a rollback, made through the rollback link or rollback API
- * - 'mw-undo': Edit made through an undo link
- * - 'mw-manual-revert': Edit that restored the page to an exact previous state
- * - 'mw-reverted': Edit that was later reverted by another edit
- *
+ * List of core tags to enable.
  * @var array
  * @since 1.31
  * @since 1.36 Added 'mw-manual-revert' and 'mw-reverted'
+ * @see ChangeTags::TAG_CONTENT_MODEL_CHANGE
+ * @see ChangeTags::TAG_NEW_REDIRECT
+ * @see ChangeTags::TAG_REMOVED_REDIRECT
+ * @see ChangeTags::TAG_CHANGED_REDIRECT_TARGET
+ * @see ChangeTags::TAG_BLANK
+ * @see ChangeTags::TAG_REPLACE
+ * @see ChangeTags::TAG_ROLLBACK
+ * @see ChangeTags::TAG_UNDO
+ * @see ChangeTags::TAG_MANUAL_REVERT
+ * @see ChangeTags::TAG_REVERTED
  */
 $wgSoftwareTags = [
 	'mw-contentmodelchange' => true,

includes/Rest/Handler/PageHistoryCountHandler.php

@@ -2,6 +2,7 @@
 
 namespace MediaWiki\Rest\Handler;
 
+use ChangeTags;
 use MediaWiki\Permissions\PermissionManager;
 use MediaWiki\Rest\LocalizedHttpException;
 use MediaWiki\Rest\Response;
@@ -43,8 +44,6 @@ class PageHistoryCountHandler extends SimpleHandler {
 
 	private const MAX_AGE_200 = 60;
 
-	private const REVERTED_TAG_NAMES = [ 'mw-undo', 'mw-rollback', 'mw-manual-revert' ];
-
 	/** @var RevisionStore */
 	private $revisionStore;
 
@@ -531,7 +530,7 @@ class PageHistoryCountHandler extends SimpleHandler {
 	protected function getRevertedCount( $pageId, RevisionRecord $fromRev = null ) {
 		$tagIds = [];
 
-		foreach ( self::REVERTED_TAG_NAMES as $tagName ) {
+		foreach ( ChangeTags::REVERT_TAGS as $tagName ) {
 			try {
 				$tagIds[] = $this->changeTagDefStore->getId( $tagName );
 			} catch ( NameTableAccessException $e ) {

includes/Rest/Handler/PageHistoryHandler.php

@@ -2,6 +2,7 @@
 
 namespace MediaWiki\Rest\Handler;
 
+use ChangeTags;
 use IDBAccessObject;
 use MediaWiki\Permissions\PermissionManager;
 use MediaWiki\Rest\LocalizedHttpException;
@@ -27,7 +28,6 @@ use Wikimedia\Rdbms\IResultWrapper;
  */
 class PageHistoryHandler extends SimpleHandler {
 	private const REVISIONS_RETURN_LIMIT = 20;
-	private const REVERTED_TAG_NAMES = [ 'mw-undo', 'mw-rollback', 'mw-manual-revert' ];
 	private const ALLOWED_FILTER_TYPES = [ 'anonymous', 'bot', 'reverted', 'minor' ];
 
 	/** @var RevisionStore */
@@ -108,7 +108,7 @@ class PageHistoryHandler extends SimpleHandler {
 
 		$tagIds = [];
 		if ( $params['filter'] === 'reverted' ) {
-			foreach ( self::REVERTED_TAG_NAMES as $tagName ) {
+			foreach ( ChangeTags::REVERT_TAGS as $tagName ) {
 				try {
 					$tagIds[] = $this->changeTagDefStore->getId( $tagName );
 				} catch ( NameTableAccessException $exception ) {

includes/Storage/RevertedTagUpdate.php

@@ -45,8 +45,6 @@ class RevertedTagUpdate implements DeferrableUpdate {
 	 */
 	public const CONSTRUCTOR_OPTIONS = [ 'RevertedTagMaxDepth' ];
 
-	private const REVERTED_TAG = 'mw-reverted';
-
 	/** @var RevisionStore */
 	private $revisionStore;
 
@@ -177,7 +175,7 @@ class RevertedTagUpdate implements DeferrableUpdate {
 	 */
 	private function shouldExecute() : bool {
 		$maxDepth = $this->options->get( 'RevertedTagMaxDepth' );
-		if ( !in_array( self::REVERTED_TAG, $this->softwareTags ) || $maxDepth <= 0 ) {
+		if ( !in_array( ChangeTags::TAG_REVERTED, $this->softwareTags ) || $maxDepth <= 0 ) {
 			return false;
 		}
 
@@ -230,7 +228,7 @@ class RevertedTagUpdate implements DeferrableUpdate {
 		}
 
 		$changeTagsOnRevert = $this->getChangeTags( $this->revertId );
-		if ( in_array( self::REVERTED_TAG, $changeTagsOnRevert ) ) {
+		if ( in_array( ChangeTags::TAG_REVERTED, $changeTagsOnRevert ) ) {
 			// This is already marked as reverted, which means the update was delayed
 			// until the edit is approved. Apparently, the edit was not approved, as
 			// it was reverted, so the update should not be performed.
@@ -300,7 +298,7 @@ class RevertedTagUpdate implements DeferrableUpdate {
 	 */
 	protected function markAsReverted( int $revisionId, array $extraParams ) {
 		ChangeTags::addTags(
-			[ self::REVERTED_TAG ],
+			[ ChangeTags::TAG_REVERTED ],
 			null,
 			$revisionId,
 			null,

includes/changetags/ChangeTags.php

@@ -29,17 +29,77 @@ use Wikimedia\Rdbms\IDatabase;
 
 class ChangeTags {
 	/**
-	 * Can't delete tags with more than this many uses. Similar in intent to
-	 * the bigdelete user right
-	 * @todo Use the job queue for tag deletion to avoid this restriction
+	 * The tagged edit changes the content model of the page.
 	 */
-	private const MAX_DELETE_USES = 5000;
+	public const TAG_CONTENT_MODEL_CHANGE = 'mw-contentmodelchange';
+	/**
+	 * The tagged edit creates a new redirect (either by creating a new page or turning an
+	 * existing page into a redirect).
+	 */
+	public const TAG_NEW_REDIRECT = 'mw-new-redirect';
+	/**
+	 * The tagged edit turns a redirect page into a non-redirect.
+	 */
+	public const TAG_REMOVED_REDIRECT = 'mw-removed-redirect';
+	/**
+	 * The tagged edit changes the target of a redirect page.
+	 */
+	public const TAG_CHANGED_REDIRECT_TARGET = 'mw-changed-redirect-target';
+	/**
+	 * The tagged edit blanks the page (replaces it with the empty string).
+	 */
+	public const TAG_BLANK = 'mw-blank';
+	/**
+	 * The tagged edit removes more than 90% of the content of the page.
+	 */
+	public const TAG_REPLACE = 'mw-replace';
+	/**
+	 * The tagged edit is a rollback (undoes the previous edit and all immediately preceding edits
+	 * by the same user, and was performed via the "rollback" link available to advanced users
+	 * or via the rollback API).
+	 *
+	 * The associated tag data is a JSON containing the edit result (see EditResult::jsonSerialize()).
+	 */
+	public const TAG_ROLLBACK = 'mw-rollback';
+	/**
+	 * The tagged edit is was performed via the "undo" link. (Usually this means that it undoes
+	 * some previous edit, but the undo workflow includes an edit step so it could be anything.)
+	 *
+	 * The associated tag data is a JSON containing the edit result (see EditResult::jsonSerialize()).
+	 */
+	public const TAG_UNDO = 'mw-undo';
+	/**
+	 * The tagged edit restores the page to an earlier revision.
+	 *
+	 * The associated tag data is a JSON containing the edit result (see EditResult::jsonSerialize()).
+	 */
+	public const TAG_MANUAL_REVERT = 'mw-manual-revert';
+	/**
+	 * The tagged edit is reverted by a subsequent edit (which is tagged by one of TAG_ROLLBACK,
+	 * TAG_UNDO, TAG_MANUAL_REVERT). Multiple edits might be reverted by the same edit.
+	 *
+	 * The associated tag data is a JSON containing the edit result (see EditResult::jsonSerialize())
+	 * with an extra 'revertId' field containing the revision ID of the reverting edit.
+	 */
+	public const TAG_REVERTED = 'mw-reverted';
+
+	/**
+	 * List of tags which denote a revert of some sort. (See also TAG_REVERTED.)
+	 */
+	public const REVERT_TAGS = [ self::TAG_ROLLBACK, self::TAG_UNDO, self::TAG_MANUAL_REVERT ];
 
 	/**
 	 * Flag for canDeleteTag().
 	 */
 	public const BYPASS_MAX_USAGE_CHECK = 1;
 
+	/**
+	 * Can't delete tags with more than this many uses. Similar in intent to
+	 * the bigdelete user right
+	 * @todo Use the job queue for tag deletion to avoid this restriction
+	 */
+	private const MAX_DELETE_USES = 5000;
+
 	/**
 	 * A list of tags defined and used by MediaWiki itself.
 	 */