diff --git a/docs/manual/admin/configuration/index.rst b/docs/manual/admin/configuration/index.rst index d2fffee1f27cae43e7faa4d75b86843f4ae9542d..721efe46a39861a82a64850e9959e477d861afaf 100644 --- a/docs/manual/admin/configuration/index.rst +++ b/docs/manual/admin/configuration/index.rst @@ -10,7 +10,7 @@ Configuration email default-reviewers permission-groups - repositories + repositories/index review-groups users webhooks diff --git a/docs/manual/admin/configuration/repositories.rst b/docs/manual/admin/configuration/repositories/index.rst similarity index 67% rename from docs/manual/admin/configuration/repositories.rst rename to docs/manual/admin/configuration/repositories/index.rst index 063163e31fa689b1e40f557e27d7fa842b26004e..dd20143d77b3e49693b577d2a978cceb6d1214e2 100644 --- a/docs/manual/admin/configuration/repositories.rst +++ b/docs/manual/admin/configuration/repositories/index.rst @@ -152,8 +152,6 @@ listed will depend on the requirements of the hosting service. :guilabel:`(None - Custom Repository)` and `Repository type`_ is set to :guilabel:`Git`. - See :ref:`raw-file-urls` below for more information. - .. _`Username and Password fields`: .. _`Username field`: @@ -364,200 +362,16 @@ you're configuring. This section provides some help for determining which value to use. -ClearCase ---------- - -Review Board works with local ClearCase dynamic views, by utilizing -version-extended paths to access specific file revisions. - -The `Path field`_ should point to the particular VOB, which must be an -absolute path starting with a drive letter on Windows or a mount point on -Unix/Linux. - -The `Username and Password fields`_ should be blank. - -.. note:: When uploading new diffs, Review Board will compare the VOBs by UUID. - If the UUID doesn't match, :command:`post-review` will use the VOB's - name as the repository name. Because of this, it is a good idea to - name the repositories in Review Board to match the VOB names. - - -CVS ---- - -Review Board supports several methods of connecting to a CVS server. In -particular, the following connection types can be used: - -* ``:ext:`` -* ``:fork:`` -* ``:gserver:`` -* ``:kserver:`` -* ``:local:`` -* ``:pserver:`` -* ``:server:`` - -If you use one of these connection types and provide it for the `Path field`_, -you won't need to fill in the `Username and Password fields`_. - -If you user ``:pserver:``, ``:gserver:``, or ``:kserver:``, you can opt not to -include the username or password in the string, and just fill them in in the -form. - -Some example of valid paths include: - -* ``:pserver:cvs.example.com/cvsroot`` -* ``:pserver:anonymous@cvs.example.com/cvsroot`` -* ``:pserver:myuser:mypass@cvs.example.com:1234/cvsroot`` -* ``:local:C:\CVSROOTS\myproject`` - - -To determine the path of an existing checkout, you can go to the top-most -directory of the checkout and type:: - - $ cat CVS/Root - -You should use the contents of this file as the repository path, adjusting the -username, password or path as necessary. - - -Git ---- - -In order to use Git with Review Board, you'll need either a local clone -on the server, or by using raw file URLs to a web front-end to Git (cgit, -Gitweb, etc.) on the Git server. Git doesn't have a way of fetching an -individual file of a given revision from a remote server without having an -entire clone, so it works differently from other repository types. - - -Local Clone -~~~~~~~~~~~ - -In order to work with Review Board, a local clone needs to be kept in -sync regularly. It should either have direct access to a central Git -server, or it needs to be updated on every commit to the central Git -server. - -The `Path field`_ should be the full path of the ``.git`` directory inside -this checkout. For example: ``/var/git/projectname/.git`` - -The `Mirror path field`_ should contain the repository URL. Find the URL you -should use from within a git checkout by running the following:: - - $ git remote show origin - -The value shown as ``URL:`` should be entered as the mirror path. For -example: ``git@git.example.com:projectname.git`` - -The `Username and Password fields`_ should be blank. - - -.. _raw-file-urls: - -Raw File URLs -~~~~~~~~~~~~~ - -.. versionadded:: 1.5 - -Review Board can access a remote file by talking to a cgit or gitweb server. -This is done by filling out the `Raw file URL mask`_ field to tell Review -Board how to access a single file based on revision. - -The URL can make use of the following tags, which will be replaced before -attempting to fetch the file: - -* ```` - The full SHA1 of the file blob. -* ```` - The unescaped path to the file. - -cgit -^^^^ - -For cgit, this path should be in the form of: - -:samp:`http://{servername}/browse/repo/blob/?id=` - -For example: - -:samp:`http://git.gnome.org/browse/gtk+/blob/?id=` - - -Gitweb -^^^^^^ - -For Gitweb: - -:samp:`http://{servername}/?p={relative path to git repo};a=blob_plain;f=;h=` - -For example: - -:samp:`http://git.kernel.org/?p=bluetooth/bluez-gnome.git;a=blob_plain;f=;h=` - - -Perforce --------- - -The Perforce path can be retrieved from an existing Perforce checkout by -typing the following:: - - $ p4 info - -Use the value from the :guilabel:`Server address` field. - -In most setups, the `Username field`_ must be provided. This must be a user -that has access to the whole repository. In some setups, this is a dedicated -read-only user. - -Note that Review Board will only ever use this user for read-only operations. -It will never write to the repository. - - -.. _perforce-stunnel: - -Using Perforce with stunnel -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.6 - -Perforce can be configured to operate with a secure stunnel setup. This is -particularly important if the server running Review Board needs to talk to -the Perforce server over the Internet or an otherwise easily accessible -network. - -To set up an stunnel connection on the Perforce server, see Perforce's guide -on `Using Stunnel with Perforce`_. - -.. _`Using Stunnel with Perforce`: - http://kb.perforce.com/article/1018/using-stunnel-with-perforce - -Once the server is set up, ensure that stunnel version 3 (not 4) is installed on -the server running Review Board and available in the web server's PATH. You can -then configure your repository settings so that Review Board can access the -repository. To do this, just prefix your repository path with ``stunnel:`` and -list the port that the stunnel server is running on. For example:: - - stunnel:perforce.example.com:2666 - -Review Board will automatically set up a local tunnel client as necessary. -It will bind this to a port between 30000 and 60000 on localhost, and proxy -all requests through it. - - -Subversion ----------- - -The Subversion path can be retrieved from an existing Subversion checkout by -typing the following:: - - $ svn info - -Use the value from the :guilabel:`Repository Root` field. +Configuring Repositories +======================== -In most server setups, Subversion provides anonymous access, so the -`Username and Password fields`_ won't need to be filled out. However, this -depends on the server setup. Some are more restricted and will require a -dedicated user. +.. toctree:: + :maxdepth: 1 -In Subversion setups where there's a public anonymous URL and a secured -developer URL (such as one using ``https`` or ``svn+ssh``), you -should put the public URL in :guilabel:`Path` field and -your developer URL in the :guilabel:`Mirror Path`. + bazaar + clearcase + cvs + git + mercurial + perforce + subversion diff --git a/docs/manual/admin/configuration/repositories/bazaar.rst b/docs/manual/admin/configuration/repositories/bazaar.rst new file mode 100644 index 0000000000000000000000000000000000000000..acea7ccb0ed74b560aa8da4016f362ae385dfa4b --- /dev/null +++ b/docs/manual/admin/configuration/repositories/bazaar.rst @@ -0,0 +1,63 @@ +.. _repository-scm-bazaar: + +=================== +Bazaar Repositories +=================== + +Review Board supports posting and reviewing code on :rbintegration:`Bazaar +` repositories. + +To simplify posting changes to Review Board, we recommend using RBTools_. This +ensures that the diffs are in the correct format, and makes managing review +requests much easier. + +.. todo: Add a link to RBTools docs for Bazaar, once written. + +.. note:: + + This guide assumes that you're adding a Bazaar repository that's hosted + somewhere in your network or one that's accessible by your Review Board + server. Review Board requires local or network access to your repository. + + Follow the documentation in the links below if your Bazaar repository is + hosted on one of these services, as configuration may differ. + + * :ref:`SourceForge ` + + +.. _RBTools: https://www.reviewboard.org/downloads/rbtools/ + + +Installing Bazaar Support +========================= + +Before you add the repository, you will need to install Bazaar on the server. +We recommend installing this using the Python packages instead of your +distribution packages. + +To install Bazaar, run:: + + $ pip install bzr + + +Adding the Repository +===================== + +To configure a Bazaar repository, first proceed to :ref:`add the repository +` and select :guilabel:`Bazaar` from the +:guilabel:`Repository type` field. + +You can then enter any valid Bazaar repository path into the :guilabel:`Path` +field. If your repository may be used at an additional path, you can also +provide an additional path for lookup matching purposes in a :guilabel:`Mirror +path`. + + +Using SSH-Backed Reposoitories +------------------------------ + +If you're using a Bazaar repository over a SSH connection, you will need to +:ref:`configure a SSH key ` in Review Board, and grant access on +the repository. You will also need to specify a username, either in the +repository path or in the :guilabel:`Username` field. The password field can +usually be left blank. diff --git a/docs/manual/admin/configuration/repositories/clearcase.rst b/docs/manual/admin/configuration/repositories/clearcase.rst new file mode 100644 index 0000000000000000000000000000000000000000..4f7481bcd35d79b0374eac92cf5a379b45a2b76f --- /dev/null +++ b/docs/manual/admin/configuration/repositories/clearcase.rst @@ -0,0 +1,55 @@ +.. _repository-scm-clearcase: + +====================== +ClearCase Repositories +====================== + +.. note:: + + ClearCase support is community-driven. If you have improvements you want + to see, or hit any problems, please discuss them on the + `community support list`_. + +Review Board supports posting and reviewing code on :rbintegration:`ClearCase +` repositories. Each ClearCase VOB needs its own repository in +Review Board. + +To post changes for review, you will need to use RBTools_. This will generate +a diff suitable for posting to Review Board. See :ref:`Using RBTools with +ClearCase ` for more information. + + +.. _community support list: https://groups.google.com/group/reviewboard +.. _RBTools: https://www.reviewboard.org/downloads/rbtools/ + + +Installing ClearCase Support +============================ + +Before you add the repository, you will need to make sure the +:command:`cleartool` command from ClearCase client is in your system path (or +in a place accessible by your web server's process). + + +Adding the Repository +===================== + +To configure a ClearCase repository, first proceed to :ref:`add the repository +` and select :guilabel:`ClearCase` from the +:guilabel:`Repository type` field. + +You will see a :guilabel:`Path` field, which should contain the VOB path for +your repository, representing either a `snapshot or dynamic view`_. The VOB +path must be an absolute path. On Windows, this must include the drive letter. +On Linux/UNIX, this must include the full mount point. + + +.. _snapshot or dynamic view: + https://www-01.ibm.com/support/docview.wss?uid=swg21177694 + + +Examples +-------- + +* ``/vobs/myrepo`` +* ``C:\vobs\myrepo`` diff --git a/docs/manual/admin/configuration/repositories/cvs.rst b/docs/manual/admin/configuration/repositories/cvs.rst new file mode 100644 index 0000000000000000000000000000000000000000..1b88a37fa504961f90af6f262850608c6cfee9eb --- /dev/null +++ b/docs/manual/admin/configuration/repositories/cvs.rst @@ -0,0 +1,166 @@ +.. _repository-scm-cvs: + +================ +CVS Repositories +================ + +Review Board supports posting and reviewing code on :rbintegration:`CVS ` +repositories. All standard CVS repository configurations can be used. + +To simplify posting changes to Review Board, we recommend using RBTools_. This +ensures that the diffs are in the correct format and makes managing review +requests much easier. See :ref:`Using RBTools with CVS ` for more +information. + +.. note:: + + This guide assumes that you're adding a CVS repository that's hosted + somewhere in your network or one that's accessible by your Review Board + server. Review Board requires local or network access to your repository. + + Follow the documentation in the links below if your CVS repository is + hosted on one of these services, as configuration may differ. + + * :ref:`SourceForge ` + + +.. _RBTools: https://www.reviewboard.org/downloads/rbtools/ + + +Installing CVS Support +====================== + +Before you add the repository, you will need to install the :command:`cvs` +command line tool in a system path (or in a place accessible by your web +server's process). This can be installed through your system's package +manager. + +See the :ref:`installation guide ` for CVS. + + +Adding the Repository +===================== + +To configure a CVS repository, first proceed to :ref:`add the repository +` and select :guilabel:`CVS` from the +:guilabel:`Repository type` field. + +You will see a :guilabel:`Path` field, which should contain the CVSROOT +for your repository. This can use any of the following CVS connection methods: + +* :ref:`repository-scm-cvs-credential-cvsroots`: + + * ``:gserver:`` + * ``:kserver:`` + * ``:pserver:`` + +* :ref:`repository-scm-cvs-ssh-cvsroots`: + + * ``:ext:`` + * ``:extssh:`` + * ``:ssh:`` + +* :ref:`repository-scm-cvs-local-cvsroots`: + + * ``:fork:`` + * ``:local:`` + + +Determining Your CVSROOT +------------------------ + +To determine the CVSROOT of an existing checkout, you can go to the top-most +directory of the checkout and type:: + + $ cat CVS/Root + +This will show the CVSROOT used for your repository. You can use the value +as-is, or modify it to suit your needs. See below for more details. + + +.. _repository-scm-cvs-credential-cvsroots: + +Credential-Based CVSROOTs +------------------------- + +If you're using ``:pserver:``, ``:gserver:``, or ``:kserver:``, you're going +to need to specify credentials (a username and password) for your repository. +You can specify these credentials either in the :guilabel:`Path` field or in +the :guilabel:`Username` and :guilabel:`Password` fields. + +Credentials specified in :guilabel:`Username` and :guilabel:`Password` will +only be used if using ``:pserver:``, ``:gserver:``, or ``:kserver`` +connection methods, and if the credentials aren't already provided in +:guilabel:`Path`. + +.. tip:: + + Specify the credentials outside of the CVSROOT, if possible. This will + allow RBTools_ or other clients to locate your repository by CVSROOT, + which may not be possible if it contains a username or password. + + +Examples +~~~~~~~~ + +* ``:pserver:cvs.example.com/cvsroot`` +* ``:pserver:anonymous@cvs.example.com/cvsroot`` +* ``:pserver:myuser:mypass@cvs.example.com:1234/cvsroot`` + + +.. _repository-scm-cvs-ssh-cvsroots: + +SSH-Based CVSROOTs +------------------ + +If you're using ``:ext:``, ``:extssh:``, or ``:ssh:``, you will need to +:ref:`configure a SSH key ` in Review Board, and grant access on +the repository. You will also need the specify the username, either in the +CVSROOT or in the :guilabel:`Username` field. The :guilabel:`Password` field +must be blank. + +.. note:: + + The ``:server:`` connection method should not be used, as it makes use of + an internal SSH client that will not see your configured Review Board SSH + key. It's also not supported by all CVS implementations. + +.. tip:: + + If your repository has an alternative ``:pserver:`` (or other) CVSROOT that + people can use, you may want to specify it in the :guilabel:`Mirror path` + field. This is used only for path matching when looking up repositories. + + +Examples +~~~~~~~~ + +* ``:extssh:cvs.example.com:/cvsroot`` +* ``:ssh:localhost:22/cvsroot`` +* ``:ssh:username@cvs.example.com:/cvsroot`` +* ``:ext:username@cvs.example.com:/cvsroot`` +* ``:ext:username@cvs.example.com:/cvsroot`` +* ``:ext:cvs.example.com:/cvsroot`` + + +.. _repository-scm-cvs-local-cvsroots: + +Local CVSROOTs +-------------- + +If your repository lives on the same machine as Review Board, you can refer to +it by local path using ``:local:`` or ``:fork:``. + +.. tip:: + + You should specify the CVSROOT that users connecting to your server would + use in the :guilabel:`Mirror path` field. This is used only for path + matching when looking up repositories. + + +Examples +~~~~~~~~ + +* ``:local:C:\CVSROOTS\myproject`` +* ``:local:/home/myuser/cvsroot`` +* ``:fork:/home/myuser/cvsroot`` diff --git a/docs/manual/admin/configuration/repositories/git.rst b/docs/manual/admin/configuration/repositories/git.rst new file mode 100644 index 0000000000000000000000000000000000000000..d280b96ee6adcca51c48a5bb3365a12119a064c9 --- /dev/null +++ b/docs/manual/admin/configuration/repositories/git.rst @@ -0,0 +1,185 @@ +.. _repository-scm-git: + +================ +Git Repositories +================ + +Review Board supports posting and reviewing code on :rbintegration:`Git ` +repositories. + +Unlike most types of source code management systems, Git has a *very* limited +remote protocol, which isn't capable of some of the requests Review Board and +other similar tools require. Because of this, if Review Board does not have +local file-based access to your main Git repository, you will need to set up a +wrapping service, such as :ref:`GitWeb ` or +:ref:`cgit `. This is covered in more detail later in +this guide. + +To simplify posting changes to Review Board, we recommend using RBTools_. This +ensures that the diffs are in the correct format, and makes managing review +requests much easier. See :ref:`Using RBTools with Git ` for +more information. + +.. note:: + + This guide assumes that you're adding a Git repository that's hosted + somewhere in your network or one that's accessible by your Review Board + server. Review Board requires either local access to your repository or + network access using a wrapping service (as documented below). + + Follow the documentation in the links below if your Git repository is + hosted on one of these services, as configuration will differ. + + * :ref:`Assembla ` + * :ref:`Beanstalk ` + * :ref:`Bitbucket ` + * :ref:`Codebase ` + * :ref:`Fedora Hosted ` + * :ref:`GitHub ` + * :ref:`GitHub Enterprise ` + * :ref:`GitLab ` + * :ref:`Gitorious ` + * :ref:`Kiln ` + * :ref:`Unfuddle ` + + If your Git repository is hosted on another third-party service, it + will not work with Review Board! Please contact us to request support + for that service. + + +.. _RBTools: https://www.reviewboard.org/downloads/rbtools/ + + +Installing Git Support +====================== + +Before you add the repository, you will need to install the :command:`git` +command line tool in a system path (or in a place accessible by your web +server's process). This can be installed through your system's package +manager. + +See the :ref:`installation guide ` for Git. + + +Adding the Repository +===================== + +To configure a Git repository, first proceed to :ref:`add the repository +` and select :guilabel:`Git` from the +:guilabel:`Repository Type` field. + +If your repository is locally accessible over the file system via the Review +Board server, you can point to file path of the repository. However, there are +caveats. See :ref:`repository-scm-git-local-clone`. + +If your repository is within your network, you will need an intermediary Git +wrapping service, such as :ref:`GitWeb ` or +:ref:`cgit `. + +If your repository is instead hosted on a compatible source code hosting +service like :rbintegration:`GitHub ` or :rbintegration:`Bitbucket +`, you'll want to refer to the instructions on that service. See +:ref:`repository-scm-git-other-services` below. + + +.. _repository-scm-git-gitweb: + +Using a GitWeb-Backed Repository +-------------------------------- + +If you're self-hosting one or more Git repositories, you can `install GitWeb`_ +and use it as a form of remote API for Review Board. This will give you basic +support for posting and reviewing changes (though some features, like browsing +for commits on the :ref:`New Review Request page `, +will not work). + +Once you have GitWeb set up, you will want to set your :guilabel:`Path` field +to the main clone path of your repository. If you use both HTTPS and SSH +access to your repository, set one in :guilabel:`Path` and the other in +:guilabel:`Mirror Path`. + +If you're using an SSH-backed repository, you will need to :ref:`configure a +SSH key ` in Review Board, and grant access on the repository. + +You will then need to set the :guilabel:`Raw File URL Mask` field to point to +a specific URL on your GitWeb server. This field essentially specifies a +URL template that Review Board can fill in with a filename and Git blob SHA +that will return the contents of that file and blob. This should take the form +of: + +:samp:`https://{servername}/?p={relative_repo_path};a=blob_plain;f=;h=` + +For example, if your repository is configured in GitWeb as +``projects/myrepo.git`` and your GitWeb is at ``git.example.com``, you will +want to use: + +``https://git.example.com/?p=projects/myrepo.git;a=blob_plain;f=;h=`` + + +.. _install GitWeb: https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb + + +.. _repository-scm-git-cgit: + +Using a cgit-Backed Repository +------------------------------ + +One alternative to GitWeb would be to install cgit_. This works similarly to +GitWeb, in that it will make use of the :guilabel:`Raw File URL Mask` field. + +Follow the instructions in :ref:`repository-scm-git-gitweb`, but use the following +for the URL mask: + +:samp:`http://{servername}/browse/{repo_name}/blob/?id=` + +For example, if your repository name is ``myproject`` and your server name is +``git.example.com``, you would use: + +``http://git.example.com/browse/myproject/blob/?id=`` + + +.. seealso:: + + `cgit's Installation Instructions + `_ + + `Installing cgit on ArchLinux + `_ + + +.. _cgit: https://git.zx2c4.com/cgit/about/ +.. _install cgit: https://wiki.gnome.org/GnomeWeb/Tutorials/LocalGit + + +.. _repository-scm-git-local-clone: + +Using a Local Clone +------------------- + +Review Board can make use of a locally-accessible Git clone, so long as that +clone contains the very latest changes for your repository. This is an easy +way to configure a Git repository accessible over the filesystem. + +If the Git clone is the master repository that your developers are cloning +from, then you're in good shape. However, if it's a clone of the master +repository, you will need to ensure it's consistently up-to-date. One way to +do this would be to have a cron job pull the latest changes at least once a +minute. + +When using a local clone, you'll need to point the :guilabel:`Path` field to +the :file:`.git` directory within your clone. For example: +``/var/git/projectname/.git``. + +The :guilabel:`Mirror Path` field should then list the URL that developers +would normally clone from. This is usually a HTTPS or SSH-backed URL. It's +important to note that you can only list one (which should not normally be a +problem if you're using RBTools_ with name-based repository lookups, which we +recommend by default). + +To get the clone URL, you can run:: + + $ git remote show origin + +Then use the value shown in ``URL:``. + +You will leave the :guilabel:`Username` and :guilabel:`Password` fields blank. diff --git a/docs/manual/admin/configuration/repositories/mercurial.rst b/docs/manual/admin/configuration/repositories/mercurial.rst new file mode 100644 index 0000000000000000000000000000000000000000..e83d0b33e7697ba66be3b9b7cc5846c3e612875c --- /dev/null +++ b/docs/manual/admin/configuration/repositories/mercurial.rst @@ -0,0 +1,122 @@ +.. _repository-scm-mercurial: + +====================== +Mercurial Repositories +====================== + +Review Board supports posting and reviewing code on :rbintegration:`Mercurial +` repositories. + +To simplify posting changes to Review Board, we recommend using RBTools_. This +ensures that the diffs are in the correct format, and makes managing review +requests much easier. See :ref:`Using RBTools with Mercurial +` for more information. + +.. note:: + + This guide assumes that you're adding a Mercurial repository that's hosted + somewhere in your network or one that's accessible by your Review Board + server. Review Board requires either local access to your repository or + network access using hgweb (as documented below) or another hosting + service. + + Follow the documentation in the links below if your Mercurial repository is + hosted on one of these services, as configuration will differ. + + * :ref:`Bitbucket ` + * :ref:`Codebase ` + * :ref:`Fedora Hosted ` + * :ref:`Kiln ` + * :ref:`SourceForge ` + + If your Mercurial repository is hosted on another third-party service, it + may not work with Review Board! Please contact us to request support + for that service. + + +.. _RBTools: https://www.reviewboard.org/downloads/rbtools/ + + +Installing Mercurial Support +============================ + +Before you add the repository, you will need to install Mercurial on the +server. We recommend installing this using the Python packages instead of your +distribution packages. + +To install Mercurial, run:: + + $ pip install mercurial + + +Adding the Repository +===================== + +To configure a Mercurial repository, first proceed to :ref:`add the repository +` and select :guilabel:`Mercurial` from the +:guilabel:`Repository type` field. + +If your repository is within your network and accessed remotely, you will need +to enable hgweb_. You can then point to the ``http://`` or ``https://`` URL. +See :ref:`repository-scm-mercurial-hgweb`. + +If your repository is locally accessible over the file system via the Review +Board server, you can point to file path of the repository. However, there are +caveats. See :ref:`repository-scm-mercurial-local-clone`. + +If your repository is instead hosted on a compatible source code hosting +service like :rbintegration:`Bitbucket `, you'll want to refer to +the instructions on that service. See +:ref:`repository-scm-mercurial-other-services` below. + + +.. _hgweb: https://www.mercurial-scm.org/repo/hg/help/hgweb + + +.. _repository-scm-mercurial-hgweb: + +Using a hgweb-Backed Repository +------------------------------- + +If you have hgweb installed for your repository, you can point to the +``http://`` or ``https://`` URL for your repository. Review Board can use this +to fetch the files from the repository for review. + +To start, you'll need to install hgweb. You can follow `Mercurial's +documentation on hgweb`_. + +Once that's set up, you will want to set your :guilabel:`Path` field to the +hgweb path for the repository. This is the same as your clone path. For +example: + +``https://hg.example.com/repo/myrepo`` + +Or for a real-world example: https://www.mercurial-scm.org/repo/evolve + +If your repository is protected by Basic HTTP Auth, you can supply credentials +in the :guilabel:`Username` and :guilabel:`Password` fields. They will be used +any time Review Board accesses your hgweb instance. + + +.. _Mercurial's documentation on hgweb: + https://www.mercurial-scm.org/wiki/PublishingRepositories#hgweb + + +.. _repository-scm-mercurial-local-clone: + +Using a Local Clone +------------------- + +Review Board can make use of a locally-accessible Mercurial clone, so long as +that clone contains the very latest changes for your repository. + +If the Mercurial clone is the master repository that your developers are +cloning from, then you're in good shape. However, if it's a clone of the +master repository, you will need to ensure it's consistently up-to-date. One +way to do this would be to have a cron job pull the latest changes at least +once a minute. + +When using a local clone, you'll need to point the :guilabel:`Path` field to +the clone directory. For example: ``/var/hg/projectname/``. + +You will leave the :guilabel:`Username` and :guilabel:`Password` fields blank. diff --git a/docs/manual/admin/configuration/repositories/perforce.rst b/docs/manual/admin/configuration/repositories/perforce.rst new file mode 100644 index 0000000000000000000000000000000000000000..ca8ba4ea0d3108ce017b36f14ddca63e238affb5 --- /dev/null +++ b/docs/manual/admin/configuration/repositories/perforce.rst @@ -0,0 +1,153 @@ +.. _repository-scm-perforce: + +===================== +Perforce Repositories +===================== + +Review Board supports posting and reviewing code on :rbintegration:`Perforce +` repositories. Unlike with most types of source code management +systems, Perforce tracks information around in-development changes on the +Perforce server. Review Board makes use of this information to help post +changesets for review and to indicate when a changeset has been submitted to +the repository. + +Review Board supports username/password authentication or ticket-based +authentication for Perforce, and also supports connecting using SSL or +Stunnel. + +To post changes for review, you will need to use RBTools_. Standard Perforce +diffs leave out a lot of important information necessary to properly identify +files, which RBTools works around. See :ref:`Using RBTools with Perforce +` for more information. + +.. note:: + + This guide assumes that you're adding a Perforce repository that's hosted + somewhere in your network or one that's accessible by your Review Board + server. Review Board requires local or network access to your repository. + + Follow the documentation in the links below if your Perforce repository is + hosted on one of these services, as configuration may differ. + + * :ref:`Assembla ` + + +.. _RBTools: https://www.reviewboard.org/downloads/rbtools/ + + +Installing Perforce Support +=========================== + +Before you add the repository, you will need to install the p4_ command line +tool in a system path (or in a place accessible by your web server's process), +and the p4python_ package. + +Installing p4_ will require registering your information on Perforce's +website. If you want to download without registering, or need a specific +version, you can use their `downloads archive`_. + +To install p4python, run:: + + $ pip install p4python + +You will then need to restart your web server for the new module to be +noticed by Review Board. + + +.. _downloads archive: http://www.perforce.com/downloads/perforce/ +.. _p4: + https://www.perforce.com/product/components/perforce-commandline-client +.. _p4python: https://pypi.python.org/pypi/P4Python + + +Adding the Repository +===================== + +To configure a Perforce repository, first proceed to :ref:`add the repository +` and select :guilabel:`Perforce` from the +:guilabel:`Repository type` field. + +You will see a :guilabel:`Path` field, which should contain the value normally +used in :envvar:`P4PORT`. This can be a standard Perforce server path, or it +can be prefixed with ``ssl:`` (to use SSL encryption, if enabled by the server +and p4python), or ``stunnel:`` (to tunnel encryption to a standard Perforce +server, if :command:`stunnel` is installed). + + +Determining your Repository Path +-------------------------------- + +To determine the repository path to use, run the following inside a checkout +of your repository:: + + $ p4 info + +Look for the ``Server address`` field. The value listed is the path you should +use for Review Board. + + +Using SSL +--------- + +If your Perforce server listens over a SSL connection (and you're using +version 2012.1 or higher for the Perforce server), you can connect over SSL by +prefixing ``ssl:`` to the path. For example:: + + ssl:perforce.example.com:1668 + +You can follow `Perforce's guide on enabling SSL support`_ to get started. + +Note that your p4python_ module must be compiled with SSL support. This should +be the case for standard builds, but if not, you will see an error explaining +the situation. Please note that p4python is provided by Perforce, and is not +maintained by the Review Board developers. + +.. _Perforce's guide on enabling SSL support: + http://answers.perforce.com/articles/KB/2596 + + +Using Stunnel +------------- + +If you're not using a SSL-backed connection, and your Perforce server is +located in a different network, you may want to set up a Stunnel connection. +This will provide an encrypted connection between Review Board and your +Perforce server, and can be used for any version of Perforce. + +To start, please follow `Perforce's guide on using Stunnel`_. This will take +care of the configuration on the Perforce server. + +You will then need to install Stunnel_ on the Review Board server. Review +Board 2.0.23+/2.5.4+ support Stunnel version 3 and 4, while earlier versions +of Review Board require Stunnel version 3. The :command:`stunnel` binary must +be in the web server's path. + +You can then configure your repository path to point to your Stunnel proxy. To +do this, just prefix your standard repository path with ``stunnel:`` and list +the port that the Stunnel server is running on. Review Board will take care of +the rest. + +For example, if Stunnel is listening on port 2666, you can use:: + + stunnel:perforce.example.com:2666 + +Review Board will automatically set up a local tunnel client as necessary. +It will bind this to a port between 30000 and 60000 on localhost, and proxy +all requests through it. + + +.. _Perforce's guide on using Stunnel: + http://kb.perforce.com/article/1018/using-stunnel-with-perforce +.. _Stunnel: https://www.stunnel.org/index.html + + +Using Ticket-Based Authentication +================================= + +Review Board supports using ticket-based authentication for Perforce. To +enable this, simply provide the credentials for the Perforce user you want +Review Board to use and then check :guilabel:`Use ticket-based +authentication`. + +Review Board will handle storing the ticket information and requesting new +tickets when necessary. You don't have to do anything else. diff --git a/docs/manual/admin/configuration/repositories/subversion.rst b/docs/manual/admin/configuration/repositories/subversion.rst new file mode 100644 index 0000000000000000000000000000000000000000..5f7c8f0155aba01bee27ea53af613806d826afdc --- /dev/null +++ b/docs/manual/admin/configuration/repositories/subversion.rst @@ -0,0 +1,131 @@ +.. _repository-scm-subversion: + +======================= +Subversion Repositories +======================= + +Review Board supports posting and reviewing code on :rbintegration:`Subversion +` repositories. It also supports browsing for commits in the +:ref:`New Review Request page `. All standard +Subversion repository configurations and access methods can be used. + +To simplify posting changes to Review Board, we recommend using RBTools_. This +ensures that the diffs are in the correct format, working around many +Subversion diff generation issues, and makes managing review requests much +easier. See :ref:`Using RBTools with Subversion ` for +more information. + +.. note:: + + This guide assumes that you're adding a Subversion repository that's hosted + somewhere in your network or one that's accessible by your Review Board + server. Review Board requires local or network access to your repository. + + Follow the documentation in the links below if your Subversion repository is + hosted on one of these services, as configuration may differ. + + * :ref:`Assembla ` + * :ref:`Beanstalk ` + * :ref:`Codebase ` + * :ref:`Fedora Hosted ` + * :ref:`SourceForge ` + * :ref:`Unfuddle ` + + +.. _RBTools: https://www.reviewboard.org/downloads/rbtools/ + + +Installing Subversion Support +============================= + +Before you add the repository, you will need to install either PySVN_ or +Subvertpy_. These are Python modules that support communicating with +Subversion repositories. If both are installed, PySVN will take precedence. + +PySVN may be harder to install on some systems, but provides better +compatibility than Subvertpy. We recommend using PySVN if possible. + +See the :ref:`installation guide ` for PySVN and Subvertpy. + + +.. _PySVN: http://pysvn.tigris.org/ +.. _Subvertpy: https://pypi.python.org/pypi/subvertpy + + +Adding the Repository +===================== + +To configure a Subversion repository, first proceed to :ref:`add the +repository ` and select :guilabel:`Subversion` from the +:guilabel:`Repository type` field. + +You will see a :guilabel:`Path` field, which should contain the URL for the +Subversion repository. This can make use of ``https://``, ``svn://``, or +``svn+ssh://`` repository paths. + +Once added, the repository will be checked to make sure your path and +credentials are correct. If using an HTTPS-backed repository, the SSL +certificate will also be checked for validity, and you may be prompted to +confirm the certificate details. + + +.. warning:: + + Make sure to use the **root** of your Subversion repository. This is + important. While you can technically add a Subversion repository path that + points to a subdirectory of the repository, you will most likely encounter + complications when posting diffs. + +.. tip:: + + If some users are accessing your repository using one protocol (such as + ``https://``) and others are accessing with another (such as + ``svn+ssh://``), you'll want to specify the primary one Review Board should + use to connect in the :guilabel:`Path` field and the other (which will just + be used for repository matching purposes) in :guilabel:`Mirror path`. + + +Determining your Repository Path +-------------------------------- + +To determine the repository path to use, run the following inside a checkout +of your repository:: + + $ svn info + +Look for the ``Repository Root`` field. The value listed is the path you +should use for Review Board. + + +Using ``https://`` or ``svn://`` Repositories +--------------------------------------------- + +If you're using a Subversion repository with ``https://`` or ``svn://``, +you'll need to supply a username and password, either in the URL or in the +:guilabel:`Username` and :guilabel:`Password` fields. + + +Examples +~~~~~~~~ + +* ``https://svn.example.com/myrepo/`` +* ``https://username@svn.example.com/myrepo/`` +* ``svn://svn.example.com/myrepo/`` +* ``svn://username@svn.example.com/myrepo/`` + + +Using ``svn+ssh://`` Reposoitories +---------------------------------- + +If you're using a Subversion repository with ``svn+ssh://`` you will need to +:ref:`configure a SSH key ` in Review Board, and grant access on +the repository. You will also need to specify a username, either in the +repository path or in the :guilabel:`Username` field. The password field can +usually be left blank. + + +Examples +~~~~~~~~ + +* ``svn+ssh://svn.example.com/myrepo/`` +* ``svn+ssh://username@svn.example.com/myrepo/`` diff --git a/docs/manual/admin/index.rst b/docs/manual/admin/index.rst index fe40088f52dbe8ed23ded39baed88f862190f7ea..ed1bdfda49fe1f905264a11ed9df87899fa3b43e 100644 --- a/docs/manual/admin/index.rst +++ b/docs/manual/admin/index.rst @@ -79,7 +79,16 @@ available through the Administration UI: Next, you'll want to configure your repositories, :term:`review groups`, and :term:`default reviewers`: -* :doc:`Managing repositories ` +* :doc:`Managing repositories ` + + * :ref:`Bazaar ` | + :ref:`ClearCase ` | + :ref:`CVS ` | + :ref:`Git ` | + :ref:`Mercurial ` | + :ref:`Perforce ` | + :ref:`Subversion ` + * :doc:`Managing review groups ` * :doc:`Managing default reviewers ` diff --git a/docs/manual/admin/installation/linux.rst b/docs/manual/admin/installation/linux.rst index 01bce93a0516c75176c88a59f7363fe95e39d2cf..6266b0f2616f9e64b6a259009c14a1795aa87649 100644 --- a/docs/manual/admin/installation/linux.rst +++ b/docs/manual/admin/installation/linux.rst @@ -235,6 +235,8 @@ Depending on which source control systems you plan to use, you will need some additional components. +.. _installing-cvs: + CVS --- @@ -253,6 +255,8 @@ To install on `RedHat Enterprise`_, Fedora_ or CentOS_, type:: .. _CVS: http://www.nongnu.org/cvs/ +.. _installing-git: + Git --- @@ -302,6 +306,8 @@ You'll then need to install the Python bindings by typing the following:: .. _Perforce: http://www.perforce.com/ +.. _installing-svn: + Subversion ---------- diff --git a/docs/manual/conf.py b/docs/manual/conf.py index 0928911482f4573755955b7e736a02566de6aea1..a13d8857a02d92b7b6bbaf9c1b1927f282ea85c4 100644 --- a/docs/manual/conf.py +++ b/docs/manual/conf.py @@ -279,6 +279,7 @@ intersphinx_mapping = { extlinks = { 'djangodoc': ('%s%%s.html' % django_doc_base_url, None), 'backbonejs': ('http://backbonejs.org/#%s', 'Backbone.'), + 'rbintegration': ('https://www.reviewboard.org/integrations/%s', ''), 'rbsource': ('https://github.com/reviewboard/reviewboard/blob/%s/%%s' % git_branch, ''), diff --git a/docs/manual/users/review-requests/creating.rst b/docs/manual/users/review-requests/creating.rst index 976ee7b613a8ea89724e45f074980c34203cce38..c8c5c7a45ef27156255aaa624759eb6fb4701cfa 100644 --- a/docs/manual/users/review-requests/creating.rst +++ b/docs/manual/users/review-requests/creating.rst @@ -24,6 +24,8 @@ built-in diff tools generating files with insufficient information). For more information, see the :ref:`RBTools documentation `. +.. _new-review-request-page: + Using the Web UI to Create Review Requests ==========================================