From c19654db161b8d2762013d41a47d8da5ea05a26d Mon Sep 17 00:00:00 2001 From: epriestley Date: Mon, 14 Dec 2015 14:36:47 -0800 Subject: [PATCH] Write some basic "dealing with Conduit changes" documentation Summary: Ref T9980. No magic here, just write a little bit about how to find outdated callers. Update the technical doc. Also: - Fix an unrelated bug where you couldn't leave comments if an object had missing, required, custom fields. - Restore the ConduitConnectionLog table so `bin/storage adjust` doesn't complain. Test Plan: Read docs. Reviewers: chad Reviewed By: chad Maniphest Tasks: T9980 Differential Revision: https://secure.phabricator.com/D14784 --- src/__phutil_library_map__.php | 2 + .../PhabricatorConduitConnectionLog.php | 26 ++++++++ .../editengine/PhabricatorEditEngine.php | 1 + src/docs/tech/conduit.diviner | 62 +++++-------------- src/docs/user/field/conduit_changes.diviner | 51 +++++++++++++++ 5 files changed, 97 insertions(+), 45 deletions(-) create mode 100644 src/applications/conduit/storage/PhabricatorConduitConnectionLog.php create mode 100644 src/docs/user/field/conduit_changes.diviner diff --git a/src/__phutil_library_map__.php b/src/__phutil_library_map__.php index 89a84669c6..03f2f47062 100644 --- a/src/__phutil_library_map__.php +++ b/src/__phutil_library_map__.php @@ -1883,6 +1883,7 @@ phutil_register_library_map(array( 'PhabricatorConduitAPIController' => 'applications/conduit/controller/PhabricatorConduitAPIController.php', 'PhabricatorConduitApplication' => 'applications/conduit/application/PhabricatorConduitApplication.php', 'PhabricatorConduitCertificateToken' => 'applications/conduit/storage/PhabricatorConduitCertificateToken.php', + 'PhabricatorConduitConnectionLog' => 'applications/conduit/storage/PhabricatorConduitConnectionLog.php', 'PhabricatorConduitConsoleController' => 'applications/conduit/controller/PhabricatorConduitConsoleController.php', 'PhabricatorConduitController' => 'applications/conduit/controller/PhabricatorConduitController.php', 'PhabricatorConduitDAO' => 'applications/conduit/storage/PhabricatorConduitDAO.php', @@ -5996,6 +5997,7 @@ phutil_register_library_map(array( 'PhabricatorConduitAPIController' => 'PhabricatorConduitController', 'PhabricatorConduitApplication' => 'PhabricatorApplication', 'PhabricatorConduitCertificateToken' => 'PhabricatorConduitDAO', + 'PhabricatorConduitConnectionLog' => 'PhabricatorConduitDAO', 'PhabricatorConduitConsoleController' => 'PhabricatorConduitController', 'PhabricatorConduitController' => 'PhabricatorController', 'PhabricatorConduitDAO' => 'PhabricatorLiskDAO', diff --git a/src/applications/conduit/storage/PhabricatorConduitConnectionLog.php b/src/applications/conduit/storage/PhabricatorConduitConnectionLog.php new file mode 100644 index 0000000000..498bb6ecfa --- /dev/null +++ b/src/applications/conduit/storage/PhabricatorConduitConnectionLog.php @@ -0,0 +1,26 @@ + array( + 'client' => 'text255?', + 'clientVersion' => 'text255?', + 'clientDescription' => 'text255?', + 'username' => 'text255?', + ), + self::CONFIG_KEY_SCHEMA => array( + 'key_created' => array( + 'columns' => array('dateCreated'), + ), + ), + ) + parent::getConfiguration(); + } + +} diff --git a/src/applications/transactions/editengine/PhabricatorEditEngine.php b/src/applications/transactions/editengine/PhabricatorEditEngine.php index 69490faeb4..eeaef34d48 100644 --- a/src/applications/transactions/editengine/PhabricatorEditEngine.php +++ b/src/applications/transactions/editengine/PhabricatorEditEngine.php @@ -1431,6 +1431,7 @@ abstract class PhabricatorEditEngine $editor = $object->getApplicationTransactionEditor() ->setActor($viewer) ->setContinueOnNoEffect($request->isContinueRequest()) + ->setContinueOnMissingFields(true) ->setContentSourceFromRequest($request) ->setIsPreview($is_preview); diff --git a/src/docs/tech/conduit.diviner b/src/docs/tech/conduit.diviner index af6c5b12b9..c31473b684 100644 --- a/src/docs/tech/conduit.diviner +++ b/src/docs/tech/conduit.diviner @@ -3,54 +3,26 @@ Technical overview of the Conduit API. -= Overview = +Overview +======== -Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on -the internet. +Conduit is the HTTP API for Phabricator. It is roughly JSON-RPC: you usually +pass a JSON blob, and usually get a JSON blob back, although both call and +result formats are flexible in some cases. -Theoretically, it provides an API to Phabricator so external scripts (including -scripts written in other languages) can interface with the applications in the -Phabricator suite. It technically does this, sort of, but it is unstable and -incomplete so you should keep your expectations very low if you choose to build -things on top of it. +The easiest way to begin exploring Conduit is by visiting {nav Conduit} in the +web UI. The application provides an API console which you can use to explore +available methods, make calls, read documentation, and see examples. -NOTE: Hopefully, this should improve over time, but making Conduit more robust -isn't currently a major project priority because there isn't much demand for it -outside of internal scripts. If you want to use Conduit to build things on top -of Phabricator, let us know so we can adjust priorities. +The API console has details about how to construct calls and generate API +tokens for authentication. -Conduit provides an authenticated HTTP API for Phabricator. It is informal and -extremely simple: you post a JSON blob and you get a JSON blob back. You can -access Conduit in PHP with @{class@libphutil:ConduitClient}, or in any language -by executing `arc call-conduit method` (see `arc help call-conduit` for -more information). You can see and test available methods at `/conduit/` in -the web interface. +The three primary ways to make Conduit calls are: -Arcanist is implemented using Conduit, and @{class:PhabricatorBot} is -intended as a practical example of how to write a program which interfaces with -Phabricator over Conduit. + - `arc call-conduit`: You can use this `arc` command to execute low-level + Conduit calls. + - `curl`: You can format a call with basic HTTP parameters and cURL. + - `ConduitClient`: -= Class Relationships = - -The primary Conduit workflow is exposed at `/api/`, which routes to -@{class:PhabricatorConduitAPIController}. This controller builds a -@{class:ConduitAPIRequest} representing authentication information and POST -parameters, instantiates an appropriate subclass of @{class:ConduitAPIMethod}, -and passes the request to it. Subclasses of @{class:ConduitAPIMethod} implement -the actual methods which Conduit exposes. - -Conduit calls which fail throw @{class:ConduitException}, which the controller -handles. - -There is a web interface for viewing and testing Conduit called the "Conduit -Console", implemented by @{class:PhabricatorConduitConsoleController} at -`/conduit/`. - -A log of connections and calls is stored in -@{class:PhabricatorConduitMethodCallLog}, and can be accessed on the web via -@{class:PhabricatorConduitLogController} at `/conduit/log/`. - -Conduit provides a token-based handshake mechanism used by -`arc install-certificate` at `/conduit/token/`, implemented by -@{class:PhabricatorConduitTokenController} which stores generated tokens using -@{class:PhabricatorConduitCertificateToken}. +There are also clients available in other languages. The Arcanist CLI client +for Phabricator is implemented over Conduit. diff --git a/src/docs/user/field/conduit_changes.diviner b/src/docs/user/field/conduit_changes.diviner new file mode 100644 index 0000000000..3b78490546 --- /dev/null +++ b/src/docs/user/field/conduit_changes.diviner @@ -0,0 +1,51 @@ +@title Managing Conduit Changes +@group fieldmanual + +Help with managing Conduit API changes. + +Overview +======== + +Many parts of the Conduit API are stable, but some parts are subject to change. +For example, when we write a new application, it usually adds several new API +methods and may update older methods. + +This document discusses API stability and how to minimize disruption when +transitionig between API versions. + + +Method Statuses +=============== + +Methods have one of three statuses: + + - **Unstable**: This is a new or experimental method which is subject to + change. You may call these methods to get access to recently released + features, but should expect that you may need to adjust your usage of + them before they stabilize. + - **Stable**: This is an established method which generally will not change. + - **Deprecated**: This method will be removed in a future version of + Phabricator and callers should cease using it. + +Normally, a method is deprecated only when it is obsolete or a new, more +powerful method is available to replace it. + + +Finding Deprecated Calls +======================== + +You can identify calls to deprecated methods in {nav Conduit > Call Logs}. +Use {nav My Deprecated Calls} to find calls to deprecated methods you have +made, and {nav Deprecated Call Logs} to find deprecated calls by all users. + +You can also search for calls by specific users. For example, it may be useful +to serach for any bot accounts you run to make sure they aren't calling +outdated APIs. + +The most common cause of calls to deprecated methods is users running very +old versions of Arcanist. They can normally upgrade by running `arc upgrade`. + +When the changelogs mention a method deprecation, you can use the call logs +to identify callers and notify them to upgrade or switch away. When the +changelogs mention a method removal, you can use the call logs to verify that +you will not be impacted.