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

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);
+      $group_name = head(explode('.', $method_name));
-      $method_names[] = array(
+
+      $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);
+  }
+
 }

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',
       ));

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');
 
 

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');
   }

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() {

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() {

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.";
   }

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.";
   }

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.";
   }

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.";

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() {

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() {

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.";
   }

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.';
   }