Tracking category and parser warning for deprecated uses of {{=}}

We plan to add {{=}} as a built-in parser function, expanding to `=`,
in the same way that `{{!}}` is a built-in.  It will be used to
automatically escape uses of `=` in template arguments (again, in the
same way that `{{!}}` can be used to protect uses of `|` in template
arguments).

Some wikis have non-standard definitions of `Template:=`; add a
tracking category to warn these wikis to transition before we turn on
the built-in parser function in a future release.

New parser test file added, so we can re-define Template:= and test
both cases of this new warning.

Bug: T91154
Change-Id: I50ff8a7b6be95901ebb14ffbe64940a0f499cfac

RELEASE-NOTES-1.36

@@ -139,6 +139,10 @@ because of Phabricator reports.
 === Other changes in 1.36 ===
 * The 'tidy' key in ParserOptions (used in the parser cache) has been removed.
   It has had no effect since 1.35.
+* A future release of MediaWiki will make {{=}} a built-in parser function,
+  for use when automatically escaping the `=` character in template arguments.
+  A tracking category and parser warning have been added to this release when
+  {{=}} is used and it expands to something other than `=`.
 * The implementation of TestFileReader::read has been changed to use
   Parsoid's parser test file parser.  This should be compatible with
   existing code, but it only supports version 2 of the test file

includes/TrackingCategories.php

@@ -47,6 +47,7 @@ class TrackingCategories {
 		'node-count-exceeded-category',
 		'expansion-depth-exceeded-category',
 		'restricted-displaytitle-ignored',
+		'template-equals-category',
 		'template-loop-category',
 	];
 

includes/parser/Parser.php

