From 12490340ff549d4dcdca01baf6e075f1da0f2baa Mon Sep 17 00:00:00 2001
From: Reedy <reedy@wikimedia.org>
Date: Thu, 7 Nov 2024 00:11:30 +0000
Subject: [PATCH] Attempt to more consistently document $wg values in
 extension.json and README

Change-Id: I83ae3dc8a2bd1d9e4655eba1d8da5e5974930357
---
 README.md      | 32 +++++++++++++++++++++++++++-----
 extension.json | 11 +++++++++++
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9a3da0b5c..e026da6dc 100644
--- a/README.md
+++ b/README.md
@@ -101,12 +101,12 @@ $wgCaptchaStorageClass = 'MediaWiki\Extension\ConfirmEdit\Store\CaptchaSessionSt
  * Number of seconds a captcha session should last in the data cache
  * before expiring when managing through CaptchaCacheStore class.
  *
- * Default is a half hour.
+ * Default is a half-hour.
  */
 $wgCaptchaSessionExpiration = 30 * 60;
 
 /**
- * Number of seconds after a bad login that a captcha will be shown to
+ * Number of seconds after a bad login (from a specific IP address) that a captcha will be shown to
  * that client on the login form to slow down password-guessing bots.
  *
  * Has no effect if 'badlogin' is disabled in $wgCaptchaTriggers or
@@ -116,9 +116,20 @@ $wgCaptchaSessionExpiration = 30 * 60;
  */
 $wgCaptchaBadLoginExpiration = 5 * 60;
 
+/**
+ * Number of seconds after a bad login (for a specific user account) that a captcha will be shown to
+ * that client on the login form to slow down password-guessing bots.
+ *
+ * Has no effect if 'badlogin' is disabled in $wgCaptchaTriggers or
+ * if there is not a caching engine enabled.
+ *
+ * Default is 10 minutes
+ */
+$wgCaptchaBadLoginPerUserExpiration = 10 * 60;
+
 /**
  * Allow users who have confirmed their email addresses to post
- * URL links without being harassed by the captcha.
+ * URL links without being shown a captcha.
  *
  * @deprecated since 1.36
  * $wgGroupPermissions['emailconfirmed']['skipcaptcha'] = true; should be used instead.
@@ -126,11 +137,17 @@ $wgCaptchaBadLoginExpiration = 5 * 60;
 $wgAllowConfirmedEmail = false;
 
 /**
- * Number of bad login attempts before triggering the captcha.  0 means the
+ * Number of bad login attempts (from a specific IP address) before triggering the captcha. 0 means the
  * captcha is presented on the first login.
  */
 $wgCaptchaBadLoginAttempts = 3;
 
+/**
+ * Number of bad login attempts (for a specific user account) before triggering the captcha. 0 means the
+ * captcha is presented on the first login.
+ */
+$wgCaptchaBadLoginPerUserAttempts = 20;
+
 /**
  * Regex to ignore URLs to known-good sites...
  * For instance:
@@ -144,9 +161,14 @@ $wgCaptchaIgnoredUrls = false;
  * other than URLs such as junk edits.
  *
  * If the new version matches one and the old version doesn't,
- * toss up the captcha screen.
+ * show the captcha screen.
  *
  * @fixme Add a message for local admins to add items as well.
  */
 $wgCaptchaRegexes = [];
+
+/**
+ * Feature flag to toggle list of available custom actions to enable in AbuseFilter. See AbuseFilterHooks::onAbuseFilterCustomActions
+ */
+$wgConfirmEditEnabledAbuseFilterCustomActions = [];
 ```
diff --git a/extension.json b/extension.json
index 234e0a9cb..d8181ce66 100644
--- a/extension.json
+++ b/extension.json
@@ -127,9 +127,11 @@
 			"value": false
 		},
 		"Captcha": {
+			"description": "Captcha class to be used; when enabling sub extensions (ie FancyCaptcha) this will be set for you",
 			"value": null
 		},
 		"CaptchaTriggers": {
+			"description": "Actions which can trigger a captcha",
 			"value": {
 				"edit": false,
 				"create": false,
@@ -142,28 +144,36 @@
 			"merge_strategy": "array_plus"
 		},
 		"CaptchaTriggersOnNamespace": {
+			"description": "Allows forcing/turning off Captcha in specific namespaces",
 			"value": {},
 			"merge_strategy": "array_plus_2d"
 		},
 		"CaptchaStorageClass": {
+			"description": "PHP class used for storing Captcha related session data",
 			"value": "MediaWiki\\Extension\\ConfirmEdit\\Store\\CaptchaSessionStore"
 		},
 		"CaptchaSessionExpiration": {
+			"description": "Number of seconds a captcha session should last in the data cache before expiring when managing through CaptchaCacheStore class.",
 			"value": 1800
 		},
 		"CaptchaBadLoginExpiration": {
+			"description": "Number of seconds after a bad login (from a specific IP address) that a captcha will be shown to that client on the login form to slow down password-guessing bots.",
 			"value": 300
 		},
 		"CaptchaBadLoginPerUserExpiration": {
+			"description": "Number of seconds after a bad login (for a specific user account) that a captcha will be shown to that client on the login form to slow down password-guessing bots.",
 			"value": 600
 		},
 		"AllowConfirmedEmail": {
+			"description": "Allow users who have confirmed their email addresses to post URL links without being shown a captcha.",
 			"value": false
 		},
 		"CaptchaBadLoginAttempts": {
+			"description": "Number of bad login attempts (from a specific IP address) before triggering the captcha. 0 means the captcha is presented on the first login.",
 			"value": 3
 		},
 		"CaptchaBadLoginPerUserAttempts": {
+			"description": "Number of bad login attempts (for a specific user account) before triggering the captcha. 0 means the captcha is presented on the first login.",
 			"value": 20
 		},
 		"CaptchaWhitelist": {
@@ -175,6 +185,7 @@
 			"value": false
 		},
 		"CaptchaRegexes": {
+			"description": "Additional regexes to check for. Use full regexes; can match things other than URLs such as junk edits. If the new version matches one and the old version doesn't, show the captcha screen.",
 			"value": []
 		},
 		"ConfirmEditEnabledAbuseFilterCustomActions": {