Document API management of repositories and fix some issues with creating URIs via API

Summary:
Ref T10923. Primarily documents the process for creating repositories via the API.

Also fixes a couple of issues with `repositoryPHID` not being set yet when creating URIs via the API.

Test Plan:
  - Followed all documented steps to create a new repository.
  - Created and edited some new URIs from the web workflow, too.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T10923

Differential Revision: https://secure.phabricator.com/D15870

src/applications/diffusion/editor/DiffusionURIEditor.php

@@ -3,6 +3,9 @@
 final class DiffusionURIEditor
   extends PhabricatorApplicationTransactionEditor {
 
+  private $repository;
+  private $repositoryPHID;
+
   public function getEditorApplicationClass() {
     return 'PhabricatorDiffusionApplication';
   }
@@ -115,6 +118,7 @@ final class DiffusionURIEditor
         break;
       case PhabricatorRepositoryURITransaction::TYPE_REPOSITORY:
         $object->setRepositoryPHID($xaction->getNewValue());
+        $object->attachRepository($this->repository);
         break;
       case PhabricatorRepositoryURITransaction::TYPE_CREDENTIAL:
         $object->setCredentialPHID($xaction->getNewValue());
@@ -151,6 +155,9 @@ final class DiffusionURIEditor
 
     switch ($type) {
       case PhabricatorRepositoryURITransaction::TYPE_REPOSITORY:
+        // Save this, since we need it to validate TYPE_IO transactions.
+        $this->repositoryPHID = $object->getRepositoryPHID();
+
         $missing = $this->validateIsEmptyTextField(
           $object->getRepositoryPHID(),
           $xactions);
@@ -208,6 +215,9 @@ final class DiffusionURIEditor
               $xaction);
             continue;
           }
+
+          $this->repository = $repository;
+          $this->repositoryPHID = $repository_phid;
         }
         break;
       case PhabricatorRepositoryURITransaction::TYPE_CREDENTIAL:
