From 76e7016993d74e1062e1e1c2a6afdd5941635084 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Bartosz=20Dziewo=C5=84ski?= <matma.rex@gmail.com>
Date: Fri, 17 Aug 2018 23:04:57 +0200
Subject: [PATCH] HTMLForm: Deprecate parameters 'notice', 'notice-messages',
 'notice-message'

Bug: T197179
Change-Id: I603436e0720fdc0f08f35f3c0630b79865a9c82a
---
 RELEASE-NOTES-1.32                  |  4 ++++
 includes/htmlform/HTMLForm.php      |  8 +++-----
 includes/htmlform/HTMLFormField.php | 21 +++++++++++++++++++--
 3 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/RELEASE-NOTES-1.32 b/RELEASE-NOTES-1.32
index c765fc1386..7ab2134e28 100644
--- a/RELEASE-NOTES-1.32
+++ b/RELEASE-NOTES-1.32
@@ -398,6 +398,10 @@ because of Phabricator reports.
   mw.user.getPageviewToken to better capture its function.
 * Passing Revision objects to ContentHandler::getUndoContent() is deprecated,
   Content object should be passed instead.
+* (T197179) Parameters 'notice', 'notice-messages', 'notice-message',
+  previously used by OOUI HTMLForm fields, are now deprecated. Use
+  'help', 'help-message', 'help-messages' instead.
+* (T197179) HTMLFormField::getNotices() is now deprecated.
 
 === Other changes in 1.32 ===
 * (T198811) The following tables have had their UNIQUE indexes turned into
diff --git a/includes/htmlform/HTMLForm.php b/includes/htmlform/HTMLForm.php
index 43c9ee05d6..8e7845914f 100644
--- a/includes/htmlform/HTMLForm.php
+++ b/includes/htmlform/HTMLForm.php
@@ -81,11 +81,9 @@ use Wikimedia\ObjectFactory;
  *    '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.
- *    'notice'              -- message text for a message to use as a notice in the field.
- *                             Currently used by OOUI form fields only.
- *    'notice-messages'     -- array of message keys/objects to use for notice.
- *                             Overrides 'notice'.
- *    'notice-message'      -- message key or object to use as a notice.
+ *    'notice'              -- (deprecated, use 'help' instead)
+ *    'notice-messages'     -- (deprecated, use 'help-messages' instead)
+ *    'notice-message'      -- (deprecated, use 'help-message' instead)
  *    'required'            -- passed through to the object, indicating that it
  *                             is a required field.
  *    'size'                -- the length of text fields
diff --git a/includes/htmlform/HTMLFormField.php b/includes/htmlform/HTMLFormField.php
index f5d6e8cbb5..bd08da0e22 100644
--- a/includes/htmlform/HTMLFormField.php
+++ b/includes/htmlform/HTMLFormField.php
@@ -462,6 +462,16 @@ abstract class HTMLFormField {
 		if ( isset( $params['hide-if'] ) ) {
 			$this->mHideIf = $params['hide-if'];
 		}
+
+		if ( isset( $this->mParams['notice-message'] ) ) {
+			wfDeprecated( "'notice-message' parameter in HTMLForm", '1.32' );
+		}
+		if ( isset( $this->mParams['notice-messages'] ) ) {
+			wfDeprecated( "'notice-messages' parameter in HTMLForm", '1.32' );
+		}
+		if ( isset( $this->mParams['notice'] ) ) {
+			wfDeprecated( "'notice' parameter in HTMLForm", '1.32' );
+		}
 	}
 
 	/**
@@ -607,7 +617,7 @@ abstract class HTMLFormField {
 			$error = new OOUI\HtmlSnippet( $error );
 		}
 
-		$notices = $this->getNotices();
+		$notices = $this->getNotices( 'skip deprecation' );
 		foreach ( $notices as &$notice ) {
 			$notice = new OOUI\HtmlSnippet( $notice );
 		}
@@ -915,9 +925,16 @@ abstract class HTMLFormField {
 	 * Determine notices to display for the field.
 	 *
 	 * @since 1.28
+	 * @deprecated since 1.32
+	 * @param string $skipDeprecation Pass 'skip deprecation' to avoid the deprecation
+	 *   warning (since 1.32)
 	 * @return string[]
 	 */
-	public function getNotices() {
+	public function getNotices( $skipDeprecation = null ) {
+		if ( $skipDeprecation !== 'skip deprecation' ) {
+			wfDeprecated( __METHOD__, '1.32' );
+		}
+
 		$notices = [];
 
 		if ( isset( $this->mParams['notice-message'] ) ) {
-- 
2.20.1