Merge "Deprecate User::getPasswordValidity()"

diff --combined RELEASE-NOTES-1.33
index 96ca382,7567252..f357aae
--- 1/RELEASE-NOTES-1.33
--- 2/RELEASE-NOTES-1.33
+++ b/RELEASE-NOTES-1.33
@@@ -75,9 -75,7 +75,9 @@@ production
      exceptions will now include the "Wikimedia\Rdbms\" prefix in the class name.
    * The code including an exception class name is deprecated. In the future,
      all internal errors will use code "internal_api_error".
 -* …
 +* (T212356) When using action=delete on pages with many revisions, the module
 +  may return a boolean-true 'scheduled' and no 'logid'. This signifies that the
 +  deletion will be processed via the job queue.
  
  === Action API internal changes in 1.33 ===
  * A number of deprecated methods for API documentation, intended for overriding
@@@ -191,13 -189,13 +191,15 @@@ because of Phabricator reports
    domain ID as a key component and use makeGlobalKey().
  * (T202094) Title::getUserCaseDBKey() is deprecated; instead, please use
    Title::getDBKey(), which doesn't vary case.
+ * User::getPasswordValidity() is now deprecated. User::checkPasswordValidity()
+   returns the same information in a more useful format.
  * …
  
  === Other changes in 1.33 ===
  * (T208871) The hard-coded Google search form on the database error page was
    removed.
 +* (T201747) Html::openElement() warns if given an element name wiht a space
 +  in it.
  * …
  
  == Compatibility ==

diff --combined includes/DefaultSettings.php
index 36b4d1e,c76b8c1..420da4f
--- 1/includes/DefaultSettings.php
--- 2/includes/DefaultSettings.php
+++ b/includes/DefaultSettings.php
@@@ -4451,29 -4451,49 +4451,49 @@@ $wgCentralIdLookupProviders = 
  $wgCentralIdLookupProvider = 'local';
  
  /**
-  * Password policy for local wiki users. A user's effective policy
-  * is the superset of all policy statements from the policies for the
-  * groups where the user is a member. If more than one group policy
-  * include the same policy statement, the value is the max() of the
-  * values. Note true > false. The 'default' policy group is required,
-  * and serves as the minimum policy for all users. New statements can
-  * be added by appending to $wgPasswordPolicy['checks'].
-  * Statements:
-  *    - MinimalPasswordLength - minimum length a user can set
-  *    - MinimumPasswordLengthToLogin - passwords shorter than this will
+  * Password policy for the wiki.
+  * Structured as
+  * [
+  *     'policies' => [ <group> => [ <policy> => <value>, ... ], ... ],
+  *     'checks' => [ <policy> => <callback>, ... ],
+  * ]
+  * where <group> is a user group, <policy> is a password policy name
+  * (arbitrary string) defined in the 'checks' part, <callback> is the
+  * PHP callable implementing the policy check, <value> is a number,
+  * boolean or null that gets passed to the callback.
+  *
+  * A user's effective policy is the superset of all policy statements
+  * from the policies for the groups where the user is a member. If more
+  * than one group policy include the same policy statement, the value is
+  * the max() of the values. Note true > false. The 'default' policy group
+  * is required, and serves as the minimum policy for all users.
+  *
+  * Callbacks receive three arguments: the policy value, the User object
+  * and the password; and must return a StatusValue. A non-good status
+  * means the password will not be accepted for new accounts, and existing
+  * accounts will be prompted for password change or barred from logging in
+  * (depending on whether the status is a fatal or merely error/warning).
+  *
+  * The checks supported by core are:
+  *    - MinimalPasswordLength - Minimum length a user can set.
+  *    - MinimumPasswordLengthToLogin - Passwords shorter than this will
   *            not be allowed to login, regardless if it is correct.
   *    - MaximalPasswordLength - maximum length password a user is allowed
   *            to attempt. Prevents DoS attacks with pbkdf2.
-  *    - PasswordCannotMatchUsername - Password cannot match username to
+  *    - PasswordCannotMatchUsername - Password cannot match the username.
   *    - PasswordCannotMatchBlacklist - Username/password combination cannot
-  *            match a specific, hardcoded blacklist.
+  *            match a blacklist of default passwords used by MediaWiki in the past.
   *    - PasswordCannotBePopular - Blacklist passwords which are known to be
   *            commonly chosen. Set to integer n to ban the top n passwords.
   *            If you want to ban all common passwords on file, use the
   *            PHP_INT_MAX constant.
   *    - PasswordNotInLargeBlacklist - Password not in best practices list of
-  *            100,000 commonly used passwords.
+  *            100,000 commonly used passwords. Due to the size of the list this
+  *      is a probabilistic test.
+  *
   * @since 1.26
+  * @see PasswordPolicyChecks
+  * @see User::checkPasswordValidity()
   */
  $wgPasswordPolicy = [
        'policies' => [
@@@ -5820,7 -5840,6 +5840,7 @@@ $wgGrantPermissions['editmycssjs']['edi
  $wgGrantPermissions['editmycssjs']['editmyuserjs'] = true;
  
  $wgGrantPermissions['editmyoptions']['editmyoptions'] = true;
 +$wgGrantPermissions['editmyoptions']['editmyuserjson'] = true;
  
  $wgGrantPermissions['editinterface'] = $wgGrantPermissions['editpage'];
  $wgGrantPermissions['editinterface']['editinterface'] = true;