jenkins-bot has submitted this change and it was merged. (
https://gerrit.wikimedia.org/r/331419 )
Change subject: API: Add reference to the mailing list in errors and
deprecation warnings
......................................................................
API: Add reference to the mailing list in errors and deprecation warnings
This was suggested at a Developer Summit session as a way to get people
to know about the mailing list.
This also adds a hook so ApiFeatureUsage can mention itself in
deprecation warnings too.
Bug: T148855
Change-Id: I04a7cf89e87e48f6504803dd173e779017a205d0
---
M docs/hooks.txt
M includes/api/ApiBase.php
M includes/api/ApiMain.php
M includes/api/i18n/en.json
M includes/api/i18n/qqq.json
M tests/phpunit/includes/api/ApiMainTest.php
6 files changed, 30 insertions(+), 3 deletions(-)
Approvals:
Umherirrender: Looks good to me, but someone else must approve
Legoktm: Looks good to me, approved
jenkins-bot: Verified
diff --git a/docs/hooks.txt b/docs/hooks.txt
index 1da39cf..ec09ea9 100644
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -365,6 +365,11 @@
* 1.27+: IApiMessage, or a key or key+parameters in ApiBase::$messageMap.
* Earlier: A key or key+parameters in ApiBase::$messageMap.
+'ApiDeprecationHelp': Add messages to the 'deprecation-help' warning generated
+from ApiBase::addDeprecation().
+&$msgs: Message[] Messages to include in the help. Multiple messages will be
+ joined with spaces.
+
'APIEditBeforeSave': DEPRECATED! Use EditFilterMergedContent instead.
Before saving a page with api.php?action=edit, after
processing request parameters. Return false to let the request fail, returning
diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index b8dd464..e249810 100644
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -1718,6 +1718,18 @@
$this->logFeatureUsage( $feature );
}
$this->addWarning( $msg, 'deprecation', $data );
+
+ // No real need to deduplicate here, ApiErrorFormatter does
that for
+ // us (assuming the hook is deterministic).
+ $msgs = [ $this->msg( 'api-usage-mailinglist-ref' ) ];
+ Hooks::run( 'ApiDeprecationHelp', [ &$msgs ] );
+ if ( count( $msgs ) > 1 ) {
+ $key = '$' . join( ' $', range( 1, count( $msgs ) ) );
+ $msg = ( new RawMessage( $key ) )->params( $msgs );
+ } else {
+ $msg = reset( $msgs );
+ }
+ $this->getMain()->addWarning( $msg, 'deprecation-help' );
}
/**
diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php
index 52f1d95..59227d9 100644
--- a/includes/api/ApiMain.php
+++ b/includes/api/ApiMain.php
@@ -1109,7 +1109,11 @@
$result->addContentValue(
$path,
'docref',
- $this->msg( 'api-usage-docref', $link
)->inLanguage( $formatter->getLanguage() )->text()
+ trim(
+ $this->msg( 'api-usage-docref', $link
)->inLanguage( $formatter->getLanguage() )->text()
+ . ' '
+ . $this->msg(
'api-usage-mailinglist-ref' )->inLanguage( $formatter->getLanguage() )->text()
+ )
);
} else {
if ( $config->get( 'ShowExceptionDetails' ) ) {
diff --git a/includes/api/i18n/en.json b/includes/api/i18n/en.json
index 8ac11d0..9e74beb 100644
--- a/includes/api/i18n/en.json
+++ b/includes/api/i18n/en.json
@@ -1795,6 +1795,7 @@
"api-feed-error-title": "Error ($1)",
"api-usage-docref": "See $1 for API usage.",
+ "api-usage-mailinglist-ref": "Subscribe to the mediawiki-api-announce
mailing list at
<https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce> for
notice of API deprecations and breaking changes.",
"api-exception-trace": "$1 at $2($3)\n$4",
"api-credits-header": "Credits",
"api-credits": "API developers:\n* Yuri Astrakhan (creator, lead
developer Sep 2006–Sep 2007)\n* Roan Kattouw (lead developer Sep 2007–2009)\n*
Victor Vasiliev\n* Bryan Tong Minh\n* Sam Reed\n* Brad Jorsch (lead developer
2013–present)\n\nPlease send your comments, suggestions and questions to
[email protected]\nor file a bug report at
https://phabricator.wikimedia.org/.";
diff --git a/includes/api/i18n/qqq.json b/includes/api/i18n/qqq.json
index 85e24e4..08e5437 100644
--- a/includes/api/i18n/qqq.json
+++ b/includes/api/i18n/qqq.json
@@ -1685,6 +1685,7 @@
"apiwarn-wgDebugAPI": "{{doc-apierror}}",
"api-feed-error-title": "Used as a feed item title when an error occurs
in <kbd>action=feedwatchlist</kbd>.\n\nParameters:\n* $1 - API error
code\n{{Identical|Error}}",
"api-usage-docref": "\n\nParameters:\n* $1 - URL of the API
auto-generated documentation.",
+ "api-usage-mailinglist-ref": "{{doc-apierror}} Also used in the error
response.",
"api-exception-trace": "\n\nParameters:\n* $1 - Exception class.\n* $2
- File from which the exception was thrown.\n* $3 - Line number from which the
exception was thrown.\n* $4 - Exception backtrace.",
"api-credits-header": "Header for the API credits section in the API
help output\n{{Identical|Credit}}",
"api-credits": "API credits text, displayed in the API help output"
diff --git a/tests/phpunit/includes/api/ApiMainTest.php
b/tests/phpunit/includes/api/ApiMainTest.php
index 71dafce..eff41e3 100644
--- a/tests/phpunit/includes/api/ApiMainTest.php
+++ b/tests/phpunit/includes/api/ApiMainTest.php
@@ -546,7 +546,9 @@
[ 'code' => 'existing-error',
'text' => 'existing error', 'module' => 'main' ],
[ 'code' => 'ue', 'text' =>
"Usage exception!", 'data' => [ 'foo' => 'bar' ] ]
],
- 'docref' => "See $doclink for API
usage.",
+ 'docref' => "See $doclink for API
usage. Subscribe to the mediawiki-api-announce mailing " .
+ "list at
<https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce> " .
+ "for notice of API deprecations
and breaking changes.",
'servedby' => wfHostname(),
]
],
@@ -564,7 +566,9 @@
[ 'code' => 'sv-error1', 'text'
=> 'An error', 'module' => 'foo+bar' ],
[ 'code' => 'sv-error2', 'text'
=> 'Another error', 'module' => 'foo+bar' ],
],
- 'docref' => "See $doclink for API
usage.",
+ 'docref' => "See $doclink for API
usage. Subscribe to the mediawiki-api-announce mailing " .
+ "list at
<https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce> " .
+ "for notice of API deprecations
and breaking changes.",
'servedby' => wfHostname(),
]
],
--
To view, visit https://gerrit.wikimedia.org/r/331419
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I04a7cf89e87e48f6504803dd173e779017a205d0
Gerrit-PatchSet: 5
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Anomie <[email protected]>
Gerrit-Reviewer: Anomie <[email protected]>
Gerrit-Reviewer: Gergő Tisza <[email protected]>
Gerrit-Reviewer: Legoktm <[email protected]>
Gerrit-Reviewer: Siebrand <[email protected]>
Gerrit-Reviewer: Umherirrender <[email protected]>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
