Deprecate the 'help' key in form descriptors in favor of 'help-raw'

This new key name should better signal to developers that this key
will be used as-is without escaping

Bug: T356971
Change-Id: I98849b2e45cc4555eca7674875b9bed89f128310

2 files changed, 6 insertions, 3 deletions

diff --git a/includes/htmlform/HTMLForm.php b/includes/htmlform/HTMLForm.php
index b14fb5cdb4dc..5f79adbb092a 100644
--- a/includes/htmlform/HTMLForm.php
+++ b/includes/htmlform/HTMLForm.php
@@ -129,14 +129,14 @@ use Wikimedia\Message\MessageSpecifier;
  *                             the message.
  *    'label'               -- alternatively, a raw text message. Overridden by
  *                             label-message
- *    'help'                -- message text for a message to use as a help text.
+ *    'help-raw'            -- message text for a message to use as a help text.
  *    'help-message'        -- message key or object for a message to use as a help text.
  *                             can be an array of msg key and then parameters to
  *                             the message.
- *                             Overwrites 'help-messages' and 'help'.
+ *                             Overwrites 'help-messages' and 'help-raw'.
  *    'help-messages'       -- array of message keys/objects. As above, each item can
  *                             be an array of msg key and then parameters.
- *                             Overwrites 'help'.
+ *                             Overwrites 'help-raw'.
  *    'help-inline'         -- Whether help text (defined using options above) will be shown
  *                             inline after the input field, rather than in a popup.
  *                             Defaults to true. Only used by OOUI form fields.
diff --git a/includes/htmlform/HTMLFormField.php b/includes/htmlform/HTMLFormField.php
index e35ccbeecdca..b0b97ef858f2 100644
--- a/includes/htmlform/HTMLFormField.php
+++ b/includes/htmlform/HTMLFormField.php
@@ -1056,7 +1056,10 @@ abstract class HTMLFormField {
 			return [ $this->mParams['help-message'] ];
 		} elseif ( isset( $this->mParams['help-messages'] ) ) {
 			return $this->mParams['help-messages'];
+		} elseif ( isset( $this->mParams['help-raw'] ) ) {
+			return [ new HtmlArmor( $this->mParams['help-raw'] ) ];
 		} elseif ( isset( $this->mParams['help'] ) ) {
+			// @deprecated since 1.43, use 'help-raw' key instead
 			return [ new HtmlArmor( $this->mParams['help'] ) ];
 		}