No OneTemporary
Actions

Size

27 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/docs/user/userguide/arcanist_lint_unit.diviner b/src/docs/user/userguide/arcanist_lint_unit.diviner
	index d9cc107440..3b12de9dac 100644
	--- a/src/docs/user/userguide/arcanist_lint_unit.diviner
	+++ b/src/docs/user/userguide/arcanist_lint_unit.diviner
	@@ -1,92 +1,92 @@
	@title Arcanist User Guide: Customizing Lint, Unit Tests and Workflows
	@group userguide

	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`
	file (see @{article:Arcanist User Guide: Configuring a New Project}), 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@arcanist:ArcanistLintEngine}.
	- if you want to integrate with a unit testing framework, you need to create a
	- new class which extends @{class@arcanist:ArcanistBaseUnitTestEngine}.
	+ new class which extends @{class@arcanist:ArcanistUnitTestEngine}.
	- if you you want to change how workflows behave, or add new workflows, you
	need to create a new class which extends
	@{class@arcanist: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@arcanist: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.

	= Create a libphutil Library =

	If you haven't created a library for the class to live in yet, you need to do
	that first. Follow the instructions in
	@{article:libphutil Libraries User Guide}, then make the library loadable by
	adding it to your ##.arcconfig## like this:

	{
	// ...
	"load" : [
	// ...
	"/path/to/my/library", // Absolute path
	"support/arcanist", // Relative path in this project
	// ...
	]
	// ...
	}

	You can either specify an absolute path, or a path relative to the project root.
	When you run ##arc list --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 <command>

	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" : "CustomArcanistLintEngine",
	// ...
	}

	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.

	= Next Steps =

	- Learn how to reuse existing linters by reading
	@{article:Arcanist User Guide: Customizing Existing Linters}.
	diff --git a/src/docs/user/userguide/arcanist_new_project.diviner b/src/docs/user/userguide/arcanist_new_project.diviner
	index 106ec6f8f8..fbb2ad4a45 100644
	--- a/src/docs/user/userguide/arcanist_new_project.diviner
	+++ b/src/docs/user/userguide/arcanist_new_project.diviner
	@@ -1,227 +1,227 @@
	@title Arcanist User Guide: Configuring a New Project
	@group userguide

	Explains how to configure Arcanist projects with `.arcconfig` files.

	= Overview =

	In most cases, you should be able to use `arc` without specifically configuring
	your project for it. If you want to adjust `arc` behaviors, you can create a
	`.arcconfig` file in your project to provide project-specific settings.

	= .arcconfig Basics =

	An `.arcconfig` file is a JSON file which you check into your project's root.

	Arcanist uses `.arcconfig` files to customize a number of things about its
	behavior. The first thing you're likely to want to configure is the URI
	for your Phabricator install. A simple, valid file looks something like this:

	name=.arcconfig
	{
	"phabricator.uri" : "https://phabricator.example.com/"
	}

	For details on available options, see below.

	NOTE: You should commit your `.arcconfig` file! It contains project
	configuration, not user configuration.

	= Advanced .arcconfig =

	Common options are:

	- phabricator.uri: the URI for the Phabricator install that `arc` should
	connect to when run in this project. This option was previously called
	`conduit_uri`.
	- repository.callsign: The callsign of this repository in Diffusion.
	Normally, `arc` can detect this automatically, but if it can't figure it out
	you can specify it explicitly. Use `arc which` to understand the detection
	process.
	- history.immutable: Configures `arc` to use workflows which never rewrite
	history in the working copy. By default, `arc` will perform some rewriting
	of unpublished history (amending commit messages, squash merging) on some
	workflows in Git. The distinctions are covered in detail below.

	Other options include:

	- load: list of additional Phutil libraries to load at startup.
	See below for details about path resolution, or see
	@{article:libphutil Libraries User Guide} for a general introduction to
	libphutil libraries.
	- project.name: name an "Arcanist Project" to associate this working
	copy (Git, Mercurial) or directory (SVN) with. Previously, this was a
	required option, but `arc` can now usually operate without it in Git and
	Mercurial. This option was previously called `project_id`.
	- https.cabundle: specifies the path to an alternate certificate bundle
	for use when making HTTPS connections.
	- lint.engine: the name of a subclass of
	@{class@arcanist:ArcanistLintEngine}, which should be used to apply lint
	rules to this project. See @{article:Arcanist User Guide: Lint}.
	- unit.engine: the name of a subclass of
	- @{class@arcanist:ArcanistBaseUnitTestEngine}, which should be used to apply
	+ @{class@arcanist:ArcanistUnitTestEngine}, which should be used to apply
	unit test rules to this project. See
	@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.

	These options are supported, but their use is discouraged:

	- http.basicauth.user: specify an HTTP basic auth username for use when
	connecting to Phabricator.
	- http.basicauth.pass: specify an HTTP basic auth password for use when
	connecting to Phabricator.
	- https.blindly-trust-domains: a list of domains to trust blindly over
	HTTPS, even if their certificates are invalid. This is a brute force
	solution to certificate validity problems, and is discouraged. Instead,
	use valid certificates.

	For a complete list of options, run `arc get-config`. Although all
	options can be set in `.arcconfig`, some options (like `editor`) usually do not
	make sense to set here because they're likely to vary from user to user.

	= History Mutability =

	Arcanist workflows run in two broad modes: either history is //mutable// or
	//immutable//. Under a //mutable// history, `arc` commands may rewrite the
	working copy history; under an //immutable// history, they may not.

	You control history mutability by setting `history.immutable` to `true` or
	`false` in your configuration. By default, it is `false` in Git (i.e.,
	//mutable//) and `true` in Mercurial (i.e., //immutable//). The sections below
	explain how these settings affect workflows.

	== History Mutability: Git ==

	In a workflow with //mutable// history, you rewrite local history. You develop
	in feature branches, but squash or amend before pushing by using ##git commit
	--amend##, ##git rebase -i##, or `git merge --squash`. Generally, one idea in
	the remote is represented by one commit.

	In a workflow with //immutable// history, you do not rewrite local history. You
	develop in feature branches and push them without squashing commits. You do not
	use ##git commit --amend## or ##git rebase -i##. Generally, one idea in the
	remote is represented by many commits.

	Practically, these are the differences you'll see based on your setting:

	- Mutable
	- `arc diff` will prompt you to amend lint changes into HEAD.
	- `arc diff` will amend the commit message in HEAD after creating a
	revision.
	- `arc land` will default to the `--squash` strategy.
	- `arc amend` will amend the commit message in HEAD with information from
	the corresponding or specified Differential revision.
	- Immutable
	- `arc diff` will abort if it makes lint changes.
	- `arc diff` will not amend the commit message in HEAD after creating a
	revision.
	- `arc land` will default to the `--merge` strategy.
	- `arc amend` will exit with an error message.

	== History Mutability: Mercurial ==

	Before version 2.2, stock Mercurial has no history mutation commands, so
	this setting has no effect. With Mercurial 2.2. or newer, making history
	//mutable// means:

	- Mutable (versions 2.2 and newer)
	- `arc diff` will amend the commit message in `.` after creating a
	revision.
	- `arc amend` will amend the commit message in `.` with information from
	the corresponding or specified Differential revision.
	- Immutable (or versions prior to 2.2)
	- `arc diff` will not amend the commit message in `.` after creating a
	revision.
	- `arc amend` will exit with an error message.

	= How Libraries Are Located =

	If you specify an external library to load, like 'examplelib', and use a
	relative path like this:

	{
	...
	"load": [
	"examplelib/src"
	],
	...
	}

	...arc looks for it by trying these paths:

	- `path/to/root/examplelib/src/` First, arc looks in the project's root
	directory (where the `.arcconfig` lives) to see if the library is part of
	the project. This makes it easy to just put project-specific code in a
	project.
	- `path/to/root/../examplelib/src/` Next, arc looks //next to// the project's
	root directory to see if the library is in a sibling directory. If you
	work with several repositories, this makes it easy to put all the `arc`
	code in one repository and just check it out in the same directory as
	everything else.
	- `php/include/path/examplelib/src` Finally, arc falls back to PHP, which
	will look in paths described in the `include_path` php.ini setting. This
	allows you to install libraries in some global location if you prefer.

	You can alternately supply an absolute path, like `/var/arc/examplelib/src`, but
	then everyone will need to install the library at that exact location.

	NOTE: Specify the path to the directory which includes
	`__phutil_library_init__.php`. For example, if your init file is in
	`examplelib/src/__phutil_library_init__.php`, specify `examplelib/src`,
	not just `examplelib/`.

	The general intent here is:

	- Put project-specific code in some directory in the project, like
	`support/arc/src/`.
	- Put shared code (e.g., which enforces general coding standards or hooks
	up to unit tests or whatever) in a separate repository and check it out
	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}.
	diff --git a/src/docs/user/userguide/events.diviner b/src/docs/user/userguide/events.diviner
	index 0ec3542f3f..3cfa38e3c6 100644
	--- a/src/docs/user/userguide/events.diviner
	+++ b/src/docs/user/userguide/events.diviner
	@@ -1,330 +1,330 @@
	@title Events User Guide: Installing Event Listeners
	@group userguide

	Using Phabricator event listeners to customize behavior.

	= Overview =

	Phabricator and Arcanist allow you to install custom runtime event listeners
	which can react to certain things happening (like a Maniphest Task being edited
	or a user creating a new Differential Revision) and run custom code to perform
	logging, synchronize with other systems, or modify workflows.

	These listeners are PHP classes which you install beside Phabricator or
	Arcanist, and which Phabricator loads at runtime and runs in-process. They
	require somewhat more effort upfront than simple configuration switches, but are
	the most direct and powerful way to respond to events.

	= Installing Event Listeners (Phabicator) =

	To install event listeners in Phabricator, follow these steps:

	- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
	- Add it to a libphutil library, or create a new library (for instructions,
	see @{article:libphutil Libraries User Guide}.
	- Configure Phabricator to load the library by adding it to `load-libraries`
	in the Phabricator config.
	- Configure Phabricator to install the event listener by adding the class
	name to `events.listeners` in the Phabricator config.

	You can verify your listener is registered in the "Events" tab of DarkConsole.
	It should appear at the top under "Registered Event Listeners". You can also
	see any events the page emitted there. For details on DarkConsole, see
	@{article:Using DarkConsole}.

	= Installing Event Listeners (Arcanist) =

	To install event listeners in Arcanist, follow these steps:

	- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
	- Add it to a libphutil library, or create a new library (for instructions,
	see @{article:libphutil Libraries User Guide}.
	- Configure Phabricator to load the library by adding it to `load`
	in the Arcanist config (e.g., `.arcconfig`, or user/global config).
	- Configure Arcanist to install the event listener by adding the class
	name to `events.listeners` in the Arcanist config.

	You can verify your listener is registered by running any `arc` command with
	`--trace`. You should see output indicating your class was registered as an
	event listener.

	= Example Listener =

	Phabricator includes an example event listener,
	@{class:PhabricatorExampleEventListener}, which may be useful as a starting
	point in developing your own listeners. This listener listens for a test
	event that is emitted by the script `scripts/util/emit_test_event.php`.

	If you run this script normally, it should output something like this:

	$ ./scripts/util/emit_test_event.php
	Emitting event...
	Done.

	This is because there are no listeners for the event, so nothing reacts to it
	when it is emitted. You can add the example listener by either adding it to
	your `events.listeners` configuration or with the `--listen` command-line flag:

	$ ./scripts/util/emit_test_event.php --listen PhabricatorExampleEventListener
	Installing 'PhabricatorExampleEventListener'...
	Emitting event...
	PhabricatorExampleEventListener got test event at 1341344566
	Done.

	This time, the listener was installed and had its callback invoked when the
	test event was emitted.

	= Available Events =

	You can find a list of all Phabricator events in @{class:PhabricatorEventType}.

	== All Events ==

	The special constant `PhutilEventType::TYPE_ALL` will let you listen for all
	events. Normally, you want to listen only to specific events, but if you're
	writing a generic handler you can listen to all events with this constant
	rather than by enumerating each event.

	== Arcanist Events ==

	Arcanist event constants are listed in @{class@arcanist:ArcanistEventType}.

	All Arcanist events have this data available:

	- - `workflow` The active @{class@arcanist:ArcanistBaseWorkflow}.
	+ - `workflow` The active @{class@arcanist:ArcanistWorkflow}.

	== Arcanist: Commit: Will Commit SVN ==

	The constant for this event is `ArcanistEventType::TYPE_COMMIT_WILLCOMMITSVN`.

	This event is dispatched before an `svn commit` occurs and allows you to
	modify the commit message. Data available on this event:

	- `message` The text of the message.

	== Arcanist: Diff: Will Build Message ==

	The constant for this event is `ArcanistEventType::TYPE_DIFF_WILLBUILDMESSAGE`.

	This event is dispatched before an editable message is presented to the user,
	and allows you to, e.g., fill in default values for fields. Data available
	on this event:

	- `fields` A map of field values to be compiled into a message.

	== Arcanist: Diff: Was Created ==

	The constant for this event is `ArcanistEventType::TYPE_DIFF_WASCREATED`.

	This event is dispatched after a diff is created. It is currently only useful
	for collecting timing information. No data is available on this event.

	== Arcanist: Revision: Will Create Revision ==

	The constant for this event is
	`ArcanistEventType::TYPE_REVISION_WILLCREATEREVISION`.

	This event is dispatched before a revision is created. It allows you to modify
	fields to, e.g., edit revision titles. Data available on this event:

	- `specification` Parameters that will be used to invoke the
	`differential.createrevision` Conduit call.

	== Controller: Check Request ==

	The constant for this event is
	`PhabricatorEventType::TYPE_CONTROLLER_CHECKREQUEST`.

	This event is dispatched when controller is about to begin execution. It is
	meant for checking if the user is allowed to use the application at the moment.
	It can check if the user has performed too many operations recently, if his IP
	address is allowed or if the servers are overloaded to process the request.
	Data available on this event:

	- `request` Object of class @{class:AphrontRequest}.
	- `controller` Class name of the current controller.

	You can delegate the execution to another controller by modifying `controller`.

	== Maniphest: Will Edit Task ==

	The constant for this event is
	`PhabricatorEventType::TYPE_MANIPHEST_WILLEDITTASK`.

	This event is dispatched before a task is edited, and allows you to respond to
	or alter the edit. Data available on this event:

	- ##task## The @{class:ManiphestTask} being edited.
	- ##transactions## The list of edits (objects of class
	@{class:ManiphestTransaction}) being applied.
	- ##new## A boolean indicating if this task is being created.
	- ##mail## If this edit originates from email, the
	@{class:PhabricatorMetaMTAReceivedMail} object.

	This is similar to the next event (did edit task) but occurs before the edit
	begins.

	== Maniphest: Did Edit Task ==

	The constant for this event is
	`PhabricatorEventType::TYPE_MANIPHEST_DIDEDITTASK`.

	This event is dispatched after a task is edited, and allows you to react to the
	edit. Data available on this event:

	- ##task## The @{class:ManiphestTask} that was edited.
	- ##transactions## The list of edits (objects of class
	@{class:ManiphestTransaction}) that were applied.
	- ##new## A boolean indicating if this task was newly created.
	- ##mail## If this edit originates from email, the
	@{class:PhabricatorMetaMTAReceivedMail} object.

	This is similar to the previous event (will edit task) but occurs after the
	edit completes.

	== Differential: Will Mark Generated ==

	The constant for this event is
	`PhabricatorEventType::TYPE_DIFFERENTIAL_WILLMARKGENERATED`.

	This event is dispatched before Differential decides if a file is generated (and
	doesn't need to be reviewed) or not. Data available on this event:

	- ##corpus## Body of the file.
	- ##is_generated## Boolean indicating if this file should be treated as
	generated.

	== Diffusion: Did Discover Commit ==

	The constant for this event is
	`PhabricatorEventType::TYPE_DIFFUSION_DIDDISCOVERCOMMIT`.

	This event is dispatched when the daemons discover a commit for the first time.
	This event happens very early in the pipeline, and not all commit information
	will be available yet. Data available on this event:

	- `commit` The @{class:PhabricatorRepositoryCommit} that was discovered.
	- `repository` The @{class:PhabricatorRepository} the commit was discovered
	in.

	== Diffusion: Lookup User ==

	The constant for this event is
	`PhabricatorEventType::TYPE_DIFFUSION_LOOKUPUSER`.

	This event is dispatched when the daemons are trying to link a commit to a
	Phabricator user account. You can listen for it to improve the accuracy of
	associating users with their commits.

	By default, Phabricator will try to find matches based on usernames, real names,
	or email addresses, but this can result in incorrect matches (e.g., if you have
	several employees with the same name) or failures to match (e.g., if someone
	changed their email address). Listening for this event allows you to intercept
	the lookup and supplement the results from another datasource.

	Data available on this event:

	- `commit` The @{class:PhabricatorRepositoryCommit} that data is being looked
	up for.
	- `query` The author or committer string being looked up. This will usually
	be something like "Abraham Lincoln <alincoln@logcabin.example.com>", but
	comes from the commit metadata so it may not be well-formatted.
	- `result` The current result from the lookup (Phabricator's best guess at
	the user PHID of the user named in the "query"). To substitute the result
	with a different result, replace this with the correct PHID in your event
	listener.

	Using @{class@libphutil:PhutilEmailAddress} may be helpful in parsing the query.

	== Search: Did Update Index ==

	The constant for this event is
	`PhabricatorEventType::TYPE_SEARCH_DIDUPDATEINDEX`.

	This event is dispatched from the Search application's indexing engine, after
	it indexes a document. It allows you to publish search-like indexes into other
	systems.

	Note that this event happens after the update is fully complete: you can not
	prevent or modify the update. Further, the event may fire significantly later
	in real time than the update, as indexing may occur in the background. You
	should use other events if you need guarantees about when the event executes.

	Finally, this event may fire more than once for a single update. For example,
	if the search indexes are rebuilt, this event will fire on objects which have
	not actually changed.

	So, good use cases for event listeners are:

	- Updating secondary search indexes.

	Bad use cases are:

	- Editing the object or document.
	- Anything with side effects, like sending email.

	Data available on this event:

	- `phid` The PHID of the updated object.
	- `object` The object which was updated (like a @{class:ManiphesTask}).
	- `document` The @{class:PhabricatorSearchAbstractDocument} which was indexed.
	This contains an abstract representation of the object, and may be useful
	in populating secondary indexes because it provides a uniform API.

	== Test: Did Run Test ==

	The constant for this event is
	`PhabricatorEventType::TYPE_TEST_DIDRUNTEST`.

	This is a test event for testing event listeners. See above for details.

	== UI: Did Render Actions ==

	The constant for this event is
	`PhabricatorEventType::TYPE_UI_DIDRENDERACTIONS`.

	This event is dispatched after a @{class:PhabricatorActionListView} is built by
	the UI. It allows you to add new actions that your application may provide, like
	"Fax this Object". Data available on this event:

	- `object` The object which actions are being rendered for.
	- `actions` The current list of available actions.

	NOTE: This event is unstable and subject to change.

	= Debugging Listeners =

	If you're having problems with your listener, try these steps:

	- If you're getting an error about Phabricator being unable to find the
	listener class, make sure you've added it to a libphutil library and
	configured Phabricator to load the library with `load-libraries`.
	- Make sure the listener is registered. It should appear in the "Events" tab
	of DarkConsole. If it's not there, you may have forgotten to add it to
	`events.listeners`.
	- Make sure it calls `listen()` on the right events in its `register()`
	method. If you don't listen for the events you're interested in, you
	won't get a callback.
	- Make sure the events you're listening for are actually happening. If they
	occur on a normal page they should appear in the "Events" tab of
	DarkConsole. If they occur on a POST, you could add a `phlog()`
	to the source code near the event and check your error log to make sure the
	code ran.
	- You can check if your callback is getting invoked by adding `phlog()` with
	a message and checking the error log.
	- You can try listening to `PhutilEventType::TYPE_ALL` instead of a specific
	event type to get all events, to narrow down whether problems are caused
	by the types of events you're listening to.
	- You can edit the `emit_test_event.php` script to emit other types of
	events instead, to test that your listener reacts to them properly. You
	might have to use fake data, but this gives you an easy way to test the
	at least the basics.
	- For scripts, you can run under `--trace` to see which events are emitted
	and how many handlers are listening to each event.

	= Next Steps =

	Continue by:

	- taking a look at @{class:PhabricatorExampleEventListener}; or
	- building a library with @{article:libphutil Libraries User Guide}.

File Metadata

Mime Type: text/x-diff
Expires: Sat, Nov 15, 8:30 AM (19 h, 28 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 337726
Default Alt Text: (27 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions