Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Formalize a mechanism for marking Conduit methods deprecated/unstable

Summary:
This is better than writing "(UNSTABLE!!!)" in front of the text description.

I'll add a wiki to keep track of API changes, too.

See also D2087, which motivates this.

Test Plan: Browsed console, saw "deprecated" and "unstable" on appropriate methods.

Reviewers: btrahan, vrana, jungejason

Reviewed By: vrana

CC: aran

Maniphest Tasks: T909

Differential Revision: https://secure.phabricator.com/D2271
  • Loading branch information...
commit bdcba43f212ad0a37d5fef016c6a1c9e46d97a35 1 parent bddcf28
@epriestley epriestley authored
Showing with 159 additions and 13 deletions.
  1. +32 −5 src/applications/conduit/controller/base/PhabricatorConduitController.php
  2. +31 −2 src/applications/conduit/controller/console/PhabricatorConduitConsoleController.php
  3. +1 −1  src/applications/conduit/controller/console/__init__.php
  4. +30 −0 src/applications/conduit/method/base/ConduitAPIMethod.php
  5. +5 −1 src/applications/conduit/method/chatlog/query/ConduitAPI_chatlog_query_Method.php
  6. +5 −1 src/applications/conduit/method/chatlog/record/ConduitAPI_chatlog_record_Method.php
  7. +8 −0 src/applications/conduit/method/differential/find/ConduitAPI_differential_find_Method.php
  8. +8 −0 src/applications/conduit/method/differential/getrevision/ConduitAPI_differential_getrevision_Method.php
  9. +8 −0 ...ions/conduit/method/differential/getrevisionfeedback/ConduitAPI_differential_getrevisionfeedback_Method.php
  10. +8 −0 ...duit/method/differential/updatetaskrevisionassoc/ConduitAPI_differential_updatetaskrevisionassoc_Method.php
  11. +5 −1 src/applications/conduit/method/feed/publish/ConduitAPI_feed_publish_Method.php
  12. +5 −1 src/applications/conduit/method/feed/query/ConduitAPI_feed_query_Method.php
  13. +9 −1 src/applications/conduit/method/phid/info/ConduitAPI_phid_info_Method.php
  14. +4 −0 src/applications/conduit/method/remarkup/process/ConduitAPI_remarkup_process_Method.php
