mirror of
https://we.phorge.it/source/phorge.git
synced 2025-02-02 01:48:23 +01:00
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
This commit is contained in:
epriestley
parent
bddcf288d8
commit
bdcba43f21
14 changed files with 159 additions and 13 deletions
|
|
@ -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);
|
||||
}
|
||||
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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',
|
||||
));
|
||||
|
|
|
|||
|
|
@ -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');
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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');
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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() {
|
||||
|
|
|
|||
|
|
@ -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() {
|
||||
|
|
|
|||
|
|
@ -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.";
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.";
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.";
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.";
|
||||
|
|
|
|||
|
|
@ -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() {
|
||||
|
|
|
|||
|
|
@ -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() {
|
||||
|
|
|
|||
|
|
@ -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.";
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.';
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue