From 34e85aaeb8b69cbd6c45dc5f3759a6706c3e11f8 Mon Sep 17 00:00:00 2001 From: epriestley Date: Mon, 9 May 2016 08:10:21 -0700 Subject: [PATCH] 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 | 2 + .../DiffusionRepositoryManageController.php | 2 +- ...RepositoryDocumentationManagementPanel.php | 29 ++ .../DiffusionRepositoryManagementPanel.php | 3 + ...DiffusionRepositoryURIsManagementPanel.php | 2 +- src/docs/user/userguide/diffusion.diviner | 94 ++---- .../user/userguide/diffusion_managing.diviner | 310 ++++++++++++++++++ .../user/userguide/diffusion_updates.diviner | 4 +- .../user/userguide/diffusion_uris.diviner | 3 - 9 files changed, 382 insertions(+), 67 deletions(-) create mode 100644 src/applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php create mode 100644 src/docs/user/userguide/diffusion_managing.diviner diff --git a/src/__phutil_library_map__.php b/src/__phutil_library_map__.php index 6b71b47c43..0b939aa459 100644 --- a/src/__phutil_library_map__.php +++ b/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', diff --git a/src/applications/diffusion/controller/DiffusionRepositoryManageController.php b/src/applications/diffusion/controller/DiffusionRepositoryManageController.php index 4f4624b70d..dcafbe8685 100644 --- a/src/applications/diffusion/controller/DiffusionRepositoryManageController.php +++ b/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) diff --git a/src/applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php b/src/applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php new file mode 100644 index 0000000000..add9cfe054 --- /dev/null +++ b/src/applications/diffusion/management/DiffusionRepositoryDocumentationManagementPanel.php @@ -0,0 +1,29 @@ +getPanelURI(); + } } diff --git a/src/applications/diffusion/management/DiffusionRepositoryURIsManagementPanel.php b/src/applications/diffusion/management/DiffusionRepositoryURIsManagementPanel.php index 45047dd4fe..5422d15779 100644 --- a/src/applications/diffusion/management/DiffusionRepositoryURIsManagementPanel.php +++ b/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() { diff --git a/src/docs/user/userguide/diffusion.diviner b/src/docs/user/userguide/diffusion.diviner index f3fa53da3b..19fd0a70c2 100644 --- a/src/docs/user/userguide/diffusion.diviner +++ b/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 -Subversion, Git, or Mercurial repository. It is somewhat similar to software -like Trac and GitWeb. +Diffusion allows you to create repositories so that you can browse them from +the web and interact with them from other applications. -Diffusion can either import a read-only copy of repositories hosted somewhere -else (for example, from GitHub, Bitbucket or existing hosting) or host -repositories within Phabricator. Hosted repositories support a variety of -triggers and access controls. +Diffusion can host repositories locally, or observe existing remote +repositories which are hosted elsewhere (for example, on GitHub, Bitbucket, or +other existing hosting). Both types of repositories can be browsed and +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 -like "P" (for Phabricator) or "ARC" (for Arcanist). +Managing Repositories +===================== -Each repository must have a unique callsign. Callsigns 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 recommended if they are reasonably -evocative and you have no more than 26 tracked repositories. +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}. -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 -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: +Repository Clustering +===================== -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 -repositories, Diffusion generally uses either a 16-character prefix (which makes -collisions very unlikely) or the full 40-character hash (which makes collisions -astronomically unlikely). +To get started with clustering, see @{article:Clustering Introduction}. For +details on repository clustering, see @{article:Cluster: Repositories}. -= Running Diffusion Daemons = -In most cases, it is sufficient to run: - - 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 = +Next Steps +========== Continue by: diff --git a/src/docs/user/userguide/diffusion_managing.diviner b/src/docs/user/userguide/diffusion_managing.diviner new file mode 100644 index 0000000000..c3492c507a --- /dev/null +++ b/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 +``` + +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 +``` + +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}. diff --git a/src/docs/user/userguide/diffusion_updates.diviner b/src/docs/user/userguide/diffusion_updates.diviner index eb01b8c9bc..7012e6228e 100644 --- a/src/docs/user/userguide/diffusion_updates.diviner +++ b/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 + phabricator/ $ ./bin/repository update --trace To catch potential issues with permissions, run this command as the same user that the daemons run as. diff --git a/src/docs/user/userguide/diffusion_uris.diviner b/src/docs/user/userguide/diffusion_uris.diviner index fc045f9704..218b8182ef 100644 --- a/src/docs/user/userguide/diffusion_uris.diviner +++ b/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: