@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Write a "Developer Setup" guide for onboarding
Summary: Fixes T11561. Collect guidance about local configuration which hasn't been obvious in the past.
Test Plan:
- Read document carefully.
- Used `./bin/diviner generate` to generate documentation.
- Previewed in Diviner locally:
{F4795021}
Reviewers: amckinley, chad
Reviewed By: chad
Subscribers: cspeckmim
Maniphest Tasks: T11561
Differential Revision: https://secure.phabricator.com/D17641
+112
+112
src/docs/contributor/developer_setup.diviner
+112
src/docs/contributor/developer_setup.diviner
···
1
+
@title Developer Setup
2
+
@group developer
3
+
4
+
How to configure a Phabricator development environment.
5
+
6
+
Overview
7
+
========
8
+
9
+
There are some options and workflows that may be useful if you are developing
10
+
or debugging Phabricator.
11
+
12
+
13
+
Configuration
14
+
=============
15
+
16
+
To adjust Phabricator for development:
17
+
18
+
- Enable `phabricator.developer-mode` to enable some options and show
19
+
more debugging information.
20
+
- Enable `phabricator.show-prototypes` to show all the incomplete
21
+
applications.
22
+
- See @{article: Using DarkConsole} for instructions on enabling the
23
+
debugging console.
24
+
25
+
26
+
Error Handling
27
+
==============
28
+
29
+
Errors normally go to DarkConsole (if enabled) and the webserver error log,
30
+
which is often located somewhere like `/var/log/apache/error_log`. This file
31
+
often contains relevant information after you encounter an error.
32
+
33
+
When debugging, you can print information to the error log with `phlog(...)`.
34
+
You can `phlog(new Exception(...))` to get a stack trace.
35
+
36
+
You can print information to the UI with `throw new Exception(...)`,
37
+
`print_r(...)`, or `var_dump(...)`.
38
+
39
+
You can abort execution with `die(...)` if you want to make sure execution
40
+
does not make it past some point. Normally `throw` does this too, but callers
41
+
can `catch` exceptions; they can not catch `die(...)`.
42
+
43
+
44
+
Utilities
45
+
=========
46
+
47
+
After adding, renaming, or moving classes, run `arc liberate` to rebuild
48
+
the class map:
49
+
50
+
```
51
+
phabricator/ $ arc liberate
52
+
```
53
+
54
+
Until you do this, Phabricator won't recognize your new, moved, or renamed
55
+
classes. You do not need to run this after modifying an existing class.
56
+
57
+
After any modifications to static resources (CSS / JS) but before sending
58
+
changes for review or pushing them to the remote, run `bin/celerity map`:
59
+
60
+
```
61
+
phabricator/ $ ./bin/celerity map
62
+
```
63
+
64
+
This rebuilds the static resource map.
65
+
66
+
If you forget to run these commands you'll normally be warned by unit tests,
67
+
but knowing about them may prevent confusion before you hit the warnings.
68
+
69
+
70
+
Command Line
71
+
============
72
+
73
+
Almost every script supports a `--trace` flag, which prints out service
74
+
calls and more detailed error information. This is often the best way to get
75
+
started with debugging command-line scripts.
76
+
77
+
78
+
Performance
79
+
===========
80
+
81
+
Although it is more user-focused than developer-focused, the
82
+
@{article:Troubleshooting Performance Problems} guide has useful information
83
+
on the tools available for diagnosing and understanding performance problems.
84
+
85
+
86
+
Custom Domains
87
+
==============
88
+
89
+
If you're working with applications that support custom domains (like Phurl or
90
+
Phame) you can normally test them by adding more entries to your webserver
91
+
configuration that look exactly like the primary entry (or expanding the
92
+
primary entry to match more domains).
93
+
94
+
Phabricator routes all requests based on host headers, so alternate domains
95
+
do not normally need any kind of special configuration.
96
+
97
+
You may also need to add `/etc/hosts` entries for the domains themselves.
98
+
99
+
100
+
Creating Test Data
101
+
==================
102
+
103
+
You can create test objects with the "Lipsum" utility:
104
+
105
+
```
106
+
phabricator/ $ ./bin/lipsum help generate
107
+
phabricator/ $ ./bin/lipsum generate ...
108
+
```
109
+
110
+
Test data can make your local install feel a little more realistic. With
111
+
`--quickly`, you can generate a large amount of test data to help test issues
112
+
with performance or scale.