From 5c8dabdf8034f6fd51c461559ab54c908d77fe4c Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Fri, 8 Jul 2016 05:48:26 -0700
Subject: [PATCH] Add a strong hint about importing or observing repositories
 to repository creation

Summary: Fixes T11278. Also mention `svnsync`, since we have some evidence that it works.

Test Plan: {F1716250}

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T11278

Differential Revision: https://secure.phabricator.com/D16255
---
 .../DiffusionRepositoryEditController.php     | 23 ++++++-
 .../user/userguide/diffusion_existing.diviner | 68 +++++++++++++++++++
 .../user/userguide/diffusion_uris.diviner     | 10 +--
 3 files changed, 96 insertions(+), 5 deletions(-)
 create mode 100644 src/docs/user/userguide/diffusion_existing.diviner

diff --git a/src/applications/diffusion/controller/DiffusionRepositoryEditController.php b/src/applications/diffusion/controller/DiffusionRepositoryEditController.php
index b8892a94ea..d3801fa206 100644
--- a/src/applications/diffusion/controller/DiffusionRepositoryEditController.php
+++ b/src/applications/diffusion/controller/DiffusionRepositoryEditController.php
@@ -56,9 +56,30 @@ final class DiffusionRepositoryEditController
       $layout->addColumn($action);
     }
 
+    $hints = id(new AphrontMultiColumnView())
+      ->setFluidLayout(true);
+
+    $observe_href = PhabricatorEnv::getDoclink(
+      'Diffusion User Guide: Existing Repositories');
+
+    $hints->addColumn(
+      id(new PHUIActionPanelView())
+        ->setIcon('fa-book')
+        ->setHeader(pht('Import or Observe an Existing Repository'))
+        ->setHref($observe_href)
+        ->setSubheader(
+          pht(
+            'Review the documentation describing how to import or observe an '.
+            'existing repository.')));
+
     $view = id(new PHUITwoColumnView())
       ->setHeader($header)
-      ->setFooter($layout);
+      ->setFooter(
+        array(
+          $layout,
+          phutil_tag('br'),
+          $hints,
+        ));
 
     return $this->newPage()
       ->setTitle($title)
diff --git a/src/docs/user/userguide/diffusion_existing.diviner b/src/docs/user/userguide/diffusion_existing.diviner
new file mode 100644
index 0000000000..56226a84a1
--- /dev/null
+++ b/src/docs/user/userguide/diffusion_existing.diviner
@@ -0,0 +1,68 @@
+@title Diffusion User Guide: Existing Repositories
+@group userguide
+
+Quick guide for importing or observing existing repositories.
+
+
+Overview
+========
+
+If you have an existing repository, you can observe or import it into
+Diffusion.
+
+Observing a repository creates a read-only copy in Phabricator that is kept
+up to date by continuously importing new changes.
+
+Importing a repository creates a read-write copy.
+
+This document is a quick guide to getting started. For an overview of
+Diffusion, see @{article:Diffusion User Guide}. For a more detailed guide
+about managing repositories and URIs in Diffusion, see
+@{article:Diffusion User Guide: URIs}.
+
+
+Observing Repositories
+======================
+
+To observe an existing repository:
+
+  - Create a repository in Diffusion, but do not activate it yet.
+  - Add the URI for the existing repository you wish to observe in the
+    **URIs** section, in **Observe** mode.
+  - Activate the repository in Diffusion.
+
+This creates a read-only copy of the repository in Phabricator. Phabricator
+will keep its copy in sync with the remote by periodically polling the remote
+for changes.
+
+For more details, see @{article:Diffusion User Guide: URIs}.
+
+
+Importing Repositories
+======================
+
+There are two primary ways to import an existing repository:
+
+**Observe First**: In Git or Mercurial, you can observe the repository first.
+Once the import completes, disable the **Observe** URI to automatically convert
+it into a hosted repository.
+
+**Push to Empty Repository**: Create an activate an empty repository, then push
+all of your changes to empty the repository.
+
+In Git and Mercurial, you can do this with `git push` or `hg push`.
+
+In Subversion, you can do this with `svnsync`.
+
+For more details, see @{article:Diffusion User Guide: URIs}.
+
+
+Next Steps
+==========
+
+Continue by:
+
+  - reading an overview of Diffusion in
+    @{article:Diffusion User Guide}; or
+  - learning more about managing remote repository URIs in
+    @{article:Diffusion User Guide: URIs}.
diff --git a/src/docs/user/userguide/diffusion_uris.diviner b/src/docs/user/userguide/diffusion_uris.diviner
index 08be97b6b8..d1f4b541bc 100644
--- a/src/docs/user/userguide/diffusion_uris.diviner
+++ b/src/docs/user/userguide/diffusion_uris.diviner
@@ -135,10 +135,6 @@ Import a Repository
 If you have an existing repository that you want to move so it is hosted on
 Phabricator, there are three ways to do it:
 
-**Push Everything**: //(Git, Mercurial)// Create a new empty hosted repository
-according to the instructions above. Once the empty repository initializes,
-push your entire existing repository to it.
-
 **Observe First**: //(Git, Mercurial)// Observe the existing repository first,
 according to the instructions above. Once Phabricator's copy of the repository
 is fully synchronized, change the **I/O Type** for the **Observe** URI to
@@ -149,6 +145,12 @@ writable, and you can begin pushing to it. If you've adjusted URI
 configuration away from the defaults, you may need to set at least one URI
 to **Read/Write** mode so you can push to it.
 
+**Push Everything**: //(Git, Mercurial, Subversion)// Create a new empty hosted
+repository according to the instructions above. Once the empty repository
+initializes, push your entire existing repository to it.
+
+In Subversion, you can do this with the `svnsync` tool.
+
 **Copy on Disk**: //(Git, Mercurial, Subversion)// Create a new empty hosted
 repository according to the instructions above, but do not activate it yet.