Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Improve arcanist documentation

Summary:
There's some good feedback from Wikimedia here:

http://lists.wikimedia.org/pipermail/wikitech-l/2012-August/062252.html

Try to improve on some of it. In particular:

  - Make it clear that /arcanist/ is not where you should be (D3235).
  - Provide better connections from "Arcanist User Guide" to other documents.
  - Provide a "Quick Start" guide with a simpler set of instructions that links to richer documentation.
  - Reorganize the project setup guide to put more important things earlier on.
  - Make it clear that you should commit `.arcconfig`.
  - Provide more hints for initial setup.
  - Describe and organize advanced configuration/extension documentation as more clearly separate from basic setup/install documentation.

Test Plan: Generated, read docs.

Reviewers: vrana, btrahan

Reviewed By: vrana

CC: aran

Differential Revision: https://secure.phabricator.com/D3236
  • Loading branch information...
commit 055e8f07ab562bbb681a24ec339233476228c408 1 parent 62b06f0
@epriestley epriestley authored
View
43 src/docs/userguide/arcanist.diviner
@@ -9,11 +9,18 @@ unit tests, and manages common workflows like getting changes into Differential
for review.
A detailed command reference is available by running ##arc help##. This
-document provides a high level overview of common workflows.
+document provides an overview of common workflows and installation.
Arcanist has technical, contributor-focused documentation here:
<http://www.phabricator.com/docs/arcanist/>
+= Quick Start =
+
+A quick start guide is available at @{article:Arcanist Quick Start}. It provides
+a much more compact summary of how to get `arc` set up and running for a new
+project. You may want to start there, and return here if you need more
+information.
+
= Overview =
Arcanist is a wrapper script that sits on top of other tools (e.g.,
@@ -21,10 +28,19 @@ Differential, linters, unit test frameworks, git, Mercurial, and SVN) and
provides a simple command-line API to manage code review and some related
revision control operations.
+For a detailed list of all available commands, run:
+
+ $ arc help
+
+For detailed information about a specific command, run:
+
+ $ arc help <command>
+
Arcanist allows you to do things like:
- get detailed help about available commands with ##arc help##
- - send your code to Differential for review with ##arc diff##
+ - send your code to Differential for review with ##arc diff## (for detailed
+ instructions, see @{article:Arcanist User Guide: arc diff})
- show pending revision information with ##arc list##
- find likely reviewers for a change with ##arc cover##
- apply changes in a revision to the working copy with ##arc patch##
@@ -37,6 +53,7 @@ Arcanist allows you to do things like:
Once you've configured lint and unit test integration, you can also:
- check your code for syntax and style errors with ##arc lint##
+ (see @{article:Arcanist User Guide: Lint})
- run unit tests that cover your changes with ##arc unit##
Arcanist integrates with other tools:
@@ -60,7 +77,8 @@ SVN repositories.
= Installing Arcanist =
Arcanist is meant to be installed on your local machine or development server --
-whatever machine you're editing code on. It runs on Linux, Mac OS X, and
+whatever machine you're editing code on. It runs on Linux,
+Mac OS X (see @{article:Arcanist User Guide: Mac OS X}), and
Windows (see @{article:Arcanist User Guide: Windows}).
Arcanist is written in PHP, so you need to install the PHP CLI first if you
@@ -96,9 +114,9 @@ You can later upgrade Arcanist and libphutil to the latest versions with
== Installing Arcanist for a Team ==
-Arcanist changes quickly and doesn't currently have an auto-update mechanism,
-so it can be something of a headache to get it installed and keep people up to
-date. Here are some approaches you might be able to use:
+Arcanist changes quickly, so it can be something of a headache to get it
+installed and keep people up to date. Here are some approaches you might be
+able to use:
- Facebook does most development on development servers, which have a standard
environment and NFS mounts. Arcanist and libphutil themselves live on an
@@ -125,5 +143,18 @@ to your ##.bashrc##, ##.profile## or similar:
Continue by:
+ - setting up a new project for use with `arc`, with
+ @{article:Arcanist User Guide: Configuring a New Project}; or
- learning how to use `arc` to send changes for review with
@{article:Arcanist User Guide: arc diff}.
+
+Advanced topics are also available. These are detailed guides to configuring
+technical features of `arc` that refine its behavior. You do not need to read
+them to get it working.
+
+ - @{article:Arcanist User Guide: Commit Ranges}
+ - @{article:Arcanist User Guide: Lint}
+ - @{article:Arcanist User Guide: Customizing Existing Linters}
+ - @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
+ - @{article:Arcanist User Guide: Code Coverage}
+ - @{article:Arcanist User Guide: Repository Hooks}
View
4 src/docs/userguide/arcanist_commit_ranges.diviner
@@ -3,6 +3,10 @@
Explains how commit ranges work in Arcanist.
+This is an advanced user guide which covers a complicated topic in detail. If
+you're just getting started, you don't need to look at this yet. Instead, start
+with the @{article:Arcanist User Guide}.
+
= Overview =
//In Subversion, `arc` commands always operate on the uncommitted changes in the
View
9 src/docs/userguide/arcanist_coverage.diviner
@@ -3,6 +3,15 @@
Explains code coverage features in Arcanist and Phabricator.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+Before you can configure coverage features, you must set up unit test
+integration. For instructions, see @{article:Arcanist User Guide: Configuring
+a New Project} and @{article:Arcanist User Guide: Customizing
+Lint, Unit Tests and Workflows}.
+
= Using Coverage Features =
If your project has unit tests with coverage integration (see below for
View
14 src/docs/userguide/arcanist_diff.diviner
@@ -1,17 +1,17 @@
@title Arcanist User Guide: arc diff
@group userguide
-Guide to running `arc diff`.
-
-= Overview =
+Guide to running `arc diff`, to send changes to Differential for review.
This article assumes you have `arc` installed and running; if not, see
@{article:Arcanist User Guide} for help getting it set up.
-This document is intended for users of `arc diff`, and is a practical
-guide to using it to send changes for review. If you are installing and
-configuring Phabricator, make sure to read the more comprehensive information in
-@{article:Arcanist User Guide: Configuring a New Project}.
+Before running `arc diff`, you should create a `.arcconfig` file. If someone
+set things up for you, they may already have done this. See
+@{article:Arcanist User Guide: Configuring a New Project} for instructions and
+information.
+
+= Overview =
While `arc` has a large number of commands that interface with various
Phabricator applications, the primary use of `arc` is to send changes for
View
8 src/docs/userguide/arcanist_extending_lint.diviner
@@ -3,6 +3,14 @@
Explains how to customize existing linters.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+This guide explains how to refine lint behavior. To configure lint in the first
+place, see @{article:Arcanist User Guide: Configuring a New Project} and
+@{article:Arcanist User Guide: Lint}.
+
= Overview =
Arcanist ships with a number of linters which you may want to reuse in whole
View
8 src/docs/userguide/arcanist_lint.diviner
@@ -3,6 +3,14 @@
Guide to lint, linters, and linter configuration.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+This guide explains how lint works when configured in an `arc` project. If
+you haven't set up a project yet, do that first. For instructions, see
+@{article:Arcanist User Guide: Configuring a New Project}.
+
= Overview =
"Lint" refers to a general class of programming tools which analyze source code
View
4 src/docs/userguide/arcanist_lint_unit.diviner
@@ -3,6 +3,10 @@
Explains how to build new classes to control how Arcanist behaves.
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
= Overview =
Arcanist has some basic configuration options available in the `.arcconfig`
View
5 src/docs/userguide/arcanist_mac_os_x.diviner
@@ -24,3 +24,8 @@ You can edit your `~/.profile` to permanently configure environmental variables.
Now you should be able to run `arc` like a normal command.
+= Next Steps =
+
+Continue by:
+
+ - returning to @{article:Arcanist User Guide}.
View
100 src/docs/userguide/arcanist_new_project.diviner
@@ -1,62 +1,20 @@
@title Arcanist User Guide: Configuring a New Project
@group userguide
-Explains how to configure Arcanist projects with ##.arcconfig## files.
-
-= Overview =
-
-You can run `arc` commands that require a working copy in any Git, Subversion
-or Mercurial working copy, but some features won't work unless you set up an
-`.arcconfig` file to configure settings for the project. Creating this file is
-easy and only takes a few minutes.
-
-Without `.arcconfig`:
-
- - You will need to set a default Phabricator URI with
- `arc set-config default <uri>`, or specify an explicit URI
- with `--conduit-uri` each time you run a command.
- - You will not be able to run linters through arc unless you pass `--engine`
- explicitly.
- - You will not be able to customize certain linter parameters even with
- `--engine`.
- - You will not be able to run unit tests through arc unless you pass
- `--engine` explicitly.
- - You will not be able to trigger lint and unit integration through
- `arc diff`.
- - You will not be able to put Git working copies into immutable history mode
- (see below).
- - You will not be able to specify a repository encoding. UTF-8 will be assumed
- if you do not pass `--encoding`.
- - You will not be able to add plugins to arc to modify existing workflows or
- add new ones.
- - You will not be able to load additional libraries unless you specify them
- explicitly with `--load-phutil-library`.
- - Symbol index integration, which allows users to click function or class
- names in Differential and jump to their definitions, will not work.
- - `arc patch` will be unable to detect that you are applying changes to the
- wrong project.
- - In Subversion, `arc` will be unable to determine the canonical root
- of a project, and will assume it is the working directory (in Subversion
- prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
- means the paths of files in diffs won't be anchored to the same place,
- and will have different amounts of path context, which may be confusing for
- reviewers and will sometimes prevent patches from applying properly if they
- are applied against a different directory than they were generated from.
- - In Subversion, `arc` will be unable to guess that you intend to update
- an existing revision; you must use `--update` explicitly or `--preview`
- and attach diffs via the web interface.
+Explains how to configure Arcanist projects with `.arcconfig` files.
= .arcconfig Basics =
+An ##.arcconfig## file is a JSON file which you check into your project's root.
+
Arcanist uses ##.arcconfig## files to determine a number of things about project
-configuration. For instance, these are things it figures out from
+configuration. For instance, these are some of the things it figures out from
##.arcconfig##:
- where the logical root directory of a project is;
- which server Arcanist should send diffs to for code review; and
- which lint rules should be applied.
-An ##.arcconfig## file is a JSON file which you check into your project's root.
A simple, valid file looks something like this:
{
@@ -72,6 +30,9 @@ Here's what these options mean:
For an exhaustive list of available options, see below.
+NOTE: You should commit your `.arcconfig` file! It contains project
+configuration, not user configuration.
+
= Advanced .arcconfig =
Other options include:
@@ -193,3 +154,50 @@ The general intent here is:
next to other repositories.
- Or put everything in some standard location and add it to `include_path`.
+= Running Without .arcconfig =
+
+Although you don't need to set up `.arcconfig`, and you can run `arc` command
+that require a working copy in any Git, Subversion or Mercurial working copy,
+some features won't work unless you set up an `.arcconfig` file.
+
+Without `.arcconfig`:
+
+ - You will need to set a default Phabricator URI with
+ `arc set-config default <uri>`, or specify an explicit URI
+ with `--conduit-uri` each time you run a command.
+ - You will not be able to run linters through arc unless you pass `--engine`
+ explicitly.
+ - You will not be able to customize certain linter parameters even with
+ `--engine`.
+ - You will not be able to run unit tests through arc unless you pass
+ `--engine` explicitly.
+ - You will not be able to trigger lint and unit integration through
+ `arc diff`.
+ - You will not be able to put Git working copies into immutable history mode
+ (see below).
+ - You will not be able to specify a repository encoding. UTF-8 will be assumed
+ if you do not pass `--encoding`.
+ - You will not be able to add plugins to arc to modify existing workflows or
+ add new ones.
+ - You will not be able to load additional libraries unless you specify them
+ explicitly with `--load-phutil-library`.
+ - Symbol index integration, which allows users to click function or class
+ names in Differential and jump to their definitions, will not work.
+ - `arc patch` will be unable to detect that you are applying changes to the
+ wrong project.
+ - In Subversion, `arc` will be unable to determine the canonical root
+ of a project, and will assume it is the working directory (in Subversion
+ prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
+ means the paths of files in diffs won't be anchored to the same place,
+ and will have different amounts of path context, which may be confusing for
+ reviewers and will sometimes prevent patches from applying properly if they
+ are applied against a different directory than they were generated from.
+ - In Subversion, `arc` will be unable to guess that you intend to update
+ an existing revision; you must use `--update` explicitly or `--preview`
+ and attach diffs via the web interface.
+
+= Next Steps =
+
+Continue by:
+
+ - returning to @{article:Arcanist User Guide}.
View
100 src/docs/userguide/arcanist_quick_start.diviner
@@ -0,0 +1,100 @@
+@title Arcanist Quick Start
+@group userguide
+
+Quick guide to getting Arcanist working for a new project.
+
+This is a summary of steps to install Arcanist, configure a project for use with
+it, and run `arc` to send changes for review.
+
+= Install Arcanist =
+
+For detailed instructions on installing Arcanist, see
+@{article:Arcanist User Guide}.
+
+ - For Mac OS X, see @{article:Arcanist User Guide: Mac OS X}.
+ - For Windows, see @{article:Arcanist User Guide: Windows}.
+
+First, install dependencies:
+
+ - Install PHP.
+ - Install Git.
+
+Then install Arcanist itself:
+
+ $ mkdir somewhere/
+ $ cd somewhere/
+ somewhere/ $ git clone git://github.com/facebook/libphutil.git
+ somewhere/ $ git clone git://github.com/facebook/arcanist.git
+
+Add `arc` to your path:
+
+ $ export PATH="$PATH:/somewhere/arcanist/bin/"
+
+This won't work for Windows, see @{article:Arcanist User Guide: Windows} for
+instructions.
+
+= Configure Your Project =
+
+For detailed instructions on project configuration, see
+@{article:Arcanist User Guide: Configuring a New Project}.
+
+Create a `.arcconfig` file in your project's working copy:
+
+ $ cd yourproject/
+ yourproject/ $ $EDITOR .arcconfig
+ yourproject/ $ cat .arcconfig
+ {
+ "project_id" : "yourprojectname",
+ "conduit_uri" : "https://phabricator.example.com/"
+ }
+
+Set `project_id` to a string that identifies the project.
+
+Set `conduit_uri` to the URI for your Phabricator install (where `arc`
+should send changes to).
+
+NOTE: You should **commit this file** to the repository.
+
+= Install Arcanist Credentials =
+
+Credentials allow you to authenticate. You must have an account on Phabricator
+before you can perform this step.
+
+ $ cd yourproject/
+ yourproject/ $ arc install-certificate
+ ...
+
+Follow the instructions. This will link your user account on your local machine
+to your Phabricator account.
+
+= Send Changes For Review =
+
+For detailed instructions on using `arc diff`, see
+@{article:Arcanist User Guide: arc diff}.
+
+Subversion:
+
+ $ $EDITOR file.c
+ $ arc diff
+
+Git:
+
+ $ $EDITOR file.c
+ $ git commit -a -m '...'
+ $ arc diff HEAD^
+
+Mercurial:
+
+ $ $EDITOR file.c
+ $ hg commit -m '...'
+ $ arc diff tip^
+
+= Next Steps =
+
+Continue by:
+
+ - learning more about project configuration with
+ @{article:Arcanist User Guide: Configuring a New Project}; or
+ - learning more about `arc diff` with
+ @{article:Arcanist User Guide: arc diff}; or
+ - returning to @{article:Arcanist User Guide}.
View
5 src/docs/userguide/arcanist_windows.diviner
@@ -77,3 +77,8 @@ And this for GitPad (you may need to adjust the path):
name=GitPad
$ arc set-config editor "\"C:\Users\yourusername\AppData\Roaming\GitPad\GitPad.exe\""
+= Next Steps =
+
+Continue by:
+
+ - returning to @{article:Arcanist User Guide}.
Please sign in to comment.
Something went wrong with that request. Please try again.