From 128995f1acd38f6a6f49684229a17f1b0dc9efcc Mon Sep 17 00:00:00 2001 From: epriestley Date: Thu, 28 Apr 2016 13:34:09 -0700 Subject: [PATCH] Document all the hypothetical URI features we plan to support soon Summary: Ref T10748. Ref T10366. This documents how everything is planned to work shortly. Test Plan: Read documentation. Reviewers: chad Reviewed By: chad Subscribers: eadler, scode Maniphest Tasks: T10366, T10748 Differential Revision: https://secure.phabricator.com/D15817 --- .../storage/PhabricatorRepositoryURI.php | 57 ++--- .../user/userguide/diffusion_uris.diviner | 232 +++++++++++++++++- 2 files changed, 255 insertions(+), 34 deletions(-) diff --git a/src/applications/repository/storage/PhabricatorRepositoryURI.php b/src/applications/repository/storage/PhabricatorRepositoryURI.php index 9aeb0c6868..364aad0a29 100644 --- a/src/applications/repository/storage/PhabricatorRepositoryURI.php +++ b/src/applications/repository/storage/PhabricatorRepositoryURI.php @@ -105,7 +105,7 @@ final class PhabricatorRepositoryURI public function getEffectiveDisplayType() { $display = $this->getDisplayType(); - if ($display != self::IO_DEFAULT) { + if ($display != self::DISPLAY_DEFAULT) { return $display; } @@ -116,47 +116,40 @@ final class PhabricatorRepositoryURI switch ($this->getEffectiveIOType()) { case self::IO_MIRROR: case self::IO_OBSERVE: - return self::DISPLAY_NEVER; case self::IO_NONE: - if ($this->isBuiltin()) { - return self::DISPLAY_NEVER; - } else { - return self::DISPLAY_ALWAYS; - } + return self::DISPLAY_NEVER; case self::IO_READ: case self::IO_READWRITE: // By default, only show the "best" version of the builtin URI, not the // other redundant versions. - if ($this->isBuiltin()) { - $repository = $this->getRepository(); - $other_uris = $repository->getURIs(); + $repository = $this->getRepository(); + $other_uris = $repository->getURIs(); - $identifier_value = array( - self::BUILTIN_IDENTIFIER_CALLSIGN => 3, - self::BUILTIN_IDENTIFIER_SHORTNAME => 2, - self::BUILTIN_IDENTIFIER_ID => 1, - ); + $identifier_value = array( + self::BUILTIN_IDENTIFIER_CALLSIGN => 3, + self::BUILTIN_IDENTIFIER_SHORTNAME => 2, + self::BUILTIN_IDENTIFIER_ID => 1, + ); - $have_identifiers = array(); - foreach ($other_uris as $other_uri) { - if ($other_uri->getIsDisabled()) { - continue; - } - - $identifier = $other_uri->getBuiltinIdentifier(); - if (!$identifier) { - continue; - } - - $have_identifiers[$identifier] = $identifier_value[$identifier]; + $have_identifiers = array(); + foreach ($other_uris as $other_uri) { + if ($other_uri->getIsDisabled()) { + continue; } - $best_identifier = max($have_identifiers); - $this_identifier = $identifier_value[$this->getBuiltinIdentifier()]; - - if ($this_identifier < $best_identifier) { - return self::DISPLAY_NEVER; + $identifier = $other_uri->getBuiltinIdentifier(); + if (!$identifier) { + continue; } + + $have_identifiers[$identifier] = $identifier_value[$identifier]; + } + + $best_identifier = max($have_identifiers); + $this_identifier = $identifier_value[$this->getBuiltinIdentifier()]; + + if ($this_identifier < $best_identifier) { + return self::DISPLAY_NEVER; } return self::DISPLAY_ALWAYS; diff --git a/src/docs/user/userguide/diffusion_uris.diviner b/src/docs/user/userguide/diffusion_uris.diviner index 3ff122e85e..b560f4ab3f 100644 --- a/src/docs/user/userguide/diffusion_uris.diviner +++ b/src/docs/user/userguide/diffusion_uris.diviner @@ -9,8 +9,8 @@ Overview WARNING: This document describes a feature which is still under development, and is not necessarily accurate or complete. -Phabricator can host, observe, mirror, and proxy repositories. For example, -here are some supported use cases: +Phabricator can create, host, observe, mirror, proxy, and import repositories. +For example, you can: **Host Repositories**: Phabricator can host repositories locally. Phabricator maintains the writable master version of the repository, and you can push and @@ -45,3 +45,231 @@ configuring URIs and marking them to be fetched from, mirrored to, clonable, and so on. By configuring all the URIs that a repository should interact with and expose to users, you configure the read, write, and mirroring behavior of the repository. + +The remainder of this document walks through this configuration in greater +detail. + + +Host a Repository +================= + +You can create new repositories that Phabricator will host, like you would +create repositories on services like GitHub or Bitbucket. Phabricator will +serve a read-write copy of the repository and you can clone it from Phabricator +and push changes to Phabricator. + +If you haven't already, you may need to configure Phabricator for hosting +before you can create your first hosted repository. For a detailed guide, +see @{article:Diffusion User Guide: Repository Hosting}. + +This is the default mode for new repositories. To host a repository: + + - Create a new repository. + - Activate it. + +Phabricator will create an empty repository and allow you to fetch from it and +push to it. + + +Observe a Repository +==================== + +If you have an existing repository hosted on another service (like GitHub, +Bitbucket, or a private server) that you want to work with in Phabricator, +you can configure Phabricator to observe it. + +When observing a repository, Phabricator will keep track of changes in the +remote repository and allow you to browse and interact with the repository from +the web UI in Diffusion and other applications, but you can continue hosting it +elsewhere. + +To observe a repository: + + - Create a new repository, but don't activate it yet. + - Add the remote URI you want to observe as a repository URI. + - Set the **I/O Type** for the URI to **Observe**. + - If necessary, configure a credential. + - Activate the repository. + +Phabricator will perform an initial import of the repository, creating a local +read-only copy. Once this process completes, it will continue keeping track of +changes in the remote, fetching them, and reflecting them in the UI. + + +Mirror a Repository +=================== + +NOTE: Mirroring is not supported in Subversion. + +You can create a read-only mirror of an existing repository. Phabricator will +push all changes made to the repository to the mirror. + +For example, if you have a repository hosted in Phabricator that you want to +mirror to GitHub, you can configure Phabricator to automatically maintain the +mirror. This is how the upstream repositories are set up. + +You can mirror any repository, even if Phabricator is only observing it and not +hosting it directly. + +To begin mirroring a repository: + + - Create a hosted or observed repository by following the relevant + instructions above. + - Add the remote URI you want to mirror to as a repository URI. + - Set the **I/O Type** for the URI to **Mirror**. + - If necessary, configure a credential. + +To stop mirroring: + + - Disable the mirror URI; or + - Change the **I/O Type** for the URI to **None**. + + +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 +**None** to stop fetching changes from the remote. + +By default, this will automatically make Phabricator's copy of the repository +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. + +**Copy on Disk**: //(Git, Mercurial, Subversion)// Create a new empty hosted +repository according to the instructions above, but do not activate it yet. + +Using the **Storage** tab, find the location of the repository's working copy +on disk, and place a working copy of the repository you wish to import there. + +For Git and Mercurial, use a bare working copy for best results. + +This is the only way to import a Subversion repository because only the master +copy of the repository has history. + +Once you've put a working copy in the right place on disk, activate the +repository. + + +Customizing Displayed Clone URIs +================================ + +If you have an unusual configuration and want the UI to offers users specific +clone URIs other than the URIs that Phabricator serves or interacts with, you +can add those URIs with the **I/O Type** set to **None** and then set their +**Display Type** to **Always**. + +Likewise, you can set the **Display Type** of any URIs you do //not// want +to be visible to **Never**. + +This allows you to precisely configure which clone URIs are shown to users for +a repository. + + +Reference: I/O Types +==================== + +This section details the available **I/O Type** options for URIs. + +Each repository has some **builtin** URIs. These are URIs hosted by Phabricator +itself. The modes available for each URI depend primarily on whether it is a +builtin URI or not. + +**Default**: This setting has Phabricator guess the correct option for the +URI. + +For **builtin** URIs, the default behavior is //Read/Write// if the repository +is hosted, and //Read-Only// if the repository is observed. + +For custom URIs, the default type is //None// because we can not automatically +guess if you want to ignore, observe, or mirror a URI and //None// is the +safest default. + +**Observe**: Phabricator will observe this repository and regularly fetch any +changes made to it to a local read-only copy. + +You can not observe builtin URIs because reading a repository from itself +does not make sense. + +You can not add a URI in Observe mode if an existing builtin URI is in +//Read/Write// mode, because this would mean the repository had two different +authorities: the observed remote copy and the hosted local copy. Take the +other URI out of //Read/Write// mode first. + +**Mirror**: Phabricator will push any changes made to this repository to the +remote URI, keeping a read-only mirror hosted at that URI up to date. + +This works for both observed and hosted repositories. + +This option is not available for builtin URIs because it does not make sense +to mirror a repository to itself. + +It is possible to mirror a repository to another repository that is also +hosted by Phabricator by adding that other repository's URI, although this is +silly and probably very rarely of any use. + +**None**: Phabricator will not fetch changes from or push changes to this URI. +For builtin URIs, it will not let users fetch changes from or push changes to +this URI. + +You can use this mode to turn off an Observe URI after an import, stop a Mirror +URI from updating, or to add URIs that you're only using to customize which +clone URIs are displayed to the user but don't want Phabricator to interact +with directly. + +**Read Only**: Phabricator will serve the repository from this URI in read-only +mode. Users will be able to fetch from it but will not be able to push to it. + +Because Phabricator must be able to serve the repository from URIs configured +in this mode, this option is only available for builtin URIs. + +**Read/Write**: Phabricator will serve the repository from this URI in +read/write mode. Users will be able to fetch from it and push to it. + +URIs can not be set into this mode if another URI is set to //Observe// mode, +because that would mean the repository had two different authorities: the +observed remote copy and the hosted local copy. Take the other URI out of +//Observe// mode first. + +Because Phabricator must be able to serve the repository from URIs configured +in this mode, this option is only available for builtin URIs. + + +Reference: Display Types +======================== + +This section details the available **Display Type** options for URIs. + +**Default**: Phabricator will guess the correct option for the URI. It +guesses based on the configured **I/O Type** and whether the URI is +**builtin** or not. + +For //Observe//, //Mirror// and //None// URIs, the default is //Never//. + +For builtin URIs in //Read Only// or //Read/Write// mode, the most +human-readable URI defaults to //Always// and the others default to //Never//. + +**Always**: This URI will be shown to users as a clone/checkout URI. You can +add URIs in this mode to cutomize exactly what users are shown. + +**Never**: This URI will not be shown to users. You can hide less-preferred +URIs to guide users to the URIs they should be using to interact with the +repository. + + +Next Steps +========== + +Continue by: + + - configuring Phabricator to host repositories with + @{article:Diffusion User Guide: Repository Hosting}.