View
37 src/applications/conduit/controller/base/PhabricatorConduitController.php
@@ -51,8 +51,16 @@ public function buildStandardPageResponse($view, array $data) {
$nav->addLabel($group);
foreach ($methods as $method) {
$method_name = $method['full_name'];
+
+ $display_name = $method_name;
+ switch ($method['status']) {
+ case ConduitAPIMethod::METHOD_STATUS_DEPRECATED:
+ $display_name = '('.$display_name.')';
+ break;
+ }
+
$nav->addFilter('method/'.$method_name,
- $method_name);
+ $display_name);
if (!$first_filter) {
$first_filter = 'method/'.$method_name;
}
@@ -103,23 +111,42 @@ protected function getAllMethodImplementationClasses() {
return array_values(ipull($classes, 'name'));
}
-
private function getMethodFilters() {
$classes = $this->getAllMethodImplementationClasses();
$method_names = array();
foreach ($classes as $method_class) {
$method_name = ConduitAPIMethod::getAPIMethodNameFromClassName(
$method_class);
- $parts = explode('.', $method_name);
- $method_names[] = array(
+ $group_name = head(explode('.', $method_name));
+
+ $status = newv($method_class, array())->getMethodStatus();
+
+ $key = sprintf(
+ '%02d %s %s',
+ $this->getOrderForMethodStatus($status),
+ $group_name,
+ $method_name);
+
+ $method_names[$key] = array(
'full_name' => $method_name,
- 'group_name' => reset($parts),
+ 'group_name' => $group_name,
+ 'status' => $status,
);
}
+ ksort($method_names);
$method_names = igroup($method_names, 'group_name');
ksort($method_names);
return $method_names;
}
+ private function getOrderForMethodStatus($status) {
+ $map = array(
+ ConduitAPIMethod::METHOD_STATUS_STABLE => 0,
+ ConduitAPIMethod::METHOD_STATUS_UNSTABLE => 1,
+ ConduitAPIMethod::METHOD_STATUS_DEPRECATED => 2,
+ );
+ return idx($map, $status, 0);
+ }
+
}
View
33 src/applications/conduit/controller/console/PhabricatorConduitConsoleController.php
@@ -39,9 +39,35 @@ public function processRequest() {
$this->setFilter('method/'.$this->method);
$method_class = $methods[$this->method];
- PhutilSymbolLoader::loadClass($method_class);
$method_object = newv($method_class, array());
+ $status = $method_object->getMethodStatus();
+ $reason = $method_object->getMethodStatusDescription();
+
+ $status_view = null;
+ if ($status != 'stable') {
+ $status_view = new AphrontErrorView();
+ switch ($status) {
+ case ConduitAPIMethod::METHOD_STATUS_DEPRECATED:
+ $status_view->setTitle('Deprecated Method');
+ $status_view->appendChild(
+ phutil_escape_html(
+ nonempty(
+ $reason,
+ "This method is deprecated.")));
+ break;
+ case ConduitAPIMethod::METHOD_STATUS_UNSTABLE:
+ $status_view->setSeverity(AphrontErrorView::SEVERITY_WARNING);
+ $status_view->setTitle('Unstable Method');
+ $status_view->appendChild(
+ phutil_escape_html(
+ nonempty(
+ $reason,
+ "This method is new and unstable. Its interface is subject ".
+ "to change.")));
+ break;
+ }
+ }
$error_description = array();
$error_types = $method_object->defineErrorTypes();
@@ -110,7 +136,10 @@ public function processRequest() {
$panel->setWidth(AphrontPanelView::WIDTH_FULL);
return $this->buildStandardPageResponse(
- array($panel),
+ array(
+ $status_view,
+ $panel,
+ ),
array(
'title' => 'Conduit Console',
));
View
2  src/applications/conduit/controller/console/__init__.php
@@ -14,10 +14,10 @@
phutil_require_module('phabricator', 'view/form/control/static');
phutil_require_module('phabricator', 'view/form/control/submit');
phutil_require_module('phabricator', 'view/form/control/text');
+phutil_require_module('phabricator', 'view/form/error');
phutil_require_module('phabricator', 'view/layout/panel');
phutil_require_module('phutil', 'markup');
-phutil_require_module('phutil', 'symbols');
phutil_require_module('phutil', 'utils');
View
30 src/applications/conduit/method/base/ConduitAPIMethod.php
@@ -17,10 +17,16 @@
*/
/**
+ *
+ * @task status Method Status
* @group conduit
*/
abstract class ConduitAPIMethod {
+ const METHOD_STATUS_STABLE = 'stable';
+ const METHOD_STATUS_UNSTABLE = 'unstable';
+ const METHOD_STATUS_DEPRECATED = 'deprecated';
+
abstract public function getMethodDescription();
abstract public function defineParamTypes();
abstract public function defineReturnType();
@@ -31,6 +37,30 @@ public function __construct() {
}
+ /**
+ * Get the status for this method (e.g., stable, unstable or deprecated).
+ * Should return a METHOD_STATUS_* constant. By default, methods are
+ * "stable".
+ *
+ * @return const METHOD_STATUS_* constant.
+ * @task status
+ */
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_STABLE;
+ }
+
+ /**
+ * Optional description to supplement the method status. In particular, if
+ * a method is deprecated, you can return a string here describing the reason
+ * for deprecation and stable alternatives.
+ *
+ * @return string|null Description of the method status, if available.
+ * @task status
+ */
+ public function getMethodStatusDescription() {
+ return null;
+ }
+
public function getErrorDescription($error_code) {
return idx($this->defineErrorTypes(), $error_code, 'Unknown Error');
}
View
6 src/applications/conduit/method/chatlog/query/ConduitAPI_chatlog_query_Method.php
@@ -22,8 +22,12 @@
final class ConduitAPI_chatlog_query_Method
extends ConduitAPI_chatlog_Method {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_UNSTABLE;
+ }
+
public function getMethodDescription() {
- return "(Unstable!) Retrieve chatter.";
+ return "Retrieve chatter.";
}
public function defineParamTypes() {
View
6 src/applications/conduit/method/chatlog/record/ConduitAPI_chatlog_record_Method.php
@@ -22,8 +22,12 @@
final class ConduitAPI_chatlog_record_Method
extends ConduitAPI_chatlog_Method {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_UNSTABLE;
+ }
+
public function getMethodDescription() {
- return "(Unstable!) Record chatter.";
+ return "Record chatter.";
}
public function defineParamTypes() {
View
8 src/applications/conduit/method/differential/find/ConduitAPI_differential_find_Method.php
@@ -21,6 +21,14 @@
*/
final class ConduitAPI_differential_find_Method extends ConduitAPIMethod {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_DEPRECATED;
+ }
+
+ public function getMethodStatusDescription() {
+ return "Replaced by 'differential.query'.";
+ }
+
public function getMethodDescription() {
return "Query Differential revisions which match certain criteria.";
}
View
8 src/applications/conduit/method/differential/getrevision/ConduitAPI_differential_getrevision_Method.php
@@ -22,6 +22,14 @@
final class ConduitAPI_differential_getrevision_Method
extends ConduitAPIMethod {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_DEPRECATED;
+ }
+
+ public function getMethodStatusDescription() {
+ return "Replaced by 'differential.query'.";
+ }
+
public function getMethodDescription() {
return "Load the content of a revision from Differential.";
}
View
8 ...s/conduit/method/differential/getrevisionfeedback/ConduitAPI_differential_getrevisionfeedback_Method.php
@@ -22,6 +22,14 @@
final class ConduitAPI_differential_getrevisionfeedback_Method
extends ConduitAPIMethod {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_DEPRECATED;
+ }
+
+ public function getMethodStatusDescription() {
+ return "Replaced by 'differential.getrevisioncomments'.";
+ }
+
public function getMethodDescription() {
return "Retrieve Differential Revision Feedback.";
}
View
8 ...t/method/differential/updatetaskrevisionassoc/ConduitAPI_differential_updatetaskrevisionassoc_Method.php
@@ -22,6 +22,14 @@
final class ConduitAPI_differential_updatetaskrevisionassoc_Method
extends ConduitAPIMethod {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_DEPRECATED;
+ }
+
+ public function getMethodStatusDescription() {
+ return "This method should not really exist. Pretend it doesn't.";
+ }
+
public function getMethodDescription() {
return "Given a task together with its original and new associated ".
"revisions, update the revisions for their attached_tasks.";
View
6 src/applications/conduit/method/feed/publish/ConduitAPI_feed_publish_Method.php
@@ -22,8 +22,12 @@
final class ConduitAPI_feed_publish_Method
extends ConduitAPIMethod {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_UNSTABLE;
+ }
+
public function getMethodDescription() {
- return "(UNSTABLE!!!) Publish a story to the feed.";
+ return "Publish a story to the feed.";
}
public function defineParamTypes() {
View
6 src/applications/conduit/method/feed/query/ConduitAPI_feed_query_Method.php
@@ -21,8 +21,12 @@
*/
final class ConduitAPI_feed_query_Method extends ConduitAPIMethod {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_UNSTABLE;
+ }
+
public function getMethodDescription() {
- return "(UNSTABLE!!) Query the feed for stories";
+ return "Query the feed for stories";
}
private function getDefaultLimit() {
View
10 src/applications/conduit/method/phid/info/ConduitAPI_phid_info_Method.php
@@ -1,7 +1,7 @@
<?php
/*
- * Copyright 2011 Facebook, Inc.
+ * Copyright 2012 Facebook, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -22,6 +22,14 @@
final class ConduitAPI_phid_info_Method
extends ConduitAPI_phid_Method {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_DEPRECATED;
+ }
+
+ public function getMethodStatusDescription() {
+ return "Replaced by 'phid.query'.";
+ }
+
public function getMethodDescription() {
return "Retrieve information about an arbitrary PHID.";
}
View
4 src/applications/conduit/method/remarkup/process/ConduitAPI_remarkup_process_Method.php
@@ -18,6 +18,10 @@
final class ConduitAPI_remarkup_process_Method extends ConduitAPIMethod {
+ public function getMethodStatus() {
+ return self::METHOD_STATUS_UNSTABLE;
+ }
+
public function getMethodDescription() {
return 'Process text through remarkup in phabricator context.';
}
Please sign in to comment.
Something went wrong with that request. Please try again.