Document most of the new Diffusion management panel

Summary: Ref T10923. This isn't complete yet, but reduces lies and increases truths.

Test Plan: Read documentation, clicked new "Documentation" nav item.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T10923

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

src/__phutil_library_map__.php

@@ -754,6 +754,7 @@ phutil_register_library_map(array(
     'DiffusionRepositoryController' => 'applications/diffusion/controller/DiffusionRepositoryController.php',
     'DiffusionRepositoryDatasource' => 'applications/diffusion/typeahead/DiffusionRepositoryDatasource.php',
     'DiffusionRepositoryDefaultController' => 'applications/diffusion/controller/DiffusionRepositoryDefaultController.php',
+    'DiffusionRepositoryDocumentationManagementPanel' => 'applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php',
     'DiffusionRepositoryEditActivateController' => 'applications/diffusion/controller/DiffusionRepositoryEditActivateController.php',
     'DiffusionRepositoryEditConduitAPIMethod' => 'applications/diffusion/conduit/DiffusionRepositoryEditConduitAPIMethod.php',
     'DiffusionRepositoryEditController' => 'applications/diffusion/controller/DiffusionRepositoryEditController.php',
@@ -4973,6 +4974,7 @@ phutil_register_library_map(array(
     'DiffusionRepositoryController' => 'DiffusionController',
     'DiffusionRepositoryDatasource' => 'PhabricatorTypeaheadDatasource',
     'DiffusionRepositoryDefaultController' => 'DiffusionController',
+    'DiffusionRepositoryDocumentationManagementPanel' => 'DiffusionRepositoryManagementPanel',
     'DiffusionRepositoryEditActivateController' => 'DiffusionRepositoryEditController',
     'DiffusionRepositoryEditConduitAPIMethod' => 'PhabricatorEditEngineAPIMethod',
     'DiffusionRepositoryEditController' => 'DiffusionController',

src/applications/diffusion/controller/DiffusionRepositoryManageController.php

@@ -109,7 +109,7 @@ final class DiffusionRepositoryManageController
       $key = $panel->getManagementPanelKey();
       $label = $panel->getManagementPanelLabel();
       $icon = $panel->getManagementPanelIcon();
-      $href = $repository->getPathURI("manage/{$key}/");
+      $href = $panel->getPanelNavigationURI();
 
       $item = id(new PHUIListItemView())
         ->setKey($key)

src/applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php

@@ -0,0 +1,29 @@
+<?php
+
+final class DiffusionRepositoryDocumentationManagementPanel
+  extends DiffusionRepositoryManagementPanel {
+
+  const PANELKEY = 'documentation';
+
+  public function getManagementPanelLabel() {
+    return pht('Documentation');
+  }
+
+  public function getManagementPanelOrder() {
+    return 3000;
+  }
+
+  public function getManagementPanelIcon() {
+    return 'fa-book bluegrey';
+  }
+
+  public function buildManagementPanelContent() {
+    return null;
+  }
+
+  public function getPanelNavigationURI() {
+    return PhabricatorEnv::getDoclink(
+      'Diffusion User Guide: Managing Repositories');
+  }
+
+}

src/applications/diffusion/management/DiffusionRepositoryManagementPanel.php

@@ -139,5 +139,8 @@ abstract class DiffusionRepositoryManagementPanel
     return "/diffusion/edit/{$id}/page/{$page}/";
   }
 
+  public function getPanelNavigationURI() {
+    return $this->getPanelURI();
+  }
 
 }

src/applications/diffusion/management/DiffusionRepositoryURIsManagementPanel.php

@@ -6,7 +6,7 @@ final class DiffusionRepositoryURIsManagementPanel
   const PANELKEY = 'uris';
 
   public function getManagementPanelLabel() {
-    return pht('Clone / Fetch / Mirror');
+    return pht('URIs');
   }
 
   public function getManagementPanelIcon() {

src/docs/user/userguide/diffusion.diviner

@@ -1,18 +1,20 @@
 @title Diffusion User Guide
 @group userguide
 
-Guide to Diffusion, the Phabricator repository browser.
+Guide to Diffusion, the Phabricator application for hosting and browsing
+repositories.
 
-= Overview =
+Overview
+========
 
-Diffusion is a repository browser which allows you to explore source code in a
+Diffusion allows you to create repositories so that you can browse them from
-Subversion, Git, or Mercurial repository. It is somewhat similar to software
+the web and interact with them from other applications.
-like Trac and GitWeb.
 
-Diffusion can either import a read-only copy of repositories hosted somewhere
+Diffusion can host repositories locally, or observe existing remote
-else (for example, from GitHub, Bitbucket or existing hosting) or host
+repositories which are hosted elsewhere (for example, on GitHub, Bitbucket, or
-repositories within Phabricator. Hosted repositories support a variety of
+other existing hosting). Both types of repositories can be browsed and
-triggers and access controls.
+interacted with, but hosted repositories support some additional triggers
+and access controls which are not available for observed repositories.
 
 Diffusion is integrated with the other tools in the Phabricator suite. For
 instance:
@@ -24,10 +26,15 @@ instance:
   - for hosted repositories, Herald can enforce granular access control rules;
   - in all the tools, commit names are automatically linked.
 
-= Adding Repositories =
+The remainder of this document walks through creating, configuring, and
+managing repositories.
+
+
+Adding Repositories
+===================
 
 Repository administration is accomplished through Diffusion. You can use the
-web interface in Diffusion to import an external repository, or create a new
+web interface in Diffusion to observe an external repository or create a new
 hosted repository.
 
   - For hosted repositories, make sure you go through the setup instructions
@@ -35,64 +42,31 @@ hosted repository.
   - For all repositories, you'll need to be running the daemons. If you have
     not set them up yet, see @{article:Managing Daemons with phd}.
 
-By default, you must be an administrator to create a new repository.
+By default, you must be an administrator to create a new repository. You can
+change this in the application settings.
 
-= Repository Callsigns and Commit Names =
 
-Each repository is identified by a "callsign", which is a short uppercase string
+Managing Repositories
-like "P" (for Phabricator) or "ARC" (for Arcanist).
+=====================
 
-Each repository must have a unique callsign. Callsigns must be unique within
+Diffusion repositories have an array of configurable options and behaviors. For
-an install but do not need to be globally unique, so you are free to use the
+details on the available options and guidance on managing and administrating
-single-letter callsigns for brevity. For example, Facebook uses "E" for the
+repositories, see @{article:Diffusion User Guilde: Managing Repositories}.
-Engineering repository, "O" for the Ops repository, "Y" for a Yum package
-repository, and so on, while Phabricator uses "P", "ARC", "PHU" for libphutil,
-and "J" for Javelin. Keeping callsigns brief will make them easier to use, and
-the use of one-character callsigns is recommended if they are reasonably
-evocative and you have no more than 26 tracked repositories.
 
-The primary goal of callsigns is to namespace commits to SVN repositories: if
-you use multiple SVN repositories, each repository has a revision 1, revision 2,
-etc., so referring to them by number alone is ambiguous. However, even for Git
-they impart additional information to human readers and allow parsers to detect
-that something is a commit name with high probability (and allow distinguishing
-between multiple copies of a repository).
 
-Diffusion uses this callsign and information about the commit itself to generate
+Repository Clustering
-a commit name, like "rE12345" or "rP28146171ce1278f2375e3646a1e1ea3fd56fc5a3".
+=====================
-The "r" stands for "revision". It is followed by the repository callsign, and
-then a VCS-specific commit identifier (for SVN, the commit number; for Git and
-Mercurial, the commit hash). When writing the name of a Git commit you may
-abbreviate the hash, but note that hash collisions are probable for short prefix
-lengths. See this post on the LKML for a historical explanation of Git's
-occasional internal use of 7-character hashes:
 
-https://lkml.org/lkml/2010/10/28/287
+Phabricator repository hosts can be set up in a cluster configuration so you
+can lose hosts with minimal downtime and data loss. This is an advanced feature
+which most installs do not need to pursue.
 
-Because 7-character hashes are likely to collide for even moderately large
+To get started with clustering, see @{article:Clustering Introduction}. For
-repositories, Diffusion generally uses either a 16-character prefix (which makes
+details on repository clustering, see @{article:Cluster: Repositories}.
-collisions very unlikely) or the full 40-character hash (which makes collisions
-astronomically unlikely).
 
-= Running Diffusion Daemons =
 
-In most cases, it is sufficient to run:
+Next Steps
-
+==========
-  phabricator/bin/ $ ./phd start
-
-...to start the daemons. For a more in-depth explanation of `phd` and daemons,
-see @{article:Managing Daemons with phd}.
-
-NOTE: If you have an unusually large install with multiple web frontends, see
-notes in @{article:Managing Daemons with phd}.
-
-You can use the repository detail screen and the Daemon Console to monitor the
-daemons and their progress importing the repository. Small repositories should
-import quickly, while larger repositories may take some time. Commits should
-begin appearing in Diffusion within a few minutes for all but the largest
-repositories.
-
-= Next Steps =
 
 Continue by:
 

src/docs/user/userguide/diffusion_managing.diviner

@@ -0,0 +1,310 @@
+@title Diffusion User Guide: Managing Repositories
+@group userguide
+
+Guide to configuring and managing repositories in Diffusion.
+
+Overview
+========
+
+After you create a new repository in Diffusion or select **Manage Repository**
+from the main screen if an existing repository, you'll be taken to the
+repository management interface for that repository.
+
+On this interface, you'll find many options which allow you to configure the
+behavior of a repository. This document walks through the options.
+
+Basics
+======
+
+The **Basics** section of the management interface allows you to configure
+the repository name, description, and identifiers. You can also activate or
+deactivate the repository here, and configure a few other miscellaneous
+settings.
+
+Basics: Name
+============
+
+The repository name is a human-readable primary name for the repository. It
+does not need to be unique
+
+Because the name is not unique and does not have any meaningful restrictions,
+it's fairly ambiguous and isn't very useful as an identifier. The other basic
+information (primarily callsigns and short names) gives you control over
+repository identifiers.
+
+
+Basics: Callsigns
+=================
+
+Each repository can optionally be identified by a "callsign", which is a short
+uppercase string like "P" (for Phabricator) or "ARC" (for Arcanist).
+
+The primary goal of callsigns is to namespace commits to SVN repositories: if
+you use multiple SVN repositories, each repository has a revision 1, revision 2,
+etc., so referring to them by number alone is ambiguous.
+
+However, even for Git and Mercurial they impart additional information to human
+readers and allow parsers to detect that something is a commit name with high
+probability (and allow distinguishing between multiple copies of a repository).
+
+Configuring a callsign can make interacting with a commonly-used repository
+easier, but you may not want to bother assigning one to every repository if you
+have some similar, templated, or rarely-used repositories.
+
+If you choose to assign a callsign to a repository, it must be unique within an
+install but do not need to be globally unique, so you are free to use the
+single-letter callsigns for brevity. For example, Facebook uses "E" for the
+Engineering repository, "O" for the Ops repository, "Y" for a Yum package
+repository, and so on, while Phabricator uses "P", "ARC", "PHU" for libphutil,
+and "J" for Javelin. Keeping callsigns brief will make them easier to use, and
+the use of one-character callsigns is encouraged if they are reasonably
+evocative.
+
+If you configure a callsign like `XYZ`, Phabricator will activate callsign URIs
+and activate the callsign identifier (like `rXYZ`) for the repository. These
+more human-readable identifiers can make things a little easier to interact
+with.
+
+
+Basics: Short Name
+==================
+
+Each repository can optionally have a unique short name. Short names must be
+unique and have some minor restrictions to make sure they are unambiguous and
+appropriate for use as directory names and in URIs.
+
+
+Basics: Description
+===================
+
+You may optionally provide a brief (or, at your discretion, excruciatingly
+long) human-readable description of the repository. This description will be
+shown on the main repository page.
+
+You can also create a `README` file at the repository root (or in any
+subdirectory) to provide information about the repository. These formats are
+supported:
+
+| File Name         | Rendered As...
+|-------------------|---------------
+| `README`          | Plain Text
+| `README.txt`      | Plain Text
+| `README.remarkup` | Remarkup
+| `README.md`       | Remarkup
+| `README.rainbow`  | Rainbow
+
+
+Basics: Encoding
+================
+
+Before content from the repository can be shown in the web UI or embedded in
+other contexts like email, it must be converted to UTF-8.
+
+Most source code is written in UTF-8 or a subset of UTF-8 (like plain ASCII)
+already, so everything will work fine. The majority of repositories do not need
+to adjust this setting.
+
+If your repository is primarily written in some other encoding, specify it here
+so Phabricator can convert from it properly when reading content to embed in
+a webpage or email.
+
+
+Basics: Dangerous Changes
+=========================
+
+By default, repositories are protected against dangerous changes. Dangerous
+changes are operations which rewrite or destroy repository history (for
+example, by deleting or rewriting branches). Normally, these take the form
+of `git push --force` or similar.
+
+It is normally a good idea to leave this protection enabled because most
+scalable workflows rarely rewrite repository history and it's easy to make
+mistakes which are expensive to correct if this protection is disabled.
+
+If you do occasionally need to rewite published history, you can treat this
+option like a safety: disable it, perform required rewrites, then enable it
+again.
+
+If you fully disable this at the repository level, you can still use Herald to
+selectively protect certain branches or grant this power to a limited set of
+users.
+
+This option is only available in Git and Mercurial, because it is impossible
+to make dangerous changes in Subversion.
+
+This option has no effect if a repository is not hosted because Phabricator
+can not prevent dangerous changes in a remote repository it is merely
+observing.
+
+
+Basics: Deactivate Repository
+=============================
+
+Repositories can be deactivated. Deactivating a repository has these effects:
+
+  - the repository will no longer be updated;
+  - users will no longer be able to clone/fetch/checkout the repository;
+  - users will no longer be able to push to the repository; and
+  - the repository will be hidden from view in default queries.
+
+When repositories are created for the first time, they are deactivated. This
+gives you an opportuinty to customize settings, like adjusting policies or
+configuring a URI to observe. You must activate a repository before it will
+start working normally.
+
+
+Basics: Delete Repository
+=========================
+
+Repositories can not be deleted from the web UI, so this option is always
+disabled. Clicking it gives you information about how to delete a repository.
+
+Repositories can only be deleted from the command line, with `bin/remove`:
+
+```
+$ ./bin/remove destroy <repository>
+```
+
+WARNING: This command will issue you a dire warning about the severity of the
+action you are taking. Heed this warning. You are **strongly discouraged** from
+destroying repositories. Instead, deactivate them.
+
+
+Policies
+========
+
+The **Policies** section of the management interface allows you to review and
+manage repository access policies.
+
+You can configure granular access policies for each repository to control who
+can view, clone, administate, and push to the repository.
+
+
+Policies: View
+==============
+
+The view policy for a repository controls who can view the repository from
+the web UI and clone, fetch, or check it out from Phabricator.
+
+Users who can view a repository can also access the "Manage" interface to
+review information about the repository and examine the edit history, but can
+not make any changes.
+
+
+Policies: Edit
+==============
+
+The edit policy for a repository controls who can change repository settings
+using the "Manage" interface. In essence, this is permission to administrate
+the repository.
+
+You must be able to view a repository to edit it.
+
+You do not need this permission to push changes to a repository.
+
+
+Policies: Push
+==============
+
+The push policy for a repository controls who can push changes to the
+repository.
+
+This policy has no effect if Phabricator is not hosting the repository, because
+it can not control who is allowed to make changes to a remote repository it is
+merely observing.
+
+You must also be able to view a repository to push to it.
+
+You do not need to be able to edit a repository to push to it.
+
+Further restrictions on who can push (and what they can push) can be configured
+for hosted repositories with Herald, which allows you to write more
+sophisticated rules that evaluate when Phabricator receives a push. To get
+started with Herald, see @{article:Herald User Guide}.
+
+Additionally, Git and Mercurial repositories have a setting which allows
+you to **Prevent Dangerous Changes**. This setting is enabled by default and
+will prevent any users from pushing changes which rewrite or destroy history.
+
+
+URIs
+====
+
+The **URIs** panel allows you to add and manage URIs which Phabricator will
+fetch from, serve from, and push to.
+
+These options are covered in detail in @{article:Diffusion User Guide: URIs}.
+
+
+Repository Identifiers and Names
+================================
+
+Repositories have several short identifiers which you can use to refer to the
+repository. For example, if you use command-line administrative tools to
+interact with a repository, you'll provide one of these identifiers:
+
+```
+$ ./bin/repository update <identifier>
+```
+
+The identifiers available for a repository depend on which options are
+configured. Each repository may have several identifiers:
+
+  - An **ID** identifier, like `R123`. This is available for all repositories.
+  - A **callsign** identifier, like `rXY`. This is available for repositories
+    with a callsign.
+  - A **short name** identifier, like `xylophone`. This is available for
+    repositories with a short name.
+
+All three identifiers can be used to refer to the repository in cases where
+the intent is unambiguous, but only the first two forms work in ambiguous
+contexts.
+
+For example, if you type `R123` or `rXY` into a comment, Phabricator will
+recognize them as references to the repository. If you type `xylophone`, it
+assumes you mean the word "xylophone".
+
+Only the `R123` identifier is immutable: the others can be changed later by
+adjusting the callsign or short name for the repository.
+
+
+Commit Identifiers
+==================
+
+Diffusion uses repository identifiers and information about the commit itself
+to generate globally unique identifers for each commit, like `rE12345`.
+
+Each commit may have several identifiers:
+
+  - A repository **ID** identifier, like `R123:abcdef123...`.
+  - A repository **callsign** identifier, like `rXYZabcdef123...`. This only
+    works if a repository has a callsign.
+  - Any unique prefix of the commit hash.
+
+Git and Mercurial use commit hashes to identify commits, and Phabricator will
+recognize a commit if the hash prefix is unique and sufficiently long. Commit
+hashes qualified with a repository identifier must be at least 5 characters
+long; unqualified commit hashes must be at least 7 characters long.
+
+In Subversion, commit identifiers are sequential integers and prefixes can not
+be used to identify them.
+
+When rendering the name of a Git or Mercurial commit hash, Phabricator tends to
+shorten it to 12 characters. This "short length" is relatively long compared to
+Git itself (which often uses 7 characters). See this post on the LKML for a
+historical explanation of Git's occasional internal use of 7-character hashes:
+
+https://lkml.org/lkml/2010/10/28/287
+
+Because 7-character hashes are likely to collide for even moderately large
+repositories, Diffusion generally uses either a 12-character prefix (which makes
+collisions very unlikely) or the full 40-character hash (which makes collisions
+astronomically unlikely).
+
+
+Next Steps
+==========
+
+Continue by:
+
+  - returning to the @{article:Diffusion User Guide}.

src/docs/user/userguide/diffusion_updates.diviner

@@ -89,7 +89,7 @@ There are several ways to do this:
   - If your repository is hosted on Phabricator, this will also be done for you
     automatically.
   - You can schedule an update from the web interface, in Diffusion >
-    (Choose a Repository) > Edit Repository > Update Now.
+    (Choose a Repository) > Manage Repository > Status > Update Now.
   - You can make a call to the Conduit API method `diffusion.looksoon`. This
     hints to Phabricator that it should poll a repository as soon as it can.
     All of the other mechanisms do this under the hood.
@@ -109,7 +109,7 @@ Troubleshooting Updates
 You can manually run a repository update from the command line to troubleshoot
 issues, using the `--trace` flag to get full details:
 
-  phabricator/ $ ./bin/repository update --trace <callsign>
+  phabricator/ $ ./bin/repository update --trace <repository>
 
 To catch potential issues with permissions, run this command as the same user
 that the daemons run as.

src/docs/user/userguide/diffusion_uris.diviner

@@ -6,9 +6,6 @@ Guide to configuring repository URIs for fetching, cloning and mirroring.
 Overview
 ========
 
-WARNING: This document describes a feature which is still under development,
-and is not necessarily accurate or complete.
-
 Phabricator can create, host, observe, mirror, proxy, and import repositories.
 For example, you can: