From 120c3bcecd5c69f519faaf27584a63aa300aa248 Mon Sep 17 00:00:00 2001 From: epriestley Date: Mon, 23 May 2011 07:42:58 -0700 Subject: [PATCH] Bring over Arcanist documentation. Summary: Mostly from arcanist/ and libphutil/. --- src/docs/userguide/arcanist.diviner | 139 ++++++++++++++++++ src/docs/userguide/arcanist_hooks.diviner | 37 +++++ src/docs/userguide/arcanist_lint_unit.diviner | 85 +++++++++++ .../userguide/arcanist_new_project.diviner | 52 +++++++ 4 files changed, 313 insertions(+) create mode 100644 src/docs/userguide/arcanist.diviner create mode 100644 src/docs/userguide/arcanist_hooks.diviner create mode 100644 src/docs/userguide/arcanist_lint_unit.diviner create mode 100644 src/docs/userguide/arcanist_new_project.diviner diff --git a/src/docs/userguide/arcanist.diviner b/src/docs/userguide/arcanist.diviner new file mode 100644 index 0000000000..38174c3c26 --- /dev/null +++ b/src/docs/userguide/arcanist.diviner @@ -0,0 +1,139 @@ +@title Arcanist User Guide +@group userguide + +Guide to Arcanist, a command-line tool for code review and revision management. + +Arcanists glues together several other tools, like Differential and lint. It +also serves as the CLI to Phabricator, and is used to get changesets into +Differential for review. + +A detailed command reference is available by running ##arc help##. This +document provides a high level overview of common workflows. + +Arcanist has technical, contributor-focused documentation here: + + += Overview = + +Arcanist is a wrapper script that sits on top of other tools (e.g., +Differential, linters, unit test frameworks, SVN, and git) and provides a +simple command-line API to manage code review and some related revision control +operations. + +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## + - 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## + - download a patch from Differential with ##arc export## + - update Git commit messages after review with ##arc amend## + - commit SVN changes with ##arc commit## + +Once you've configured lint and unit test integration, you can also: + + - check your code for syntax and style errors with ##arc lint## + - run unit tests that cover your changes with ##arc unit## + +Arcanist has some advanced features as well, you can: + + - execute Conduit method calls with ##arc call-conduit## + - create or update libphutil libraries with ##arc liberate## + - activate tab completion with ##arc shell-complete## + - install arc as a pre-commit hook with ##arc svn-hook-pre-commit## or + ##arc git-hook-pre-receive## + - ...or extend Arcanist and add new commands + +Except where otherwise noted, these workflows are generally agnostic to the +underlying version control system and will work properly in git or SVN +repositories. + += Installing Arcanist = + +Arcanist is meant to be installed on your local machine or development server, +i.e. whatever machine you're editing code on. It runs on Linux and Mac OS X; +To install it, clone it and libphutil off github: + + somewhere/ $ git clone git://github.com/facebook/libphutil.git + somewhere/ $ git clone git://github.com/facebook/arcanist.git + +Now add ##somewhere/arcanist/bin/arc## to your path. + +== Installing Tab Completion == + +If you use ##bash##, you can set up tab completion by adding something like this +to your ##.bashrc##, ##.profile## or similar: + + source /path/to/arcanist/resources/shell/bash-completion + += Running Arcanist = + +Arcanist is a context-sensitive command which you should run in a working copy, +like ##svn## or ##git##. Generally speaking, ##arc## commands operate on changed +files in the working copy in svn, and on the commit at HEAD in git. + +== SVN Basics == + +To **create a revision** in SVN: + + $ nano source_code.c # Make changes. + $ arc diff + +This will give you a diff URI, which you can use to create a new revision via +the web UI. To later **update an existing revision**, just do the same thing: + + $ nano source_code.c # Make more changes. + $ arc diff + +This time, attach the diff to your existing revision. Once your revision has +been accepted, you can commit it like this: + + $ arc commit + +== Git Basics == + +There are a lot of ways to use git, and Arcanist is flexible enough to handle +several of them. Use a commit template similar to this one: + + resources/git/commit-template.txt + +To **create a revision** in git: + + $ nano source_code.c # Make changes. + $ git commit -a # Fill out the template. + $ arc diff + +To **update a revision** in git by amending HEAD: + + $ nano source_code.c # Make changes. + $ git commit -a --amend # Amend into HEAD. + $ arc diff + +To **update a revision** in git by stacking local commits: + + $ nano source_code.c # Make changes. + $ git commit -a -m '...' # Make another local commit. + $ arc diff HEAD^^ # Update with the last two changes. + +To **create and update a revision** using feature branches: + + $ git checkout master + $ git checkout -b feature # Create a branch. + $ nano source_code.c # Make changes. + $ git commit -a # Fill out the template. + $ arc diff master # Diff changes between here and branch 'master' + $ nano source_code.c # Make more changes. + $ git commit -a -m '...' # Or you can amend. + $ arc diff master # Updates the diff. + +Once your revision has been accepted, use ##arc amend## to finalize it. + + $ arc amend # If you used an --amend workflow. + +If you used a multiple-commit workflow, you need to squash commits first with +##git rebase -i## or similar, then amend the squashed commit. + +After amending, you can push the commit to the remote with ##git push## or +##git svn dcommit## or via whatever other channel your project uses as +applicable. diff --git a/src/docs/userguide/arcanist_hooks.diviner b/src/docs/userguide/arcanist_hooks.diviner new file mode 100644 index 0000000000..e6129db39b --- /dev/null +++ b/src/docs/userguide/arcanist_hooks.diviner @@ -0,0 +1,37 @@ +@title Arcanist User Guide: Repository Hooks +@group userguide + +Describes how to set up Arcanist as an SVN pre-commit hook. + += Installing Arcanist SVN Hooks = + +You can install Arcanist as an SVN pre-commit hook, to reject commits which +contain lint errors. The immediate value of this is that syntax errors won't +be committable, but you can block other kinds of badness with appropriate lint +engines. + +To install Arcanist as a pre-commit hook, add this to your svn/hooks/pre-commit: + + #!/bin/sh + /usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit $@ 1>&2 + +Make sure you make this file executable, or you'll get an error for every commit +with an unhelpful error message. You also need to specify the full path to PHP +since SVN nukes ENV before executing scripts. Alternatively you can specify +PATH explicitly. + +If your project is configured to run linters or lint engines which aren't part +of Arcanist, specify where to load them from with ##--load-phutil-library##: + + --load-phutil-library=/path/to/library/root + +Since SVN commit hooks run without access to a working copy, you'll need to keep +one checked out somewhere and reference it with ##--load-phutil-library## if you +build new linters or customize lint engines. For example, your hook might +look like this: + + #!/bin/sh + /usr/local/bin/php -f /path/to/arcanist/bin/arc svn-hook-pre-commit \ + --load-phutil-library=/path/to/custom/lint/engine \ + --load-phutil-library=/path/to/custom/unittest/engine \ + $@ 1>&2 diff --git a/src/docs/userguide/arcanist_lint_unit.diviner b/src/docs/userguide/arcanist_lint_unit.diviner new file mode 100644 index 0000000000..4fbb8655ab --- /dev/null +++ b/src/docs/userguide/arcanist_lint_unit.diviner @@ -0,0 +1,85 @@ +@title Arcanist User Guide: Customizing Lint, Unit Tests and Workflows +@group userguide + +Explains how to build new classes to control how Arcanist behaves. + +NOTE: TODO: This document is pretty trash, follow at your own risk. + += Overview = + +Arcanist has some basic configuration options available in the ##.arcconfig## +file (see @{article:Setting Up .arcconfig}), but it can't handle everything. If +you want to customize Arcanist at a deeper level, you need to build new classes. +For instance: + + - if you want to configure linters, or add new linters, you need to create a + new class which extends @{class:ArcanistLintEngine}. + - if you want to integrate with a unit testing framework, you need to create a + new class which extends @{class:ArcanistBaseUnitTestEngine}. + - if you you want to change how workflows behave, or add new workflows, you + need to create a new class which extends @{class:ArcanistConfiguration}. + +Arcanist works through a sort of dependency-injection approach. For example, +Arcanist does not run lint rules by default, but you can set **lint_engine** +in your ##.arcconfig## to the name of a class which extends +@{class:ArcanistLintEngine}. When running from inside your project, Arcanist +will load this class and call methods on it in order to run lint. To make this +work, you need to do three things: + + - actually write the class; + - add the library where the class exists to your ##.arcconfig##; + - add the class name to your ##.arcconfig## as the **lint_engine**, + **unit_engine**, or **arcanist_configuration**. + += Write the Class = + +(TODO) + += Load the Class = + +To make the class loadable, you need to put the path to it in your +##.arcconfig##, under **phutil_libraries**: + + { + // ... + "phutil_libraries" : { + // ... + "my-library" : "/path/to/my/library", + // ... + } + // ... + } + +You can either specify an absolute path, or a path relative to the project root. +When you run ##arc --trace##, you should see a message to the effect that it has +loaded your library. + +For debugging or testing, you can also run Arcanist with the +##--load-phutil-library## flag: + + arc --load-phutil-library=/path/to/library + +You can specify this flag more than once to load several libraries. Note that +if you use this flag, Arcanist will ignore any libraries listed in +##.arcconfig##. + += Use the Class = + +This step is easy: just edit ##.arcconfig## to specify your class name as +the appropriate configuration value. + + { + // ... + "lint_engine" : "MyCustomArcanistLintEngine", + // ... + } + +Now, when you run Arcanist in your project, it will invoke your class when +appropriate. + +For lint and unit tests, you can also use the ##--engine## flag override the +default engine: + + arc lint --engine MyCustomArcanistLintEngine + +This is mostly useful for debugging and testing. diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/userguide/arcanist_new_project.diviner new file mode 100644 index 0000000000..8aab8d4cb3 --- /dev/null +++ b/src/docs/userguide/arcanist_new_project.diviner @@ -0,0 +1,52 @@ +@title Arcanist User Guide: Configuring a New Project +@group userguide + +Explains how to configure Arcanist projects with ##.arcconfig## files. + += .arcconfig Basics = + +Arcanist uses ##.arcconfig## files to determine a number of things about project +configuration. For instance, these are 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: + + { + "project_id" : "some_project_name", + "conduit_uri" : "https://phabricator.example.com/api/" + } + +Here's what these options mean: + + - **project_id**: a human-readable string identifying the project + - **conduit_uri**: the Conduit API URI for the Phabricator installation that + Arcanist should send diffs to for review. Generally, if you access + Phabricator at ##https://phabricator.example.com/##, the **conduit_uri** is + ##https://phabricator.example.com/api/##. Be mindful about "http" vs + "https". + +For an exhaustive list of available options, see below. + += Advanced .arcconfig = + +Other options include: + + - **lint_engine**: the name of a subclass of @{class:ArcanistLintEngine}, + which should be used to apply lint rules to this project. See (TODO). + - **unit_engine**: the name of a subclass of + @{class:ArcanistBaseUnitTestEngine}, which should be used to apply unit + test rules to this project. See (TODO). + - **arcanist_configuration**: the name of a subclass of + @{class:ArcanistConfiguration} which can add new command flags for this + project or provide entirely new commands. + - **remote_hooks_installed**: tells Arcanist that you've set up remote hooks + in the master repository (see @{article:Installing Arcanist SVN Hooks} for + SVN, or (TODO) for git). + - **copyright_holder**: used by @{class:ArcanistLicenseLinter} to apply + license notices to source files. + - **phutil_libraries**: map of additional Phutil libraries to load at startup.