1
0
Fork 0
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:
epriestley 2012-08-10 12:00:40 -07:00
parent 62b06f0f5d
commit 055e8f07ab
11 changed files with 241 additions and 59 deletions

View file

@ -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 file

@ -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 file

@ -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 file

@ -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 file

@ -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 file

@ -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 file

@ -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 file

@ -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 file

@ -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 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}.

View file

@ -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}.