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

Author: epriestley

src/__phutil_library_map__.php

@@ -1883,6 +1883,7 @@
     '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 @@
     'PhabricatorConduitAPIController' => 'PhabricatorConduitController',
     'PhabricatorConduitApplication' => 'PhabricatorApplication',
     'PhabricatorConduitCertificateToken' => 'PhabricatorConduitDAO',
+    'PhabricatorConduitConnectionLog' => 'PhabricatorConduitDAO',
     'PhabricatorConduitConsoleController' => 'PhabricatorConduitController',
     'PhabricatorConduitController' => 'PhabricatorController',
     'PhabricatorConduitDAO' => 'PhabricatorLiskDAO',

src/applications/conduit/storage/PhabricatorConduitConnectionLog.php

@@ -0,0 +1,26 @@
+<?php
+
+final class PhabricatorConduitConnectionLog extends PhabricatorConduitDAO {
+
+  protected $client;
+  protected $clientVersion;
+  protected $clientDescription;
+  protected $username;
+
+  protected function getConfiguration() {
+    return array(
+      self::CONFIG_COLUMN_SCHEMA => array(
+        'client' => 'text255?',
+        'clientVersion' => 'text255?',
+        'clientDescription' => 'text255?',
+        'username' => 'text255?',
+      ),
+      self::CONFIG_KEY_SCHEMA => array(
+        'key_created' => array(
+          'columns' => array('dateCreated'),
+        ),
+      ),
+    ) + parent::getConfiguration();
+  }
+
+}

src/applications/transactions/editengine/PhabricatorEditEngine.php

@@ -1431,6 +1431,7 @@ private function buildCommentResponse($object) {
     $editor = $object->getApplicationTransactionEditor()
       ->setActor($viewer)
       ->setContinueOnNoEffect($request->isContinueRequest())
+      ->setContinueOnMissingFields(true)
       ->setContentSourceFromRequest($request)
       ->setIsPreview($is_preview);
 

src/docs/tech/conduit.diviner

@@ -3,54 +3,26 @@
 
 Technical overview of the Conduit API.
 
-= Overview =
-
-Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on
-the internet.
-
-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.
-
-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.
-
-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.
-
-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.
-
-= 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}.
+Overview
+========
+
+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.
+
+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.
+
+The API console has details about how to construct calls and generate API
+tokens for authentication.
+
+The three primary ways to make Conduit calls are:
+
+  - `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`:
+
+There are also clients available in other languages. The Arcanist CLI client
+for Phabricator is implemented over Conduit.

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.