From f70c7a06de8776cd7b4ebdc6fe04932c6d1feaec Mon Sep 17 00:00:00 2001 From: Brad Jorsch Date: Mon, 9 Jan 2017 15:38:36 -0800 Subject: [PATCH] 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 --- docs/hooks.txt | 5 +++++ includes/api/ApiBase.php | 12 ++++++++++++ includes/api/ApiMain.php | 6 +++++- includes/api/i18n/en.json | 1 + includes/api/i18n/qqq.json | 1 + tests/phpunit/includes/api/ApiMainTest.php | 8 ++++++-- 6 files changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/hooks.txt b/docs/hooks.txt index 1da39cf61b..ec09ea98a6 100644 --- a/docs/hooks.txt +++ b/docs/hooks.txt @@ -365,6 +365,11 @@ $user: Current user * 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 b8dd4641d9..e2498108e5 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -1718,6 +1718,18 @@ abstract class ApiBase extends ContextSource { $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 52f1d95830..59227d91e9 100644 --- a/includes/api/ApiMain.php +++ b/includes/api/ApiMain.php @@ -1109,7 +1109,11 @@ class ApiMain extends ApiBase { $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 8ac11d0499..9e74bebd07 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 mediawiki-api@lists.wikimedia.org\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 85e24e4c44..08e543722c 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 action=feedwatchlist.\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 71dafceb5a..eff41e3492 100644 --- a/tests/phpunit/includes/api/ApiMainTest.php +++ b/tests/phpunit/includes/api/ApiMainTest.php @@ -546,7 +546,9 @@ class ApiMainTest extends ApiTestCase { [ '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 @@ class ApiMainTest extends ApiTestCase { [ '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(), ] ], -- 2.20.1