From aa6e788f3666c0e4f22d251e0e5e1fa71a4e675d Mon Sep 17 00:00:00 2001 From: epriestley Date: Sun, 8 Jan 2017 12:54:39 -0800 Subject: [PATCH] Mark "v3" API methods as stable; mark obsoleted methods as "Frozen" Summary: Ref T12074. The "v3" API methods (`*.search`, `*.edit`) are currently marked as "unstable", but they're pretty stable and essentially all new code should be using them. Although these methods are seeing some changes, almost all changes are additive (support for new constraints or attachemnts) and do not break backward compatibility. We have no major, compatibility-breaking changes planned. I don't want to mark the older methods "deprecated" yet since `arc` still uses a lot of them and there are some capabilities not yet available on the v3 methods, but introduce a new "frozen" status with pointers to the new methods. Overall, this should gently push users toward the newer methods. Test Plan: {F2325323} Reviewers: chad Reviewed By: chad Maniphest Tasks: T12074 Differential Revision: https://secure.phabricator.com/D17158 --- .../PhabricatorConduitConsoleController.php | 7 +++++++ src/applications/conduit/method/ConduitAPIMethod.php | 7 ++++--- .../conduit/query/PhabricatorConduitMethodQuery.php | 3 ++- .../conduit/query/PhabricatorConduitSearchEngine.php | 4 ++++ .../conduit/DifferentialCloseConduitAPIMethod.php | 10 ++++++++++ .../DifferentialCreateCommentConduitAPIMethod.php | 10 ++++++++++ .../DifferentialCreateRevisionConduitAPIMethod.php | 10 ++++++++++ .../conduit/DifferentialQueryConduitAPIMethod.php | 10 ++++++++++ .../DifferentialUpdateRevisionConduitAPIMethod.php | 10 ++++++++++ .../conduit/ManiphestCreateTaskConduitAPIMethod.php | 10 ++++++++++ .../conduit/ManiphestInfoConduitAPIMethod.php | 10 ++++++++++ .../conduit/ManiphestQueryConduitAPIMethod.php | 10 ++++++++++ .../conduit/ManiphestUpdateConduitAPIMethod.php | 10 ++++++++++ .../paste/conduit/PasteCreateConduitAPIMethod.php | 10 ++++++++++ .../paste/conduit/PasteQueryConduitAPIMethod.php | 10 ++++++++++ .../people/conduit/UserQueryConduitAPIMethod.php | 10 ++++++++++ .../project/conduit/ProjectCreateConduitAPIMethod.php | 10 ++++++++++ .../project/conduit/ProjectQueryConduitAPIMethod.php | 10 ++++++++++ .../conduit/RepositoryQueryConduitAPIMethod.php | 6 ++++-- .../engine/PhabricatorSearchEngineAPIMethod.php | 11 ----------- .../editengine/PhabricatorEditEngineAPIMethod.php | 11 ----------- 21 files changed, 161 insertions(+), 28 deletions(-) diff --git a/src/applications/conduit/controller/PhabricatorConduitConsoleController.php b/src/applications/conduit/controller/PhabricatorConduitConsoleController.php index b767ead4f0..b696645e55 100644 --- a/src/applications/conduit/controller/PhabricatorConduitConsoleController.php +++ b/src/applications/conduit/controller/PhabricatorConduitConsoleController.php @@ -128,6 +128,13 @@ final class PhabricatorConduitConsoleController $stability_label = pht('Deprecated Method'); $stability_info = nonempty($reason, pht('This method is deprecated.')); break; + case ConduitAPIMethod::METHOD_STATUS_FROZEN: + $stability_icon = 'fa-archive grey'; + $stability_label = pht('Frozen Method'); + $stability_info = nonempty( + $reason, + pht('This method is frozen and will eventually be deprecated.')); + break; default: $stability_label = null; break; diff --git a/src/applications/conduit/method/ConduitAPIMethod.php b/src/applications/conduit/method/ConduitAPIMethod.php index 3a2cc6e30d..05831a782d 100644 --- a/src/applications/conduit/method/ConduitAPIMethod.php +++ b/src/applications/conduit/method/ConduitAPIMethod.php @@ -11,9 +11,10 @@ abstract class ConduitAPIMethod private $viewer; - const METHOD_STATUS_STABLE = 'stable'; - const METHOD_STATUS_UNSTABLE = 'unstable'; - const METHOD_STATUS_DEPRECATED = 'deprecated'; + const METHOD_STATUS_STABLE = 'stable'; + const METHOD_STATUS_UNSTABLE = 'unstable'; + const METHOD_STATUS_DEPRECATED = 'deprecated'; + const METHOD_STATUS_FROZEN = 'frozen'; const SCOPE_NEVER = 'scope.never'; const SCOPE_ALWAYS = 'scope.always'; diff --git a/src/applications/conduit/query/PhabricatorConduitMethodQuery.php b/src/applications/conduit/query/PhabricatorConduitMethodQuery.php index 0409e4ceb3..eb61d8c480 100644 --- a/src/applications/conduit/query/PhabricatorConduitMethodQuery.php +++ b/src/applications/conduit/query/PhabricatorConduitMethodQuery.php @@ -66,7 +66,8 @@ final class PhabricatorConduitMethodQuery } $status = array( - ConduitAPIMethod::METHOD_STATUS_STABLE => $this->isStable, + ConduitAPIMethod::METHOD_STATUS_STABLE => $this->isStable, + ConduitAPIMethod::METHOD_STATUS_FROZEN => $this->isStable, ConduitAPIMethod::METHOD_STATUS_DEPRECATED => $this->isDeprecated, ConduitAPIMethod::METHOD_STATUS_UNSTABLE => $this->isUnstable, ); diff --git a/src/applications/conduit/query/PhabricatorConduitSearchEngine.php b/src/applications/conduit/query/PhabricatorConduitSearchEngine.php index 3c01005722..787c2154d5 100644 --- a/src/applications/conduit/query/PhabricatorConduitSearchEngine.php +++ b/src/applications/conduit/query/PhabricatorConduitSearchEngine.php @@ -166,6 +166,10 @@ final class PhabricatorConduitSearchEngine $item->addIcon('fa-warning', pht('Deprecated')); $item->setStatusIcon('fa-warning red'); break; + case ConduitAPIMethod::METHOD_STATUS_FROZEN: + $item->addIcon('fa-archive', pht('Frozen')); + $item->setStatusIcon('fa-archive grey'); + break; } $list->addItem($item); diff --git a/src/applications/differential/conduit/DifferentialCloseConduitAPIMethod.php b/src/applications/differential/conduit/DifferentialCloseConduitAPIMethod.php index e613647935..d71876961e 100644 --- a/src/applications/differential/conduit/DifferentialCloseConduitAPIMethod.php +++ b/src/applications/differential/conduit/DifferentialCloseConduitAPIMethod.php @@ -11,6 +11,16 @@ final class DifferentialCloseConduitAPIMethod return pht('Close a Differential revision.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "differential.revision.edit" instead.'); + } + protected function defineParamTypes() { return array( 'revisionID' => 'required int', diff --git a/src/applications/differential/conduit/DifferentialCreateCommentConduitAPIMethod.php b/src/applications/differential/conduit/DifferentialCreateCommentConduitAPIMethod.php index 8f4b154876..459298c54f 100644 --- a/src/applications/differential/conduit/DifferentialCreateCommentConduitAPIMethod.php +++ b/src/applications/differential/conduit/DifferentialCreateCommentConduitAPIMethod.php @@ -11,6 +11,16 @@ final class DifferentialCreateCommentConduitAPIMethod return pht('Add a comment to a Differential revision.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "differential.revision.edit" instead.'); + } + protected function defineParamTypes() { return array( 'revision_id' => 'required revisionid', diff --git a/src/applications/differential/conduit/DifferentialCreateRevisionConduitAPIMethod.php b/src/applications/differential/conduit/DifferentialCreateRevisionConduitAPIMethod.php index 371d57cd9c..532d63680b 100644 --- a/src/applications/differential/conduit/DifferentialCreateRevisionConduitAPIMethod.php +++ b/src/applications/differential/conduit/DifferentialCreateRevisionConduitAPIMethod.php @@ -11,6 +11,16 @@ final class DifferentialCreateRevisionConduitAPIMethod return pht('Create a new Differential revision.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "differential.revision.edit" instead.'); + } + protected function defineParamTypes() { return array( // TODO: Arcanist passes this; prevent fatals after D4191 until Conduit diff --git a/src/applications/differential/conduit/DifferentialQueryConduitAPIMethod.php b/src/applications/differential/conduit/DifferentialQueryConduitAPIMethod.php index 1d4bcc2a8d..720361367a 100644 --- a/src/applications/differential/conduit/DifferentialQueryConduitAPIMethod.php +++ b/src/applications/differential/conduit/DifferentialQueryConduitAPIMethod.php @@ -11,6 +11,16 @@ final class DifferentialQueryConduitAPIMethod return pht('Query Differential revisions which match certain criteria.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "differential.revision.search" instead.'); + } + protected function defineParamTypes() { $hash_types = ArcanistDifferentialRevisionHash::getTypes(); $hash_const = $this->formatStringConstants($hash_types); diff --git a/src/applications/differential/conduit/DifferentialUpdateRevisionConduitAPIMethod.php b/src/applications/differential/conduit/DifferentialUpdateRevisionConduitAPIMethod.php index 232dbf79b4..d45dc9749e 100644 --- a/src/applications/differential/conduit/DifferentialUpdateRevisionConduitAPIMethod.php +++ b/src/applications/differential/conduit/DifferentialUpdateRevisionConduitAPIMethod.php @@ -11,6 +11,16 @@ final class DifferentialUpdateRevisionConduitAPIMethod return pht('Update a Differential revision.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "differential.revision.edit" instead.'); + } + protected function defineParamTypes() { return array( 'id' => 'required revisionid', diff --git a/src/applications/maniphest/conduit/ManiphestCreateTaskConduitAPIMethod.php b/src/applications/maniphest/conduit/ManiphestCreateTaskConduitAPIMethod.php index 3a404774cf..fac96372fe 100644 --- a/src/applications/maniphest/conduit/ManiphestCreateTaskConduitAPIMethod.php +++ b/src/applications/maniphest/conduit/ManiphestCreateTaskConduitAPIMethod.php @@ -11,6 +11,16 @@ final class ManiphestCreateTaskConduitAPIMethod return pht('Create a new Maniphest task.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "maniphest.edit" instead.'); + } + protected function defineParamTypes() { return $this->getTaskFields($is_new = true); } diff --git a/src/applications/maniphest/conduit/ManiphestInfoConduitAPIMethod.php b/src/applications/maniphest/conduit/ManiphestInfoConduitAPIMethod.php index 367feff41a..8bd439253f 100644 --- a/src/applications/maniphest/conduit/ManiphestInfoConduitAPIMethod.php +++ b/src/applications/maniphest/conduit/ManiphestInfoConduitAPIMethod.php @@ -10,6 +10,16 @@ final class ManiphestInfoConduitAPIMethod extends ManiphestConduitAPIMethod { return pht('Retrieve information about a Maniphest task, given its ID.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "maniphest.search" instead.'); + } + protected function defineParamTypes() { return array( 'task_id' => 'required id', diff --git a/src/applications/maniphest/conduit/ManiphestQueryConduitAPIMethod.php b/src/applications/maniphest/conduit/ManiphestQueryConduitAPIMethod.php index ea8aeb95ed..45373d2587 100644 --- a/src/applications/maniphest/conduit/ManiphestQueryConduitAPIMethod.php +++ b/src/applications/maniphest/conduit/ManiphestQueryConduitAPIMethod.php @@ -10,6 +10,16 @@ final class ManiphestQueryConduitAPIMethod extends ManiphestConduitAPIMethod { return pht('Execute complex searches for Maniphest tasks.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "maniphest.search" instead.'); + } + protected function defineParamTypes() { $statuses = array( ManiphestTaskQuery::STATUS_ANY, diff --git a/src/applications/maniphest/conduit/ManiphestUpdateConduitAPIMethod.php b/src/applications/maniphest/conduit/ManiphestUpdateConduitAPIMethod.php index d4adee9570..d8d02becd7 100644 --- a/src/applications/maniphest/conduit/ManiphestUpdateConduitAPIMethod.php +++ b/src/applications/maniphest/conduit/ManiphestUpdateConduitAPIMethod.php @@ -10,6 +10,16 @@ final class ManiphestUpdateConduitAPIMethod extends ManiphestConduitAPIMethod { return pht('Update an existing Maniphest task.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "maniphest.edit" instead.'); + } + protected function defineErrorTypes() { return array( 'ERR-BAD-TASK' => pht('No such Maniphest task exists.'), diff --git a/src/applications/paste/conduit/PasteCreateConduitAPIMethod.php b/src/applications/paste/conduit/PasteCreateConduitAPIMethod.php index b6ccd151ba..3badd04da7 100644 --- a/src/applications/paste/conduit/PasteCreateConduitAPIMethod.php +++ b/src/applications/paste/conduit/PasteCreateConduitAPIMethod.php @@ -10,6 +10,16 @@ final class PasteCreateConduitAPIMethod extends PasteConduitAPIMethod { return pht('Create a new paste.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "paste.edit" instead.'); + } + protected function defineParamTypes() { return array( 'content' => 'required string', diff --git a/src/applications/paste/conduit/PasteQueryConduitAPIMethod.php b/src/applications/paste/conduit/PasteQueryConduitAPIMethod.php index 6f3f87acf2..f20c18c06a 100644 --- a/src/applications/paste/conduit/PasteQueryConduitAPIMethod.php +++ b/src/applications/paste/conduit/PasteQueryConduitAPIMethod.php @@ -10,6 +10,16 @@ final class PasteQueryConduitAPIMethod extends PasteConduitAPIMethod { return pht('Query Pastes.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "paste.search" instead.'); + } + protected function defineParamTypes() { return array( 'ids' => 'optional list', diff --git a/src/applications/people/conduit/UserQueryConduitAPIMethod.php b/src/applications/people/conduit/UserQueryConduitAPIMethod.php index c42414a6be..df0ec65841 100644 --- a/src/applications/people/conduit/UserQueryConduitAPIMethod.php +++ b/src/applications/people/conduit/UserQueryConduitAPIMethod.php @@ -10,6 +10,16 @@ final class UserQueryConduitAPIMethod extends UserConduitAPIMethod { return pht('Query users.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "user.search" instead.'); + } + protected function defineParamTypes() { return array( 'usernames' => 'optional list', diff --git a/src/applications/project/conduit/ProjectCreateConduitAPIMethod.php b/src/applications/project/conduit/ProjectCreateConduitAPIMethod.php index aefade63a2..66075e7248 100644 --- a/src/applications/project/conduit/ProjectCreateConduitAPIMethod.php +++ b/src/applications/project/conduit/ProjectCreateConduitAPIMethod.php @@ -10,6 +10,16 @@ final class ProjectCreateConduitAPIMethod extends ProjectConduitAPIMethod { return pht('Create a project.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "project.edit" instead.'); + } + protected function defineParamTypes() { return array( 'name' => 'required string', diff --git a/src/applications/project/conduit/ProjectQueryConduitAPIMethod.php b/src/applications/project/conduit/ProjectQueryConduitAPIMethod.php index 3116ecb7f9..0a02088413 100644 --- a/src/applications/project/conduit/ProjectQueryConduitAPIMethod.php +++ b/src/applications/project/conduit/ProjectQueryConduitAPIMethod.php @@ -10,6 +10,16 @@ final class ProjectQueryConduitAPIMethod extends ProjectConduitAPIMethod { return pht('Execute searches for Projects.'); } + public function getMethodStatus() { + return self::METHOD_STATUS_FROZEN; + } + + public function getMethodStatusDescription() { + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "project.search" instead.'); + } + protected function defineParamTypes() { $statuses = array( diff --git a/src/applications/repository/conduit/RepositoryQueryConduitAPIMethod.php b/src/applications/repository/conduit/RepositoryQueryConduitAPIMethod.php index a3c1061e6a..61435e2a1b 100644 --- a/src/applications/repository/conduit/RepositoryQueryConduitAPIMethod.php +++ b/src/applications/repository/conduit/RepositoryQueryConduitAPIMethod.php @@ -8,11 +8,13 @@ final class RepositoryQueryConduitAPIMethod } public function getMethodStatus() { - return self::METHOD_STATUS_UNSTABLE; + return self::METHOD_STATUS_FROZEN; } public function getMethodStatusDescription() { - return pht('Repository methods are new and subject to change.'); + return pht( + 'This method is frozen and will eventually be deprecated. New code '. + 'should use "diffusion.repository.query" instead.'); } public function getMethodDescription() { diff --git a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php index d050e48bff..3d13f2c3d9 100644 --- a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php +++ b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php @@ -32,17 +32,6 @@ abstract class PhabricatorSearchEngineAPIMethod return PhabricatorApplication::getByClass($class); } - public function getMethodStatus() { - return self::METHOD_STATUS_UNSTABLE; - } - - public function getMethodStatusDescription() { - return pht( - 'ApplicationSearch methods are fairly stable, but were introduced '. - 'relatively recently and may continue to evolve as more applications '. - 'adopt them.'); - } - final protected function defineParamTypes() { return array( 'queryKey' => 'optional string', diff --git a/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php b/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php index de693a4049..3a6dd4b70c 100644 --- a/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php +++ b/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php @@ -11,17 +11,6 @@ abstract class PhabricatorEditEngineAPIMethod return PhabricatorApplication::getByClass($class); } - public function getMethodStatus() { - return self::METHOD_STATUS_UNSTABLE; - } - - public function getMethodStatusDescription() { - return pht( - 'ApplicationEditor methods are fairly stable, but were introduced '. - 'relatively recently and may continue to evolve as more applications '. - 'adopt them.'); - } - final protected function defineParamTypes() { return array( 'transactions' => 'list>',