@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+161
-28
+7
src/applications/conduit/controller/PhabricatorConduitConsoleController.php
+7
src/applications/conduit/controller/PhabricatorConduitConsoleController.php
···
128
128
$stability_label = pht('Deprecated Method');
129
129
$stability_info = nonempty($reason, pht('This method is deprecated.'));
130
130
break;
131
+
case ConduitAPIMethod::METHOD_STATUS_FROZEN:
132
+
$stability_icon = 'fa-archive grey';
133
+
$stability_label = pht('Frozen Method');
134
+
$stability_info = nonempty(
135
+
$reason,
136
+
pht('This method is frozen and will eventually be deprecated.'));
137
+
break;
131
138
default:
132
139
$stability_label = null;
133
140
break;
+4
-3
src/applications/conduit/method/ConduitAPIMethod.php
+4
-3
src/applications/conduit/method/ConduitAPIMethod.php
···
11
11
12
12
private $viewer;
13
13
14
-
const METHOD_STATUS_STABLE = 'stable';
15
-
const METHOD_STATUS_UNSTABLE = 'unstable';
16
-
const METHOD_STATUS_DEPRECATED = 'deprecated';
14
+
const METHOD_STATUS_STABLE = 'stable';
15
+
const METHOD_STATUS_UNSTABLE = 'unstable';
16
+
const METHOD_STATUS_DEPRECATED = 'deprecated';
17
+
const METHOD_STATUS_FROZEN = 'frozen';
17
18
18
19
const SCOPE_NEVER = 'scope.never';
19
20
const SCOPE_ALWAYS = 'scope.always';
+2
-1
src/applications/conduit/query/PhabricatorConduitMethodQuery.php
+2
-1
src/applications/conduit/query/PhabricatorConduitMethodQuery.php
···
66
66
}
67
67
68
68
$status = array(
69
-
ConduitAPIMethod::METHOD_STATUS_STABLE => $this->isStable,
69
+
ConduitAPIMethod::METHOD_STATUS_STABLE => $this->isStable,
70
+
ConduitAPIMethod::METHOD_STATUS_FROZEN => $this->isStable,
70
71
ConduitAPIMethod::METHOD_STATUS_DEPRECATED => $this->isDeprecated,
71
72
ConduitAPIMethod::METHOD_STATUS_UNSTABLE => $this->isUnstable,
72
73
);
+4
src/applications/conduit/query/PhabricatorConduitSearchEngine.php
+4
src/applications/conduit/query/PhabricatorConduitSearchEngine.php
···
166
166
$item->addIcon('fa-warning', pht('Deprecated'));
167
167
$item->setStatusIcon('fa-warning red');
168
168
break;
169
+
case ConduitAPIMethod::METHOD_STATUS_FROZEN:
170
+
$item->addIcon('fa-archive', pht('Frozen'));
171
+
$item->setStatusIcon('fa-archive grey');
172
+
break;
169
173
}
170
174
171
175
$list->addItem($item);
+10
src/applications/differential/conduit/DifferentialCloseConduitAPIMethod.php
+10
src/applications/differential/conduit/DifferentialCloseConduitAPIMethod.php
···
11
11
return pht('Close a Differential revision.');
12
12
}
13
13
14
+
public function getMethodStatus() {
15
+
return self::METHOD_STATUS_FROZEN;
16
+
}
17
+
18
+
public function getMethodStatusDescription() {
19
+
return pht(
20
+
'This method is frozen and will eventually be deprecated. New code '.
21
+
'should use "differential.revision.edit" instead.');
22
+
}
23
+
14
24
protected function defineParamTypes() {
15
25
return array(
16
26
'revisionID' => 'required int',
+10
src/applications/differential/conduit/DifferentialCreateCommentConduitAPIMethod.php
+10
src/applications/differential/conduit/DifferentialCreateCommentConduitAPIMethod.php
···
11
11
return pht('Add a comment to a Differential revision.');
12
12
}
13
13
14
+
public function getMethodStatus() {
15
+
return self::METHOD_STATUS_FROZEN;
16
+
}
17
+
18
+
public function getMethodStatusDescription() {
19
+
return pht(
20
+
'This method is frozen and will eventually be deprecated. New code '.
21
+
'should use "differential.revision.edit" instead.');
22
+
}
23
+
14
24
protected function defineParamTypes() {
15
25
return array(
16
26
'revision_id' => 'required revisionid',
+10
src/applications/differential/conduit/DifferentialCreateRevisionConduitAPIMethod.php
+10
src/applications/differential/conduit/DifferentialCreateRevisionConduitAPIMethod.php
···
11
11
return pht('Create a new Differential revision.');
12
12
}
13
13
14
+
public function getMethodStatus() {
15
+
return self::METHOD_STATUS_FROZEN;
16
+
}
17
+
18
+
public function getMethodStatusDescription() {
19
+
return pht(
20
+
'This method is frozen and will eventually be deprecated. New code '.
21
+
'should use "differential.revision.edit" instead.');
22
+
}
23
+
14
24
protected function defineParamTypes() {
15
25
return array(
16
26
// TODO: Arcanist passes this; prevent fatals after D4191 until Conduit
+10
src/applications/differential/conduit/DifferentialQueryConduitAPIMethod.php
+10
src/applications/differential/conduit/DifferentialQueryConduitAPIMethod.php
···
11
11
return pht('Query Differential revisions which match certain criteria.');
12
12
}
13
13
14
+
public function getMethodStatus() {
15
+
return self::METHOD_STATUS_FROZEN;
16
+
}
17
+
18
+
public function getMethodStatusDescription() {
19
+
return pht(
20
+
'This method is frozen and will eventually be deprecated. New code '.
21
+
'should use "differential.revision.search" instead.');
22
+
}
23
+
14
24
protected function defineParamTypes() {
15
25
$hash_types = ArcanistDifferentialRevisionHash::getTypes();
16
26
$hash_const = $this->formatStringConstants($hash_types);
+10
src/applications/differential/conduit/DifferentialUpdateRevisionConduitAPIMethod.php
+10
src/applications/differential/conduit/DifferentialUpdateRevisionConduitAPIMethod.php
···
11
11
return pht('Update a Differential revision.');
12
12
}
13
13
14
+
public function getMethodStatus() {
15
+
return self::METHOD_STATUS_FROZEN;
16
+
}
17
+
18
+
public function getMethodStatusDescription() {
19
+
return pht(
20
+
'This method is frozen and will eventually be deprecated. New code '.
21
+
'should use "differential.revision.edit" instead.');
22
+
}
23
+
14
24
protected function defineParamTypes() {
15
25
return array(
16
26
'id' => 'required revisionid',
+10
src/applications/maniphest/conduit/ManiphestCreateTaskConduitAPIMethod.php
+10
src/applications/maniphest/conduit/ManiphestCreateTaskConduitAPIMethod.php
···
11
11
return pht('Create a new Maniphest task.');
12
12
}
13
13
14
+
public function getMethodStatus() {
15
+
return self::METHOD_STATUS_FROZEN;
16
+
}
17
+
18
+
public function getMethodStatusDescription() {
19
+
return pht(
20
+
'This method is frozen and will eventually be deprecated. New code '.
21
+
'should use "maniphest.edit" instead.');
22
+
}
23
+
14
24
protected function defineParamTypes() {
15
25
return $this->getTaskFields($is_new = true);
16
26
}
+10
src/applications/maniphest/conduit/ManiphestInfoConduitAPIMethod.php
+10
src/applications/maniphest/conduit/ManiphestInfoConduitAPIMethod.php
···
10
10
return pht('Retrieve information about a Maniphest task, given its ID.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "maniphest.search" instead.');
21
+
}
22
+
13
23
protected function defineParamTypes() {
14
24
return array(
15
25
'task_id' => 'required id',
+10
src/applications/maniphest/conduit/ManiphestQueryConduitAPIMethod.php
+10
src/applications/maniphest/conduit/ManiphestQueryConduitAPIMethod.php
···
10
10
return pht('Execute complex searches for Maniphest tasks.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "maniphest.search" instead.');
21
+
}
22
+
13
23
protected function defineParamTypes() {
14
24
$statuses = array(
15
25
ManiphestTaskQuery::STATUS_ANY,
+10
src/applications/maniphest/conduit/ManiphestUpdateConduitAPIMethod.php
+10
src/applications/maniphest/conduit/ManiphestUpdateConduitAPIMethod.php
···
10
10
return pht('Update an existing Maniphest task.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "maniphest.edit" instead.');
21
+
}
22
+
13
23
protected function defineErrorTypes() {
14
24
return array(
15
25
'ERR-BAD-TASK' => pht('No such Maniphest task exists.'),
+10
src/applications/paste/conduit/PasteCreateConduitAPIMethod.php
+10
src/applications/paste/conduit/PasteCreateConduitAPIMethod.php
···
10
10
return pht('Create a new paste.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "paste.edit" instead.');
21
+
}
22
+
13
23
protected function defineParamTypes() {
14
24
return array(
15
25
'content' => 'required string',
+10
src/applications/paste/conduit/PasteQueryConduitAPIMethod.php
+10
src/applications/paste/conduit/PasteQueryConduitAPIMethod.php
···
10
10
return pht('Query Pastes.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "paste.search" instead.');
21
+
}
22
+
13
23
protected function defineParamTypes() {
14
24
return array(
15
25
'ids' => 'optional list<int>',
+10
src/applications/people/conduit/UserQueryConduitAPIMethod.php
+10
src/applications/people/conduit/UserQueryConduitAPIMethod.php
···
10
10
return pht('Query users.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "user.search" instead.');
21
+
}
22
+
13
23
protected function defineParamTypes() {
14
24
return array(
15
25
'usernames' => 'optional list<string>',
+10
src/applications/project/conduit/ProjectCreateConduitAPIMethod.php
+10
src/applications/project/conduit/ProjectCreateConduitAPIMethod.php
···
10
10
return pht('Create a project.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "project.edit" instead.');
21
+
}
22
+
13
23
protected function defineParamTypes() {
14
24
return array(
15
25
'name' => 'required string',
+10
src/applications/project/conduit/ProjectQueryConduitAPIMethod.php
+10
src/applications/project/conduit/ProjectQueryConduitAPIMethod.php
···
10
10
return pht('Execute searches for Projects.');
11
11
}
12
12
13
+
public function getMethodStatus() {
14
+
return self::METHOD_STATUS_FROZEN;
15
+
}
16
+
17
+
public function getMethodStatusDescription() {
18
+
return pht(
19
+
'This method is frozen and will eventually be deprecated. New code '.
20
+
'should use "project.search" instead.');
21
+
}
22
+
13
23
protected function defineParamTypes() {
14
24
15
25
$statuses = array(
+4
-2
src/applications/repository/conduit/RepositoryQueryConduitAPIMethod.php
+4
-2
src/applications/repository/conduit/RepositoryQueryConduitAPIMethod.php
···
8
8
}
9
9
10
10
public function getMethodStatus() {
11
-
return self::METHOD_STATUS_UNSTABLE;
11
+
return self::METHOD_STATUS_FROZEN;
12
12
}
13
13
14
14
public function getMethodStatusDescription() {
15
-
return pht('Repository methods are new and subject to change.');
15
+
return pht(
16
+
'This method is frozen and will eventually be deprecated. New code '.
17
+
'should use "diffusion.repository.query" instead.');
16
18
}
17
19
18
20
public function getMethodDescription() {
-11
src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
-11
src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
···
32
32
return PhabricatorApplication::getByClass($class);
33
33
}
34
34
35
-
public function getMethodStatus() {
36
-
return self::METHOD_STATUS_UNSTABLE;
37
-
}
38
-
39
-
public function getMethodStatusDescription() {
40
-
return pht(
41
-
'ApplicationSearch methods are fairly stable, but were introduced '.
42
-
'relatively recently and may continue to evolve as more applications '.
43
-
'adopt them.');
44
-
}
45
-
46
35
final protected function defineParamTypes() {
47
36
return array(
48
37
'queryKey' => 'optional string',
-11
src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
-11
src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
···
11
11
return PhabricatorApplication::getByClass($class);
12
12
}
13
13
14
-
public function getMethodStatus() {
15
-
return self::METHOD_STATUS_UNSTABLE;
16
-
}
17
-
18
-
public function getMethodStatusDescription() {
19
-
return pht(
20
-
'ApplicationEditor methods are fairly stable, but were introduced '.
21
-
'relatively recently and may continue to evolve as more applications '.
22
-
'adopt them.');
23
-
}
24
-
25
14
final protected function defineParamTypes() {
26
15
return array(
27
16
'transactions' => 'list<map<string, wild>>',