@@ -2970,6 +2970,8 @@ class Parser {
 
 		$profileSection = null; // profile templates
 
+		$sawDeprecatedTemplateEquals = false; // T91154
+
 		# SUBST
 		// @phan-suppress-next-line PhanRedundantCondition
 		if ( !$found ) {
@@ -3160,6 +3162,17 @@ class Parser {
 					if ( $text !== false ) {
 						$found = true;
 						$isChildObj = true;
+						if (
+							$title->getNamespace() === NS_TEMPLATE &&
+							$title->getDBkey() === '=' &&
+							$originalTitle === '='
+						) {
+							// Note that we won't get here if `=` is evaluated
+							// (in the future) as a parser function, nor if
+							// the Template namespace is given explicitly,
+							// ie `{{Template:=}}`.  Only `{{=}}` triggers.
+							$sawDeprecatedTemplateEquals = true; // T91154
+						}
 					}
 				}
 
@@ -3229,6 +3242,15 @@ class Parser {
 		if ( $profileSection ) {
 			$this->mProfiler->scopedProfileOut( $profileSection );
 		}
+		if (
+			$sawDeprecatedTemplateEquals &&
+			$this->mStripState->unstripBoth( $text ) !== '='
+		) {
+			// T91154: {{=}} is deprecated when it doesn't expand to `=`;
+			// use {{Template:=}} if you must.
+			$this->addTrackingCategory( 'template-equals-category' );
+			$this->mOutput->addWarning( wfMessage( 'template-equals-warning' )->text() );
+		}
 
 		# Replace raw HTML by a placeholder
 		if ( $isHTML ) {

languages/i18n/en.json

@@ -805,6 +805,9 @@
 	"post-expand-template-inclusion-category": "Pages where template include size is exceeded",
 	"post-expand-template-argument-warning": "<strong>Warning:</strong> This page contains at least one template argument that has a too large expansion size.\nThese arguments have been omitted.",
 	"post-expand-template-argument-category": "Pages containing omitted template arguments",
+	"template-equals-category": "Pages which use = as a template",
+	"template-equals-category-desc": "The page contains <code><nowiki>{{=}}</nowiki></code> but on this wiki that does not expand to <code>=</code>.  This usage is deprecated; a future MediaWiki version will implement <code><nowiki>{{=}}</nowiki></code> as a parser function.",
+	"template-equals-warning": "<strong>Warning:</strong> This page uses <code><nowiki>{{=}}</nowiki></code> but on this wiki that does not expand to <code>=</code>.  This usage is deprecated; a future MediaWiki version will implement <code><nowiki>{{=}}</nowiki></code> as a parser function.",
 	"parser-template-loop-warning": "Template loop detected: [[$1]]",
 	"template-loop-category": "Pages with template loops",
 	"template-loop-category-desc": "The page contains a template loop, ie. a template which calls itself recursively.",

languages/i18n/qqq.json

@@ -1021,6 +1021,9 @@
 	"post-expand-template-inclusion-category": "This message is used as a category name for a [[mw:Special:MyLanguage/Help:Tracking categories|tracking category]] where pages are placed automatically if the expanded size of the templates they contain exceeds the limit.\n\nWhen templates are expanded, there is a size limit for the number of bytes yielded. Usually that occurs from excessively nested templates, recursive templates, or ones having x-zillion of #if #case or similar contructs in them. When the wikicode parser detects this, it outputs a red warning message to the page.\n\nSee also:\n* {{msg-mw|Post-expand-template-inclusion-category-desc}}\n* {{msg-mw|Post-expand-template-inclusion-warning}}",
 	"post-expand-template-argument-warning": "Used as warning in parser limitation.\n\nSee also:\n* {{msg-mw|Post-expand-template-argument-category}}",
 	"post-expand-template-argument-category": "This message is used as a category name for a [[mw:Special:MyLanguage/Help:Tracking categories|tracking category]] where pages are placed automatically if they contain omitted template arguments.\n\nSee also:\n* {{msg-mw|Post-expand-template-argument-category-desc}}\n* {{msg-mw|Post-expand-template-argument-warning}}",
+	"template-equals-category": "This message is used as a category name for a [[mw:Special:MyLanguage/Help:Tracking categories|tracking category]] where pages with deprecated uses of <code><nowiki>{{=}}</nowiki></code> will be listed.",
+	"template-equals-category-desc": "Pages with deprecated uses of <code><nowiki>{{=}}</nowiki></code> category description. Shown on [[Special:TrackingCategories]].\n\nSee also:\n* {{msg-mw|Template-equals-category}}",
+	"template-equals-warning": "This message is displayed in edit preview when a deprecated use of <code><nowiki>{{=}}</nowiki></code> is detected on the previewed page.",
 	"parser-template-loop-warning": "Parameters:\n* $1 - page title",
 	"template-loop-category": "This message is used as a category name for a [[mw:Special:MyLanguage/Help:Tracking categories|tracking category]] where pages with template loops will be listed.",
 	"template-loop-category-desc": "Pages with template loops category description. Shown on [[Special:TrackingCategories]].\n\nSee also:\n* {{msg-mw|Template-loop-category}}",

tests/parser/ParserTestRunner.php

@@ -49,6 +49,7 @@ class ParserTestRunner {
 	 */
 	private static $coreTestFiles = [
 		'parserTests.txt',
+		'pfeqParserTests.txt',
 		'extraParserTests.txt',
 	];
 

tests/parser/parserTests.txt

@@ -26206,6 +26206,30 @@ Special:Foobar
 </p>
 !! end
 
+# {{=}} will be converted to a parser function which expands to `=`
+# If you have it defined as a Template that expands to `=` that's ok;
+# and using it explicitly as {{Template:=}} (regardless of what it
+# expands to) is also ok and will not generate a tracking category.
+# T91154
+!! test
+Using {{=}} when it expands to "=" should not create a tracking category
+!! wikitext
+This uses {{=}} and {{Template:=}}.
+!! html
+<p>This uses = and =.
+</p>
+!! end
+
+# Repeat the test, looking at categories.  Note: none should be emitted!
+!! test
+Using {{=}} when it expands to "=" should not create a tracking category (cat)
+!! options
+cat
+!! wikitext
+This uses {{=}} and {{Template:=}}.
+!! html/php
+!! end
+
 !!test
 T36939 - Case insensitive link parsing ([HttP://])
 !! wikitext

tests/parser/pfeqParserTests.txt

@@ -0,0 +1,30 @@
+!! Version 2
+!! article
+Template:=
+!! text
+no
+!! endarticle
+
+# {{=}} will be converted to a parser function which expands to `=`
+# If you have it defined as a Template that expands to something other
+# than `=` that will generate a warning and a tracking category, although
+# referencing the template explicitly as {{Template:=}} is fine
+# regardless of what it expands to. (T91154)
+!! test
+Using {{=}} when that doesn't expand to "=" should create a tracking category
+!! options
+cat
+!! wikitext
+This uses {{=}}.
+!! html/php
+cat=Pages_which_use_=_as_a_template sort=
+!! end
+
+!! test
+Using {{Template:=}} shouldn't create tracking category regardless of definition
+!! options
+cat
+!! wikitext
+This uses {{Template:=}}.
+!! html/php
+!! end