@@ -315,7 +325,7 @@ final class DiffusionURIEditor
           if ($no_observers || $no_readwrite) {
             $repository = id(new PhabricatorRepositoryQuery())
               ->setViewer(PhabricatorUser::getOmnipotentUser())
-              ->withPHIDs(array($object->getRepositoryPHID()))
+              ->withPHIDs(array($this->repositoryPHID))
               ->needURIs(true)
               ->executeOne();
             $uris = $repository->getURIs();

src/docs/user/userguide/diffusion.diviner

@@ -53,6 +53,10 @@ Diffusion repositories have an array of configurable options and behaviors. For
 details on the available options and guidance on managing and administrating
 repositories, see @{article:Diffusion User Guilde: Managing Repositories}.
 
+Repositories can also be managed via the API. For an overview on using the
+API to create and edit repositories, see
+@{article:Diffusion User Guide: Repositories API}.
+
 
 Repository Clustering
 =====================

src/docs/user/userguide/diffusion_api.diviner

@@ -0,0 +1,182 @@
+@title Diffusion User Guide: Repositories API
+@group userguide
+
+Managing repositories with the API.
+
+Overview
+========
+
+You can create and update Diffusion repositories using the Conduit API. This
+may be useful if you have a large number of existing repositories you want
+to import or apply bulk actions to.
+
+For an introduction to Conduit, see @{article:Conduit API Overview}.
+
+In general, you'll use these API methods:
+
+  - `diffusion.repository.edit`: Create and edit repositorie.
+  - `diffusion.uri.edit`: Create and edit repository URIs to configure
+    observation, mirroring, and cloning.
+
+To create a repository, you'll generally do this:
+
+  - Call `diffusion.repository.edit` to create a new object and configure
+    basic information.
+  - Optionally, call `diffusion.uri.edit` to add URIs to observe or mirror.
+  - Call `diffusion.repository.edit` to activate the repository.
+
+This workflow mirrors the workflow from the web UI. The remainder of this
+document walks through this workflow in greater detail.
+
+
+Create a Repository
+===================
+
+To create a repository, call `diffusion.repository.edit`, providing any
+properties you want to set. For simplicity these examples will use the
+builtin `arc call-conduit` client, but you can use whatever Conduit client
+you prefer.
+
+When creating a repository, you must provide a `vcs` transaction to choose
+a repository type, one of: `git`, `hg` or `svn`.
+
+You must also provide a `name`.
+
+Other properties are optional. Review the Conduit method documentation from the
+web UI for an exhaustive list.
+
+```
+$ echo '{
+  "transactions": [
+    {
+      "type": "vcs",
+      "value": "git"
+    },
+    {
+      "type": "name",
+      "value": "Poetry"
+    }
+  ]
+}' | arc call-conduit diffusion.repository.edit
+```
+
+If things work, you should get a result that looks something like this:
+
+```lang=json
+{
+  ...
+  "response": {
+    "object": {
+      "id": 1,
+      "phid": "PHID-REPO-7vm42oayez2rxcmpwhuv"
+    },
+    ...
+  }
+  ...
+}
+```
+
+If so, your new repository has been created. It hasn't been activated yet so
+it will not show up in the default repository list, but you can find it in the
+web UI by browsing to {nav Diffusion > All Repositories}.
+
+Continue to the next step to configure URIs.
+
+
+Configure URIs
+==============
+
+Now that the repository exists, you can add URIs to it. This is optional,
+and if you're creating a //hosted// repository you may be able to skip this
+step.
+
+However, if you want Phabricator to observe an existing remote, you'll
+configure it here by adding a URI in "Observe" mode. Use the PHID from the
+previous step to identify the repository you want to add a URI to, and call
+`diffusion.uri.edit` to create a new URI in Observe mode for the repository.
+
+You need to provide a `repository` to add the URI to, and the `uri` itself.
+
+To add the URI in Observe mode, provide an `io` transaction selecting
+`observe` mode.
+
+You may also want to provide a `credential`.
+
+```
+$ echo '{
+  "transactions": [
+    {
+      "type": "repository",
+      "value": "PHID-REPO-7vm42oayez2rxcmpwhuv"
+    },
+    {
+      "type": "uri",
+      "value": "https://github.com/epriestley/poems.git"
+    },
+    {
+      "type": "io",
+      "value": "observe"
+    }
+  ]
+}' | arc call-conduit diffusion.uri.edit
+```
+
+You should get a response that looks something like this:
+
+```lang=json
+{
+  ...
+  "response": {
+    "object": {
+      "id": 1,
+      "phid": "PHID-RURI-zwtho5o7h3m6rjzgsgrh"
+    },
+    ...
+  }
+  ...
+}
+```
+
+If so, your URI has been created. You can review it in the web UI, under
+{nav Manage Repository > URIs}.
+
+When satisfied, continue to the next step to activate the repository.
+
+
+Activate the Repository
+=======================
+
+Now that any URIs have been configured, activate the repository with another
+call to `diffusion.repository.edit`. This time, modify the existing repostitory
+instead of creating a new one:
+
+```
+$ echo '{
+  "objectIdentifier": "PHID-REPO-7vm42oayez2rxcmpwhuv",
+  "transactions": [
+    {
+      "type": "status",
+      "value": "active"
+    }
+  ]
+}' | arc call-conduit diffusion.repository.edit
+```
+
+If that goes through cleanly, you should be all set. You can review the
+repository from the web UI.
+
+
+Editing Repositories
+====================
+
+To edit an existing repository, apply changes normally with
+`diffusion.repository.edit`. For more details on using edit endpoints, see
+@{article:Conduit API: Using Edit Endpoints}.
+
+
+Next Steps
+==========
+
+Continue by:
+
+  - returning to the @{article:Diffusion User Guide}.