mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-30 02:32:42 +01:00
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
This commit is contained in:
parent
62b06f0f5d
commit
055e8f07ab
11 changed files with 241 additions and 59 deletions
|
@ -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}
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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`
|
||||
|
|
|
@ -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}.
|
||||
|
|
|
@ -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}.
|
||||
|
|
100
src/docs/userguide/arcanist_quick_start.diviner
Normal file
100
src/docs/userguide/arcanist_quick_start.diviner
Normal file
|
@ -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}.
|
|
@ -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}.
|
||||
|
|
Loading…
Reference in a new issue