diff --git a/src/applications/conduit/controller/base/PhabricatorConduitController.php b/src/applications/conduit/controller/base/PhabricatorConduitController.php index e8970994f1..8f5988e6f5 100644 --- a/src/applications/conduit/controller/base/PhabricatorConduitController.php +++ b/src/applications/conduit/controller/base/PhabricatorConduitController.php @@ -51,8 +51,16 @@ abstract class PhabricatorConduitController extends PhabricatorController { $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 @@ abstract class PhabricatorConduitController extends PhabricatorController { 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); + } + } diff --git a/src/applications/conduit/controller/console/PhabricatorConduitConsoleController.php b/src/applications/conduit/controller/console/PhabricatorConduitConsoleController.php index ab945a3a82..b1e8a8856d 100644 --- a/src/applications/conduit/controller/console/PhabricatorConduitConsoleController.php +++ b/src/applications/conduit/controller/console/PhabricatorConduitConsoleController.php @@ -39,9 +39,35 @@ final class PhabricatorConduitConsoleController $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 @@ final class PhabricatorConduitConsoleController $panel->setWidth(AphrontPanelView::WIDTH_FULL); return $this->buildStandardPageResponse( - array($panel), + array( + $status_view, + $panel, + ), array( 'title' => 'Conduit Console', )); diff --git a/src/applications/conduit/controller/console/__init__.php b/src/applications/conduit/controller/console/__init__.php index f58e4210cc..5e21a1df74 100644 --- a/src/applications/conduit/controller/console/__init__.php +++ b/src/applications/conduit/controller/console/__init__.php @@ -14,10 +14,10 @@ phutil_require_module('phabricator', 'view/form/control/select'); 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'); diff --git a/src/applications/conduit/method/base/ConduitAPIMethod.php b/src/applications/conduit/method/base/ConduitAPIMethod.php index 04aef555d1..9d30f71073 100644 --- a/src/applications/conduit/method/base/ConduitAPIMethod.php +++ b/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 @@ abstract class ConduitAPIMethod { } + /** + * 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'); } diff --git a/src/applications/conduit/method/chatlog/query/ConduitAPI_chatlog_query_Method.php b/src/applications/conduit/method/chatlog/query/ConduitAPI_chatlog_query_Method.php index a434d63196..8bca00e9d0 100644 --- a/src/applications/conduit/method/chatlog/query/ConduitAPI_chatlog_query_Method.php +++ b/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() { diff --git a/src/applications/conduit/method/chatlog/record/ConduitAPI_chatlog_record_Method.php b/src/applications/conduit/method/chatlog/record/ConduitAPI_chatlog_record_Method.php index 22595322a1..687dee8fb8 100644 --- a/src/applications/conduit/method/chatlog/record/ConduitAPI_chatlog_record_Method.php +++ b/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() { diff --git a/src/applications/conduit/method/differential/find/ConduitAPI_differential_find_Method.php b/src/applications/conduit/method/differential/find/ConduitAPI_differential_find_Method.php index 5fcfab0b9c..aac289101d 100644 --- a/src/applications/conduit/method/differential/find/ConduitAPI_differential_find_Method.php +++ b/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."; } diff --git a/src/applications/conduit/method/differential/getrevision/ConduitAPI_differential_getrevision_Method.php b/src/applications/conduit/method/differential/getrevision/ConduitAPI_differential_getrevision_Method.php index 3a3f33f4a0..5e50142db5 100644 --- a/src/applications/conduit/method/differential/getrevision/ConduitAPI_differential_getrevision_Method.php +++ b/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."; } diff --git a/src/applications/conduit/method/differential/getrevisionfeedback/ConduitAPI_differential_getrevisionfeedback_Method.php b/src/applications/conduit/method/differential/getrevisionfeedback/ConduitAPI_differential_getrevisionfeedback_Method.php index 67c009c6f9..70954ae50c 100644 --- a/src/applications/conduit/method/differential/getrevisionfeedback/ConduitAPI_differential_getrevisionfeedback_Method.php +++ b/src/applications/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."; } diff --git a/src/applications/conduit/method/differential/updatetaskrevisionassoc/ConduitAPI_differential_updatetaskrevisionassoc_Method.php b/src/applications/conduit/method/differential/updatetaskrevisionassoc/ConduitAPI_differential_updatetaskrevisionassoc_Method.php index 381faa7b70..9598159e99 100644 --- a/src/applications/conduit/method/differential/updatetaskrevisionassoc/ConduitAPI_differential_updatetaskrevisionassoc_Method.php +++ b/src/applications/conduit/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."; diff --git a/src/applications/conduit/method/feed/publish/ConduitAPI_feed_publish_Method.php b/src/applications/conduit/method/feed/publish/ConduitAPI_feed_publish_Method.php index c2be4bf06f..05752a3994 100644 --- a/src/applications/conduit/method/feed/publish/ConduitAPI_feed_publish_Method.php +++ b/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() { diff --git a/src/applications/conduit/method/feed/query/ConduitAPI_feed_query_Method.php b/src/applications/conduit/method/feed/query/ConduitAPI_feed_query_Method.php index 82121d5de8..5181d52d42 100644 --- a/src/applications/conduit/method/feed/query/ConduitAPI_feed_query_Method.php +++ b/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() { diff --git a/src/applications/conduit/method/phid/info/ConduitAPI_phid_info_Method.php b/src/applications/conduit/method/phid/info/ConduitAPI_phid_info_Method.php index 4c57d8f799..e908df409d 100644 --- a/src/applications/conduit/method/phid/info/ConduitAPI_phid_info_Method.php +++ b/src/applications/conduit/method/phid/info/ConduitAPI_phid_info_Method.php @@ -1,7 +1,7 @@