@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
Update Diviner documentation to reference Phorge instead of Phabricator.
Summary: This commit also removes references to support pacts and updates links to point to the new upstream.
Test Plan: Generated Diviner documentation on a local install and verified that the changes look good.
Reviewers: O1 Blessed Committers, chris
Reviewed By: O1 Blessed Committers, chris
Subscribers: chris, speck, tobiaswiese
Maniphest Tasks: T15012
Differential Revision: https://we.phorge.it/D25007
+1712
-1399
+5
-5
src/docs/book/contributor.book
+5
-5
src/docs/book/contributor.book
···
1
1
{
2
-
"name": "phabcontrib",
3
-
"title": "Phabricator Contributor Documentation",
4
-
"short": "Phabricator Contributor Docs",
5
-
"preface": "Information for Phabricator contributors and developers.",
2
+
"name": "contrib",
3
+
"title": "Phorge Contributor Documentation",
4
+
"short": "Contributor Docs",
5
+
"preface": "Information for Phorge contributors and developers.",
6
6
"root": "../../../",
7
7
"uri.source":
8
-
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
8
+
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
9
9
"rules": {
10
10
"(\\.diviner$)": "DivinerArticleAtomizer"
11
11
},
+5
-8
src/docs/book/flavor.book
+5
-8
src/docs/book/flavor.book
···
1
1
{
2
-
"name": "phabflavor",
3
-
"title": "Phabricator Flavor Text",
2
+
"name": "flavor",
3
+
"title": "Phorge Flavor Text",
4
4
"short": "Flavor Text",
5
-
"preface": "Recommendations, lore, and dark rituals.",
5
+
"preface": "A collection of short articles which pertain to software development in general, not necessarily to Phorge specifically.",
6
6
"root": "../../../",
7
7
"uri.source":
8
-
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
8
+
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
9
9
"rules": {
10
10
"(\\.diviner$)": "DivinerArticleAtomizer"
11
11
},
···
20
20
"(^webroot/rsrc/externals/)"
21
21
],
22
22
"groups": {
23
-
"overview": {
24
-
"name": "Overview"
25
-
},
26
23
"javascript": {
27
24
"name": "Javascript"
28
25
},
29
26
"lore": {
30
-
"name": "Phabricator Lore"
27
+
"name": "Phorge Lore"
31
28
},
32
29
"php": {
33
30
"name": "PHP"
+5
-5
src/docs/book/phabricator.book
src/docs/book/phorge.book
+5
-5
src/docs/book/phabricator.book
src/docs/book/phorge.book
···
1
1
{
2
-
"name": "phabdev",
3
-
"title": "Phabricator Technical Documentation",
4
-
"short": "Phabricator Tech Docs",
5
-
"preface": "Technical reference material for Phabricator developers.",
2
+
"name": "dev",
3
+
"title": "Phorge Technical Documentation",
4
+
"short": "Tech Docs",
5
+
"preface": "Technical reference material for Phorge developers.",
6
6
"root": "../../../",
7
7
"uri.source":
8
-
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
8
+
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
9
9
"rules": {
10
10
"(\\.diviner$)": "DivinerArticleAtomizer",
11
11
"(\\.php$)": "DivinerPHPAtomizer"
+5
-8
src/docs/book/user.book
+5
-8
src/docs/book/user.book
···
1
1
{
2
-
"name": "phabricator",
3
-
"title": "Phabricator User Documentation",
4
-
"short": "Phabricator User Docs",
5
-
"preface": "Instructions for installing, configuring, and using Phabricator.",
2
+
"name": "phorge",
3
+
"title": "Phorge User Documentation",
4
+
"short": "User Docs",
5
+
"preface": "Instructions for installing, configuring, and using Phorge.",
6
6
"root": "../../../",
7
7
"uri.source":
8
-
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
8
+
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
9
9
"rules": {
10
10
"(\\.diviner$)": "DivinerArticleAtomizer"
11
11
},
···
37
37
},
38
38
"fieldmanual": {
39
39
"name": "Field Manuals"
40
-
},
41
-
"cellar": {
42
-
"name": "Musty Cellar"
43
40
}
44
41
}
45
42
}
+38
-39
src/docs/contributor/adding_new_classes.diviner
+38
-39
src/docs/contributor/adding_new_classes.diviner
···
1
1
@title Adding New Classes
2
2
@group developer
3
3
4
-
Guide to adding new classes to extend Phabricator.
4
+
Guide to adding new classes to extend Phorge.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator is highly modular, and many parts of it can be extended by adding
9
+
Phorge is highly modular, and many parts of it can be extended by adding
10
10
new classes. This document explains how to write new classes to change or
11
-
expand the behavior of Phabricator.
11
+
expand the behavior of Phorge.
12
12
13
-
IMPORTANT: The upstream does not offer support with extension development.
13
+
NOTE: The upstream offers limited support with extension development.
14
14
15
15
Fundamentals
16
16
============
17
17
18
-
Phabricator primarily discovers functionality by looking at concrete subclasses
19
-
of some base class. For example, Phabricator determines which applications are
18
+
Phorge primarily discovers functionality by looking at concrete subclasses
19
+
of some base class. For example, Phorge determines which applications are
20
20
available by looking at all of the subclasses of
21
21
@{class@phabricator:PhabricatorApplication}. It
22
22
discovers available workflows in `arc` by looking at all of the subclasses of
···
24
24
by looking at all of the subclasses of @{class@arcanist:PhutilLocale}.
25
25
26
26
This pattern holds in many cases, so you can often add functionality by adding
27
-
new classes with no other work. Phabricator will automatically discover and
27
+
new classes with no other work. Phorge will automatically discover and
28
28
integrate the new capabilities or features at runtime.
29
29
30
30
There are two main ways to add classes:
···
42
42
Extensions Directory
43
43
====================
44
44
45
-
The easiest way to extend Phabricator by adding new classes is to drop them
46
-
into the extensions directory, at `phabricator/src/extensions/`.
45
+
The easiest way to extend Phorge by adding new classes is to drop them
46
+
into the extensions directory, at `pohrge/src/extensions/`.
47
47
48
48
This is intended as a quick way to add small pieces of functionality, test new
49
-
features, or get started on a larger project. Extending Phabricator like this
49
+
features, or get started on a larger project. Extending Phorge like this
50
50
imposes a small performance penalty compared to using a library.
51
51
52
-
This directory exists in all libphutil libraries, so you can find a similar
52
+
This directory also exists for Arcanist, so you can find a similar
53
53
directory in `arcanist/src/extensions/`.
54
54
55
55
For example, to add a new application, create a file like this one and add it
56
-
to `phabricator/src/extensions/`.
56
+
to `phorge/src/extensions/`.
57
57
58
-
```name=phabricator/src/extensions/ExampleApplication.php, lang=php
58
+
```name=phorge/src/extensions/ExampleApplication.php, lang=php
59
59
<?php
60
60
61
61
final class ExampleApplication extends PhabricatorApplication {
···
69
69
70
70
If you load {nav Applications} in the web UI, you should now see your new
71
71
application in the list. It won't do anything yet since you haven't defined
72
-
any interesting behavior, but this is the basic building block of Phabricator
72
+
any interesting behavior, but this is the basic building block of Phorge
73
73
extensions.
74
74
75
75
76
76
Creating Libraries
77
77
==================
78
78
79
-
A more powerful (but more complicated) way to extend Phabricator is to create
80
-
a libphutil library. Libraries can organize a larger amount of code, are easier
79
+
A more powerful (but more complicated) way to extend Phorge is to create
80
+
a library. Libraries can organize a larger amount of code, are easier
81
81
to work with and distribute, and have slightly better performance than loose
82
82
source files in the extensions directory.
83
83
···
85
85
86
86
- Create a new directory.
87
87
- Use `arc liberate` to initialize and name the library.
88
-
- Configure Phabricator or Arcanist to load the library.
88
+
- Configure Phorge or Arcanist to load the library.
89
89
90
90
Then, to add new code, you do this:
91
91
···
95
95
Initializing a Library
96
96
======================
97
97
98
-
To create a new libphutil library, create a directory for it and run
98
+
To create a new library, create a directory for it and run
99
99
`arc liberate` on the directory. This documentation will use a conventional
100
100
directory layout, which is recommended, but you are free to deviate from this.
101
101
···
143
143
(functions and classes) in the library, which allows them to be autoloaded
144
144
at runtime and dependencies to be statically managed by `arc liberate`.
145
145
146
-
Linking with Phabricator
147
-
========================
146
+
Linking with Phorge
147
+
===================
148
148
149
-
If you aren't using this library with Phabricator (e.g., you are only using it
150
-
with Arcanist or are building something else on libphutil) you can skip this
149
+
(NOTE) If you aren't using this library with Phorge (e.g., you are only using it
150
+
with Arcanist or are building something else) you can skip this
151
151
step.
152
152
153
-
But, if you intend to use this library with Phabricator, you need to define its
154
-
dependency on Phabricator by creating a `.arcconfig` file which points at
155
-
Phabricator. For example, you might write this file to
153
+
But, if you intend to use this library with Phorge, you need to define its
154
+
dependency on Phorge by creating a `.arcconfig` file which points at
155
+
Phorge. For example, you might write this file to
156
156
`libcustom/.arcconfig`:
157
157
158
158
```lang=json
159
159
{
160
160
"load": [
161
-
"phabricator/src/"
161
+
"phorge/src/"
162
162
]
163
163
}
164
164
```
165
165
166
166
For details on creating a `.arcconfig`, see
167
167
@{article:Arcanist User Guide: Configuring a New Project}. In general, this
168
-
tells `arc liberate` that it should look for symbols in Phabricator when
168
+
tells `arc liberate` that it should look for symbols in Phorge when
169
169
performing static analysis.
170
170
171
-
NOTE: If Phabricator isn't located next to your custom library, specify a
172
-
path which actually points to the `phabricator/` directory.
171
+
NOTE: If Phorge isn't located next to your custom library, specify a
172
+
path which actually points to the `phorge/` directory.
173
173
174
174
You do not need to declare dependencies on `arcanist`, since `arc liberate`
175
175
automatically loads them.
176
176
177
-
Finally, edit your Phabricator config to tell it to load your library at
177
+
Finally, edit your Phorge config to tell it to load your library at
178
178
runtime, by adding it to `load-libraries`:
179
179
180
180
```lang=json
···
185
185
...
186
186
```
187
187
188
-
Now, Phabricator will be able to load classes from your custom library.
188
+
Now, Phorge will be able to load classes from your custom library.
189
189
190
190
191
191
Writing Classes
···
206
206
What You Can Extend And Invoke
207
207
==============================
208
208
209
-
Arcanist and Phabricator are strict about extensibility of classes and
209
+
Arcanist and Pohrge are strict about extensibility of classes and
210
210
visibility of methods and properties. Most classes are marked `final`, and
211
211
methods have the minimum required visibility (protected or private). The goal
212
212
of this strictness is to make it clear what you can safely extend, access, and
213
213
invoke, so your code will keep working as the upstream changes.
214
214
215
-
IMPORTANT: We'll still break APIs frequently. The upstream does not support
216
-
extension development, and none of these APIs are stable.
215
+
IMPORTANT: We'll still break APIs frequently. The upstream offers limited
216
+
support for extension development, and none of these APIs are stable.
217
217
218
-
When developing libraries to work with Arcanist and Phabricator, you should
218
+
When developing libraries to work with Arcanist and Phorge, you should
219
219
respect method and property visibility.
220
220
221
221
If you want to add features but can't figure out how to do it without changing
222
-
Phabricator code, here are some approaches you may be able to take:
222
+
Phorge code, here are some approaches you may be able to take:
223
223
224
224
- {icon check, color=green} **Use Composition**: If possible, use composition
225
225
rather than extension to build your feature.
···
228
228
- {icon check, color=green} **File a Feature Request**: Let us know what your
229
229
use case is so we can make the class tree more flexible or configurable, or
230
230
point you at the right way to do whatever you're trying to do, or explain
231
-
why we don't let you do it. Note that we **do not support** extension
232
-
development so you may have mixed luck with this one.
231
+
why we don't let you do it.
233
232
234
233
These approaches are **discouraged**, but also possible:
235
234
···
252
251
253
252
Continue by:
254
253
255
-
- visiting the [[ https://secure.phabricator.com/w/community_resources/ |
254
+
- visiting the [[ https://we.phorge.it/w/community_resources/ |
256
255
Community Resources ]] page to find or share extensions and libraries.
+6
-8
src/docs/contributor/adding_new_css_and_js.diviner
+6
-8
src/docs/contributor/adding_new_css_and_js.diviner
···
1
1
@title Adding New CSS and JS
2
2
@group developer
3
3
4
-
Explains how to add new CSS and JS files to Phabricator.
4
+
Explains how to add new CSS and JS files to Phorge.
5
5
6
6
= Overview =
7
7
8
-
Phabricator uses a system called **Celerity** to manage static resources. If you
9
-
are a current or former Facebook employee, Celerity is based on the Haste system
10
-
used at Facebook and generally behaves similarly.
8
+
Phorge uses a system called **Celerity** to manage static resources.
11
9
12
-
This document is intended for Phabricator developers and contributors. This
10
+
(NOTE) This document is intended for Phorge developers and contributors. This
13
11
process will not work correctly for third-party code, plugins, or extensions.
14
12
15
13
= Adding a New File =
16
14
17
15
To add a new CSS or JS file, create it in an appropriate location in
18
-
`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phabricator/`
16
+
`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phorge/`
19
17
directory.
20
18
21
19
Each file must `@provides` itself as a component, declared in a header comment:
···
54
52
When you add, move or remove a file, or change the contents of existing JS or
55
53
CSS file, you should rebuild the Celerity map:
56
54
57
-
phabricator/ $ ./bin/celerity map
55
+
phorge/ $ ./bin/celerity map
58
56
59
57
If you've only changed file content things will generally work even if you
60
58
don't, but they might start not working as well in the future if you skip this
···
64
62
quite often. They can be resolved by running the Celerity mapper. You can
65
63
automate this process by running:
66
64
67
-
phabricator/ $ ./scripts/celerity/install_merge.sh
65
+
phorge/ $ ./scripts/celerity/install_merge.sh
68
66
69
67
This will install Git merge driver which will run when a conflict in this file
70
68
occurs.
+4
-4
src/docs/contributor/assistive_technologies.diviner
+4
-4
src/docs/contributor/assistive_technologies.diviner
···
1
1
@title Assistive Technologies
2
2
@group developer
3
3
4
-
Information about making Phabricator accessible to assistive technologies.
4
+
Information about making Phorge accessible to assistive technologies.
5
5
6
6
Overview
7
7
========
···
10
10
screen readers can assist people with limited or no eyesight by reading the
11
11
contents of pages aloud.
12
12
13
-
Phabricator has some support for assistive technologies, and we'd like to have
13
+
Phorge has some support for assistive technologies, and we'd like to have
14
14
more support. This document describes how to use the currently available
15
-
features to improve the accessibility of Phabricator.
15
+
features to improve the accessibility of Phorge.
16
16
17
17
18
18
Aural-Only Elements
···
72
72
======================
73
73
74
74
To verify aural markup, you can add `?__aural__=1` to any page URI. This will
75
-
make Phabricator render the page with styles that reveal aural-only elements and
75
+
make Phorge render the page with styles that reveal aural-only elements and
76
76
mute visual-only elements.
+152
-1
src/docs/contributor/bug_reports.diviner
+152
-1
src/docs/contributor/bug_reports.diviner
···
1
1
@title Contributing Bug Reports
2
2
@group detail
3
3
4
-
Effective June 1, 2021: Phabricator is no longer actively maintained and no longer accepts bug reports.
4
+
Describes how to file an effective Phorge bug report.
5
+
6
+
7
+
Overview
8
+
========
9
+
10
+
This article describes how to file an effective Phorge bug report.
11
+
12
+
The most important things to do are:
13
+
14
+
- check the list of common fixes below;
15
+
- make sure Phorge is up to date;
16
+
- make sure we support your setup;
17
+
- gather debugging information; and
18
+
- explain how to reproduce the issue.
19
+
20
+
The rest of this article walks through these points in detail.
21
+
22
+
For general information on contributing to Phorge, see
23
+
@{article:Contributor Introduction}.
24
+
25
+
26
+
Common Fixes
27
+
============
28
+
29
+
Before you file a report, here are some common solutions to problems:
30
+
31
+
- **Update Phorge**: We receive a lot of bug reports about issues we have
32
+
already fixed in HEAD. Updating often resolves issues. It is common for
33
+
issues to be fixed in less than 24 hours, so even if you've updated recently
34
+
you should update again. If you aren't sure how to update, see the next
35
+
section.
36
+
- **Update Libraries**: Make sure `arcanist/` and `phorge/` are all up
37
+
to date. Users often update `phorge/` but forget to update `arcanist/`.
38
+
When you update, make sure you update both libraries.
39
+
- **Restart Apache or PHP-FPM**: Phorge uses caches which don't get
40
+
reset until you restart Apache or PHP-FPM. After updating, make sure you
41
+
restart.
42
+
43
+
44
+
Update Phorge
45
+
=============
46
+
47
+
Before filing a bug, make sure you are up to date. We receive many bug reports
48
+
for issues we have already fixed, and even if we haven't fixed an issue we'll
49
+
be able to resolve it more easily if you file a report based on HEAD. (For
50
+
example, an old stack trace may not have the right line numbers, which will
51
+
make it more difficult for us to figure out what's going wrong.)
52
+
53
+
To update Phorge, use a script like the one described in
54
+
@{article:Upgrading Phorge}.
55
+
56
+
**If you can not update** for some reason, please include the version of
57
+
Phorge and Arcanist you are running when you file a report.
58
+
59
+
For help, see @{article:Providing Version Information}.
60
+
61
+
62
+
Supported Issues
63
+
================
64
+
65
+
Before filing a bug, make sure you're filing an issue against something we
66
+
support.
67
+
68
+
**We can NOT help you with issues we can not reproduce.** It is critical that
69
+
you explain how to reproduce the issue when filing a report.
70
+
71
+
For help, see @{article:Providing Reproduction Steps}.
72
+
73
+
**We do NOT support prototype applications.** If you're running into an issue
74
+
with a prototype application, you're on your own. For more information about
75
+
prototype applications, see @{article:User Guide: Prototype Applications}.
76
+
77
+
**We do NOT support third-party packages or instructions.** If you installed
78
+
Phorge (or configured some aspect of it) using a third-party package or by
79
+
following a third-party guide (like a blog post), we can not help you.
80
+
Phorge changes quickly and third-party information is unreliable and often
81
+
falls out of date. Contact the maintainer of the package or guide you used,
82
+
or reinstall following the upstream instructions.
83
+
84
+
**We do NOT support custom code development or third-party libraries.** If
85
+
you're writing an extension, you're on your own. We provide some documentation,
86
+
but can not help you with extension or library development. If you downloaded a
87
+
library from somewhere, contact the library maintainer.
88
+
89
+
**We do NOT support bizarre environments.** If your issue is specific to an
90
+
unusual installation environment, we generally will not help you find a
91
+
workaround. Install Phorge in a normal environment instead. Examples of
92
+
unusual environments are shared hosts, nontraditional hosts (gaming consoles,
93
+
storage appliances), and hosts with unusually tight resource constraints. The
94
+
vast majority of users run Phorge in normal environments (modern computers
95
+
with root access) and these are the only environments we support.
5
96
97
+
Otherwise, if you're having an issue with a supported first-party application
98
+
and followed the upstream install instructions on a normal computer, we're happy
99
+
to try to help.
100
+
101
+
102
+
Getting More Information
103
+
========================
104
+
105
+
For some issues, there are places you can check for more information. This may
106
+
help you resolve the issue yourself. Even if it doesn't, this information can
107
+
help us figure out and resolve an issue.
108
+
109
+
- For issues with `arc` or any other command-line script, you can get more
110
+
details about what the script is doing by adding the `--trace` flag.
111
+
- For issues with Phorge, check your webserver error logs.
112
+
- For Apache, this is often `/var/log/httpd/error.log`, or
113
+
`/var/log/apache2/error.log` or similar.
114
+
- For nginx, check both the nginx and php-fpm logs.
115
+
- For issues with the UI, check the Javascript error console in your web
116
+
browser.
117
+
- Some other things, like daemons, have their own debug flags or
118
+
troubleshooting steps. Check the documentation for information on
119
+
troubleshooting. Adjusting settings or enabling debugging modes may give
120
+
you more information about the issue.
121
+
122
+
123
+
Reproducibility
124
+
===============
125
+
126
+
The most important part of your report content is instructions on how to
127
+
reproduce the issue. What did you do? If you do it again, does it still break?
128
+
Does it depend on a specific browser? Can you reproduce the issue on
129
+
a fresh, unmodified Phorge instance?
130
+
131
+
It is nearly impossible for us to resolve many issues if we can not reproduce
132
+
them. We will not accept reports which do not contain the information required
133
+
to reproduce problems.
134
+
135
+
For help, see @{article:Providing Reproduction Steps}.
136
+
137
+
138
+
File a Bug Report
139
+
=================
140
+
141
+
If you're up to date, have collected information about the problem, and have
142
+
the best reproduction instructions you can come up with, you're ready
143
+
to file a report.
144
+
145
+
It is **particularly critical** that you include reproduction steps.
146
+
147
+
You can file a report [[ https://we.phorge.it/maniphest/task/edit/form/2/ | on this instance]].
148
+
149
+
150
+
Next Steps
151
+
==========
152
+
153
+
Continue by:
154
+
155
+
- reading general support information in @{article:Support Resources}; or
156
+
- returning to the @{article:Contributor Introduction}.
-169
src/docs/contributor/cla.diviner
-169
src/docs/contributor/cla.diviner
···
1
-
@title Understanding the Phacility CLA
2
-
@group detail
3
-
4
-
Describes the Contributor License Agreement (CLA).
5
-
6
-
Overview
7
-
========
8
-
9
-
IMPORTANT: This document is not legal advice.
10
-
11
-
Phacility requires contributors to sign a Contributor License Agreement
12
-
(often abbreviated "CLA") before we can accept contributions into the upstream.
13
-
This document explains what this document means and why we require it.
14
-
15
-
This requirement is not unusual, and many large open source projects require a
16
-
similar CLA, including Python, Go, jQuery, and Apache Software Foundation
17
-
projects.
18
-
19
-
You can read more about CLAs and find more examples of companies and projects
20
-
which require them on Wikipedia's
21
-
[[ https://en.wikipedia.org/wiki/Contributor_License_Agreement | CLA ]] page.
22
-
23
-
Our CLA is substantially similar to the CLA required by Apache, the
24
-
"Apache Individual Contributor License Agreement V2.0". Many projects which
25
-
require a CLA use this CLA or a similar one.
26
-
27
-
28
-
Why We Require a CLA
29
-
====================
30
-
31
-
While many projects require a CLA, others do not. This project requires a CLA
32
-
primarily because:
33
-
34
-
- it gives us certain rights, particularly the ability to relicense the work
35
-
later;
36
-
- it makes the terms of your contribution clear, protecting us from liability
37
-
related to copyright and patent disputes.
38
-
39
-
**More Rights**: We consider the cost of maintaining changes to greatly
40
-
outweigh the cost of writing them in the first place. When we accept work
41
-
into the upstream, we are agreeing to bear that maintenance cost.
42
-
43
-
This cost is not worthwhile to us unless the changes come with no strings
44
-
attached. Among other concerns, we would be unable to redistribute Phabricator
45
-
under a different license in the future without the additional rights the CLA
46
-
gives us.
47
-
48
-
For a concrete example of the problems this causes, Bootstrap switched from
49
-
GPLv2 to MIT in 2012-2013. You can see the issue tracking the process and read
50
-
about what they had to go through to do this here:
51
-
52
-
https://github.com/twbs/bootstrap/issues/2054
53
-
54
-
This took almost 18 months and required a huge amount of effort. We are not
55
-
willing to encumber the project with that kind of potential cost in order to
56
-
accept contributions.
57
-
58
-
The rights you give us by signing the CLA allow us to release the software
59
-
under a different license later without asking you for permission, including a
60
-
license you may not agree with.
61
-
62
-
They do not allow us to //undo// the existing release under the Apache license,
63
-
but allow us to make an //additional// release under a different license, or
64
-
release under multiple licenses (if we do, users may choose which license or
65
-
licenses they wish to use the software under). It would also allow us to
66
-
discontinue updating the release under the Apache license.
67
-
68
-
While we do not currently plan to relicense Phabricator, we do not want to
69
-
give up the ability to do so: we may want or need to in the future.
70
-
71
-
The most likely scenario which would lead to us changing the license is if a
72
-
new version of the Apache license is released. Open source software licenses
73
-
are still largely untested in the US legal system, and they may face challenges
74
-
in the future which could require adapting them to a changing legal
75
-
environment. If this occurs, we would want to be able to update to a newer
76
-
version of the license which accounted for these changes.
77
-
78
-
It is also possible that we may want to change open source licenses (for
79
-
example, to MIT) or adopt dual-licensing (for example, both Apache and MIT). We
80
-
might want to do this so that our license is compatible with the licenses used
81
-
by other software we want to be distributed alongside.
82
-
83
-
Although we currently believe it is unlikely, it is also possible we may want
84
-
to relicense Phabricator under a closed, proprietary, or literally evil license.
85
-
By signing the CLA, you are giving us the power to do this without requiring
86
-
you to consent. If you are not comfortable with this, do not sign the CLA and
87
-
do not contribute to Phabricator.
88
-
89
-
**Limitation of Liability**: The second benefit the CLA provides is that it
90
-
makes the terms of your contribution explicitly clear upfront, and it puts us
91
-
in a much stronger legal position if a contributor later claims there is
92
-
ambiguity about ownership of their work. We can point at the document they
93
-
signed as proof that they consented to our use and understood the terms of
94
-
their contribution.
95
-
96
-
//SCO v. IBM// was a lawsuit filed in 2003 alleging (roughly) that IBM had
97
-
improperly contributed code owned by SCO to Linux. The details of this and the
98
-
subsequent cases are very complex and the situation is not a direct parallel to
99
-
anything we are likely to face, but SCO claimed billions of dollars in damages
100
-
and the litigation has now been ongoing for more than a decade.
101
-
102
-
We want to avoid situations like this in the future by making the terms of
103
-
contribution explicit upfront.
104
-
105
-
Generally, we believe the terms of the CLA are fair and reasonable for
106
-
contributors, and that the primary way contributors benefit from contributing
107
-
to Phabricator is that we publish and maintain their changes so they do not
108
-
have to fork the software.
109
-
110
-
If you have strong ideological reasons for contributing to open source, you may
111
-
not be comfortable with the terms of the CLA (for example, it may be important
112
-
to you that your changes are never available under a license which you haven't
113
-
explicitly approved). This is fine and we can understand why contributors may
114
-
hold this viewpoint, but we can not accept your changes into the upstream.
115
-
116
-
117
-
Corporate vs Individual CLAs
118
-
============================
119
-
120
-
We offer two CLAs:
121
-
122
-
- {L28}
123
-
- {L30}
124
-
125
-
These are both substantially similar to the corresponding Apache CLAs.
126
-
127
-
If you own the work you are contributing, sign the individual CLA. If your
128
-
employer owns the work you are contributing, have them sign the corporate CLA.
129
-
130
-
**If you are employed, there is a substantial possibility that your employer
131
-
owns your work.** If they do, you do not have the right to contribute it to us
132
-
or assign the rights that we require, and can not contribute under the
133
-
individual CLA. Work with your employer to contribute under the corporate CLA
134
-
instead.
135
-
136
-
Particularly, this clause in the individual CLA is the important one:
137
-
138
-
> 4. You represent that you are legally entitled to grant the above license. If
139
-
> your employer(s) has rights to intellectual property that you create that
140
-
> includes your Contributions, you represent that you have received permission
141
-
> to make Contributions on behalf of that employer, that your employer has
142
-
> waived such rights for your Contributions to Phacility, or that your employer
143
-
> has executed a separate Corporate CLA with Phacility.
144
-
145
-
Ownership of your work varies based on where you live, how you are employed,
146
-
and your agreements with your employer. However, at least in the US, it is
147
-
likely that your employer owns your work unless you have anticipated conflicts
148
-
and specifically avoided them. This generally makes sense: if you are paid by
149
-
your employer for your work, they own the product of your work and you receive
150
-
salary and benefits in fair exchange for that work.
151
-
152
-
Your employer may have an ownership claim on your work even if you perform it
153
-
on your own time, if you use their equipment (like a company laptop or phone),
154
-
resources, facilities, or trade secrets, or signed something like an "Invention
155
-
Assignment Agreement" when you were hired. Such agreements are common. The
156
-
details of the strength of their claim will vary based on your situation and
157
-
local law.
158
-
159
-
If you are unsure, you should speak with your employer or a lawyer. If you
160
-
contribute code you do not own under the individual CLA, you are exposing
161
-
yourself to liability. You may also be exposing us to liability, but we'll have
162
-
the CLA on our side to show that we were unwilling pawns in your malicious
163
-
scheme to defraud your employer.
164
-
165
-
The good news is that most employers are happy to contribute to open source
166
-
projects. Incentives are generally well aligned: they get features they want,
167
-
and it reflects well on them. In the past, potential contributors who have
168
-
approached their employers about a corporate CLA have generally had little
169
-
difficulty getting approval.
+5
-18
src/docs/contributor/contrib_intro.diviner
+5
-18
src/docs/contributor/contrib_intro.diviner
···
1
1
@title Contributor Introduction
2
2
@group contrib
3
3
4
-
Introduction to contributing to Phabricator and Arcanist.
4
+
Introduction to contributing to Phorge and Arcanist.
5
5
6
6
Overview
7
7
========
8
8
9
-
If you'd like to contribute to Phabricator, this document can guide you though
9
+
If you'd like to contribute to Phorge, this document can guide you though
10
10
ways you can help improve the project.
11
11
12
12
Writing code is valuable, but often isn't the best or easiest way to contribute.
···
19
19
20
20
Without writing any code, learning the whole codebase, making a big time
21
21
commitment, or having to touch PHP, here are some ways you can materially
22
-
contribute to Phabricator:
22
+
contribute to Phorge:
23
23
24
-
- Drop by the [[ https://phurl.io/u/discourse | community forum ]] just to
25
-
say "thanks". A big part of the reason we build this software is to help
26
-
people solve problems, and knowing that our efforts are appreciated is
27
-
really rewarding.
28
-
- Recommend Phabricator to people who you think might find it useful. Our
24
+
- Recommend Phorge to people who you think might find it useful. Our
29
25
most powerful growth channel is word of mouth, and mentioning or tweeting
30
-
about Phabricator helps the project grow. If writing a tweet sounds like
31
-
too much work, you can use one of these form tweets written by our PR
32
-
department to quickly and easily shill on our behalf. Hail corporate!
33
-
34
-
> Phabricator seems like it's pretty okay
35
-
36
-
> I am not being paid to mention Phabricator in this extemporaneous, completely organic tweet
37
-
38
-
> Phabricator is objectively the best thing. Source: I am a certified, internationally recognized expert.
39
-
26
+
about Phorge helps the project grow.
40
27
- Submit high-quality bug reports by carefully following the guide in
41
28
@{article:Contributing Bug Reports}.
42
29
+194
-1
src/docs/contributor/contributing_code.diviner
+194
-1
src/docs/contributor/contributing_code.diviner
···
1
1
@title Contributing Code
2
2
@group detail
3
3
4
-
Effective June 1, 2021: Phabricator is no longer actively maintained, and no longer accepting contributions.
4
+
Phorge is an open-source project, and welcomes contributions from the community
5
+
at large. However, there are some guidelines we ask you to follow.
6
+
7
+
8
+
Overview
9
+
========
10
+
11
+
The most important parts of contributing code to Phorge are:
12
+
13
+
- File a task with a bug report or feature request //before// you write code.
14
+
- We do not accept GitHub pull requests.
15
+
- Some alternative approaches are available if your change isn't something
16
+
we want to bring upstream.
17
+
18
+
The rest of this article describes these points in more detail, and then
19
+
provides guidance on writing and submitting patches.
20
+
21
+
If you just want to contribute some code but don't have a specific bug or
22
+
feature in mind, see the bottom of this document for tips on finding ways to get
23
+
started.
24
+
25
+
For general information on contributing to Phorge, see
26
+
@{article:Contributor Introduction}.
27
+
28
+
29
+
Coordinate First
30
+
================
31
+
32
+
Before sending code, you should file a task describing what you'd like to write.
33
+
34
+
When you file a task, mention that you'd like to write the code to fix it. We
35
+
can help contextualize your request or bug and guide you through writing an
36
+
upstreamable patch, provided it's something that's upstreamable. If it isn't
37
+
upstreamable, we can let you know what the issues are and help find another
38
+
plan of attack.
39
+
40
+
You don't have to file first (for example, if you spot a misspelling it's
41
+
normally fine to just send a diff), but for anything even moderately complex
42
+
you're strongly encouraged to file first and coordinate with the upstream.
43
+
44
+
45
+
Rejecting Patches
46
+
=================
47
+
48
+
If you send us a patch without coordinating it with us first, it will probably
49
+
be immediately rejected, or sit in limbo for a long time and eventually be
50
+
rejected. The reasons we do this vary from patch to patch, but some of the most
51
+
common reasons are:
52
+
53
+
**Unjustifiable Costs**: We support code in the upstream forever. Support is
54
+
enormously expensive and takes up a huge amount of our time. The cost to support
55
+
a change over its lifetime is often 10x or 100x or 1000x greater than the cost
56
+
to write the first version of it. Many uncoordinated patches we receive are
57
+
"white elephants", which would cost much more to maintain than the value they
58
+
provide.
59
+
60
+
As an author, it may look like you're giving us free work and we're rejecting it
61
+
as too expensive, but this viewpoint doesn't align with the reality of a large
62
+
project which is actively supported by a small, experienced team. Writing code
63
+
is cheap; maintaining it is expensive.
64
+
65
+
By coordinating with us first, you can make sure the patch is something we
66
+
consider valuable enough to put long-term support resources behind, and that
67
+
you're building it in a way that we're comfortable taking over.
68
+
69
+
**Not a Good Fit**: Many patches aren't good fits for the upstream: they
70
+
implement features we simply don't want. Coordinating with us first helps
71
+
make sure we're on the same page and interested in a feature.
72
+
73
+
The most common type of patch along these lines is a patch which adds new
74
+
configuration options. We consider additional configuration options to have
75
+
an exceptionally high lifetime support cost and are very unlikely to accept
76
+
them. Coordinate with us first.
77
+
78
+
**Not a Priority**: If you send us a patch against something which isn't a
79
+
priority, we probably won't have time to look at it. We don't give special
80
+
treatment to low-priority issues just because there's code written: we'd still
81
+
be spending time on something lower-priority when we could be spending it on
82
+
something higher-priority instead.
83
+
84
+
If you coordinate with us first, you can make sure your patch is in an area
85
+
of the codebase that we can prioritize.
86
+
87
+
**Overly Ambitious Patches**: Sometimes we'll get huge patches from new
88
+
contributors. These can have a lot of fundamental problems and require a huge
89
+
amount of our time to review and correct. If you're interested in contributing,
90
+
you'll have more success if you start small and learn as you go.
91
+
92
+
We can help you break a large change into smaller pieces and learn how the
93
+
codebase works as you proceed through the implementation, but only if you
94
+
coordinate with us first.
95
+
96
+
**Generality**: We often receive several feature requests which ask for similar
97
+
features, and can come up with a general approach which covers all of the use
98
+
cases. If you send us a patch for //your use case only//, the approach may be
99
+
too specific. When a cleaner and more general approach is available, we usually
100
+
prefer to pursue it.
101
+
102
+
By coordinating with us first, we can make you aware of similar use cases and
103
+
opportunities to generalize an approach. These changes are often small, but can
104
+
have a big impact on how useful a piece of code is.
105
+
106
+
**Infrastructure and Sequencing**: Sometimes patches are written against a piece
107
+
of infrastructure with major planned changes. We don't want to accept these
108
+
because they'll make the infrastructure changes more difficult to implement.
109
+
110
+
Coordinate with us first to make sure a change doesn't need to wait on other
111
+
pieces of infrastructure. We can help you identify technical blockers and
112
+
possibly guide you through resolving them if you're interested.
113
+
114
+
115
+
No Prototype Changes
116
+
====================
117
+
118
+
With rare exceptions, we do not accept patches for prototype applications for
119
+
the same reasons that we don't accept feature requests or bug reports. To learn
120
+
more about prototype applications, see
121
+
@{article:User Guide: Prototype Applications}.
122
+
123
+
124
+
No Pull Requests
125
+
================
126
+
127
+
We do not accept pull requests on GitHub:
128
+
129
+
- Pull requests do not get lint and unit tests run, so issues which are
130
+
normally caught statically can slip by.
131
+
- Phorge is code review software, and developed using its own workflows.
132
+
Pull requests bypass some of these workflows (for example, they will not
133
+
trigger Herald rules to notify interested parties).
134
+
- GitHub is not the authoritative master repository and we maintain a linear
135
+
history, so merging pull requests is cumbersome on our end.
136
+
- If you're comfortable enough with Phorge to contribute to it, you
137
+
should also be comfortable using it to submit changes.
138
+
139
+
Instead of sending a pull request, use `arc diff` to create a revision on the
140
+
upstream install. Your change will go through the normal Phorge review
141
+
process.
142
+
143
+
(GitHub does not allow repositories to disable pull requests, which is why
144
+
it's technically possible to submit them.)
145
+
146
+
147
+
Alternatives
148
+
============
149
+
150
+
If you've written code but we're not accepting it into the upstream, some
151
+
alternative approaches include:
152
+
153
+
**Maintain a local fork.** This will require some ongoing effort to port your
154
+
changes forward when you update, but is often very reasonable for simple
155
+
changes.
156
+
157
+
**Develop as an application.** Many parts of Phorge's infrastructure are
158
+
modular, and modularity is increasing over time. A lot of changes can be built
159
+
as external modules or applications without forking Phorge itself. There
160
+
isn't much documentation for this right now, but you can look at
161
+
how other applications are implemented, and at other third-party code that
162
+
extends Phorge.
163
+
164
+
**Rise to prominence.** We're more willing to accept borderline changes from
165
+
community members who are active, make multiple contributions, or have a history
166
+
with the project. This is not carte blanche, but distinguishing yourself can
167
+
make us feel more comfortable about supporting a change which is slightly
168
+
outside of our comfort zone.
169
+
170
+
171
+
Writing and Submitting Patches
172
+
==================
173
+
174
+
To actually submit a patch, run `arc diff` in `phorge/` or `arcanist/`.
175
+
When executed in these directories, `arc` should automatically talk to the
176
+
upstream install. You can add #blessed_reviewers as a reviewer.
177
+
178
+
You should read the relevant coding convention documents before you submit a
179
+
change. If you're a new contributor, you don't need to worry about this too
180
+
much. Just try to make your code look similar to the code around it, and we
181
+
can help you through the details during review.
182
+
183
+
- @{article:General Coding Standards} (for all languages)
184
+
- @{article:PHP Coding Standards} (for PHP)
185
+
- @{article:Javascript Coding Standards} (for Javascript)
186
+
187
+
In general, if you're coordinating with us first, we can usually provide
188
+
guidance on how to implement things. The other articles in this section also
189
+
provide information on how to work in the Phorge codebase.
190
+
191
+
192
+
Next Steps
193
+
==========
194
+
195
+
Continue by:
196
+
197
+
- returning to the @{article:Contributor Introduction}.
+6
-6
src/docs/contributor/css_coding_standards.diviner
+6
-6
src/docs/contributor/css_coding_standards.diviner
···
1
1
@title CSS Coding Standards
2
2
@group standards
3
3
4
-
This document describes CSS features and coding standards for Phabricator.
4
+
This document describes CSS features and coding standards for Phorge.
5
5
6
6
= Overview =
7
7
8
8
This document describes technical and style guidelines for writing CSS in
9
-
Phabricator.
9
+
Phorge.
10
10
11
-
Phabricator has a limited CSS preprocessor. This document describes the features
11
+
Phorge has a limited CSS preprocessor. This document describes the features
12
12
it makes available.
13
13
14
14
= Z-Indexes =
···
19
19
20
20
= Color Variables =
21
21
22
-
Phabricator's preprocessor provides some standard color variables. You can
22
+
Phorge's preprocessor provides some standard color variables. You can
23
23
reference these with `{$color}`. For example:
24
24
25
25
lang=css
···
60
60
61
61
= Device Rules =
62
62
63
-
Phabricator's environment defines several device classes which can be used to
63
+
Phorge's environment defines several device classes which can be used to
64
64
adjust behavior responsively. In particular:
65
65
66
66
lang=css
···
86
86
87
87
= Image Inlining =
88
88
89
-
Phabricator's CSS preprocessor automatically inlines images which are less than
89
+
Phorge's CSS preprocessor automatically inlines images which are less than
90
90
32KB using `data:` URIs. This is primarily useful for gradients or textures
91
91
which are small and difficult to sprite.
+18
-16
src/docs/contributor/database.diviner
+18
-16
src/docs/contributor/database.diviner
···
7
7
Database System
8
8
===============
9
9
10
-
Phabricator uses MySQL or another MySQL-compatible database (like MariaDB
10
+
Phorge uses MySQL or another MySQL-compatible database (like MariaDB
11
11
or Amazon RDS).
12
12
13
-
Phabricator uses the InnoDB table engine. The only exception is the
13
+
Phorge uses the InnoDB table engine. The only exception is the
14
14
`search_documentfield` table which uses MyISAM because MySQL doesn't support
15
15
fulltext search in InnoDB (recent versions do, but we haven't added support
16
16
yet).
···
21
21
PHP Drivers
22
22
===========
23
23
24
-
Phabricator supports [[ http://www.php.net/book.mysql | MySQL ]] and
24
+
Phorge supports [[ http://www.php.net/book.mysql | MySQL ]] and
25
25
[[ http://www.php.net/book.mysqli | MySQLi ]] PHP extensions.
26
26
27
27
Databases
28
28
=========
29
29
30
-
Each Phabricator application has its own database. The names are prefixed by
31
-
`phabricator_` (this is configurable).
30
+
Each Phorge application has its own database. The names are prefixed by
31
+
`phorge_` (this is configurable).
32
32
33
-
Phabricator uses a separate database for each application. To understand why,
34
-
see @{article:Why does Phabricator need so many databases?}.
33
+
Phorge uses a separate database for each application. To understand why,
34
+
see @{article:Why does Phorge need so many databases?}.
35
35
36
36
Connections
37
37
===========
38
38
39
-
Phabricator specifies if it will use any opened connection just for reading or
39
+
Phorge specifies if it will use any opened connection just for reading or
40
40
also for writing. This allows opening write connections to a primary and read
41
41
connections to a replica in primary/replica setups (which are not actually
42
42
supported yet).
···
45
45
======
46
46
47
47
Most table names are prefixed by their application names. For example,
48
-
Differential revisions are stored in database `phabricator_differential` and
48
+
Differential revisions are stored in database `phorge_differential` and
49
49
table `differential_revision`. This generally makes queries easier to recognize
50
50
and understand.
51
51
···
57
57
Column Names
58
58
============
59
59
60
-
Phabricator uses `camelCase` names for columns. The main advantage is that they
60
+
Phorge uses `camelCase` names for columns. The main advantage is that they
61
61
directly map to properties in PHP classes.
62
62
63
63
Don't use MySQL reserved words (such as `order`) for column names.
···
65
65
Data Types
66
66
==========
67
67
68
-
Phabricator defines a set of abstract data types (like `uint32`, `epoch`, and
68
+
Phorge defines a set of abstract data types (like `uint32`, `epoch`, and
69
69
`phid`) which map to MySQL column types. The mapping depends on the MySQL
70
70
version.
71
71
72
-
Phabricator uses `utf8mb4` character sets where available (MySQL 5.5 or newer),
72
+
Phorge uses `utf8mb4` character sets where available (MySQL 5.5 or newer),
73
73
and `binary` character sets in most other cases. The primary motivation is to
74
74
allow 4-byte unicode characters to be stored (the `utf8` character set, which
75
75
is more widely available, does not support them). On newer MySQL, we use
76
76
`utf8mb4` to take advantage of improved collation rules.
77
77
78
-
Phabricator stores dates with an `epoch` abstract data type, which maps to
78
+
Phorge stores dates with an `epoch` abstract data type, which maps to
79
79
`int unsigned`. Although this makes dates less readable when browsing the
80
80
database, it makes date and time manipulation more consistent and
81
81
straightforward in the application.
···
134
134
PHIDs
135
135
=====
136
136
137
-
Each globally referencable object in Phabricator has an associated PHID
138
-
("Phabricator ID") which serves as a global identifier, similar to a GUID.
137
+
Each globally referencable object in Phorge has an associated PHID
138
+
("Phorge ID") which serves as a global identifier, similar to a GUID.
139
139
We use PHIDs for referencing data in different databases.
140
140
141
141
We use both auto-incrementing IDs and global PHIDs because each is useful in
···
149
149
are permitted to subscribe to different types of objects (revisions, tasks,
150
150
etc). Without PHIDs, we would need to add a "type" column to avoid ID collision;
151
151
using PHIDs makes implementing features like this simpler.
152
+
153
+
For more information, see @{article:Handles Technical Documentation}
152
154
153
155
Transactions
154
156
============
···
169
171
Schema Denormalization
170
172
======================
171
173
172
-
Phabricator uses schema denormalization sparingly. Avoid denormalization unless
174
+
Phorge uses schema denormalization sparingly. Avoid denormalization unless
173
175
there is a compelling reason (usually, performance) to denormalize.
174
176
175
177
Schema Changes and Migrations
+21
-21
src/docs/contributor/describing_problems.diviner
+21
-21
src/docs/contributor/describing_problems.diviner
···
37
37
38
38
Here are some examples of good ways to start a problem description:
39
39
40
-
> My company does contracting work for government agencies. Because of the
41
-
> nature of our customers, deadlines are critical and it's very important
42
-
> for us to keep track of where we are on a timeline. We're using Maniphest
43
-
> to track tasks...
40
+
(NOTE) My company does contracting work for government agencies. Because of the
41
+
nature of our customers, deadlines are critical and it's very important
42
+
for us to keep track of where we are on a timeline. We're using Maniphest
43
+
to track tasks...
44
44
45
-
> I have poor eyesight, and use a screenreader to help me use software like
46
-
> Phabricator in my job as a developer. I'm having difficulty...
45
+
(NOTE) I have poor eyesight, and use a screenreader to help me use software like
46
+
Phorge in my job as a developer. I'm having difficulty...
47
47
48
-
> We work on a large server program which has very long compile times.
49
-
> Switching branches is a huge pain (you have to rebuild the binary after
50
-
> every switch, which takes about 8 minutes), but we've recently begun using
51
-
> `git worktree` to help, which has made life a lot better. However, ...
48
+
(NOTE) We work on a large server program which has very long compile times.
49
+
Switching branches is a huge pain (you have to rebuild the binary after
50
+
every switch, which takes about 8 minutes), but we've recently begun using
51
+
`git worktree` to help, which has made life a lot better. However, ...
52
52
53
-
> I triage manual test failures from our offshore QA team. Here's how our
54
-
> workflow works...
53
+
(NOTE) I triage manual test failures from our offshore QA team. Here's how our
54
+
workflow works...
55
55
56
56
All of these descriptions are helpful: the provide context about what goals
57
57
you're trying to accomplish and why.
···
59
59
Here are some examples of ways to start a problem description that probably
60
60
are not very good:
61
61
62
-
> {icon times color=red} Add custom keyboard shortcuts.
62
+
(IMPORTANT) Add custom keyboard shortcuts.
63
63
64
-
> {icon times color=red} I have a problem: there is no way to download
65
-
> .tar archives of repositories.
64
+
(IMPORTANT) I have a problem: there is no way to download
65
+
.tar archives of repositories.
66
66
67
-
> {icon times color=red} I want an RSS feed of my tokens. My root problem is
68
-
> that I do not have an RSS feed of my tokens.
67
+
(IMPORTANT) I want an RSS feed of my tokens. My root problem is
68
+
that I do not have an RSS feed of my tokens.
69
69
70
-
> {icon times color=red} There is no way to see other users' email addresses.
71
-
> That is a problem.
70
+
(IMPORTANT) There is no way to see other users' email addresses.
71
+
That is a problem.
72
72
73
-
> {icon times color=red} I've used some other software that has a cool
74
-
> feature. Phabricator should have that feature too.
73
+
(IMPORTANT) I've used some other software that has a cool
74
+
feature. Phorge should have that feature too.
75
75
76
76
These problem descriptions are not helpful. They do not describe goals or
77
77
provide context.
+9
-9
src/docs/contributor/developer_setup.diviner
+9
-9
src/docs/contributor/developer_setup.diviner
···
1
1
@title Developer Setup
2
2
@group developer
3
3
4
-
How to configure a Phabricator development environment.
4
+
How to configure a Phorge development environment.
5
5
6
6
Overview
7
7
========
8
8
9
9
There are some options and workflows that may be useful if you are developing
10
-
or debugging Phabricator.
10
+
or debugging Phorge.
11
11
12
12
13
13
Configuration
14
14
=============
15
15
16
-
To adjust Phabricator for development:
16
+
To adjust Phorge for development:
17
17
18
18
- Enable `phabricator.developer-mode` to enable some options and show
19
19
more debugging information.
···
48
48
the class map:
49
49
50
50
```
51
-
phabricator/ $ arc liberate
51
+
phorge/ $ arc liberate
52
52
```
53
53
54
-
Until you do this, Phabricator won't recognize your new, moved, or renamed
54
+
Until you do this, Phorge won't recognize your new, moved, or renamed
55
55
classes. You do not need to run this after modifying an existing class.
56
56
57
57
After any modifications to static resources (CSS / JS) but before sending
58
58
changes for review or pushing them to the remote, run `bin/celerity map`:
59
59
60
60
```
61
-
phabricator/ $ ./bin/celerity map
61
+
phorge/ $ ./bin/celerity map
62
62
```
63
63
64
64
This rebuilds the static resource map.
···
91
91
configuration that look exactly like the primary entry (or expanding the
92
92
primary entry to match more domains).
93
93
94
-
Phabricator routes all requests based on host headers, so alternate domains
94
+
Phorge routes all requests based on host headers, so alternate domains
95
95
do not normally need any kind of special configuration.
96
96
97
97
You may also need to add `/etc/hosts` entries for the domains themselves.
···
103
103
You can create test objects with the "Lipsum" utility:
104
104
105
105
```
106
-
phabricator/ $ ./bin/lipsum help generate
107
-
phabricator/ $ ./bin/lipsum generate ...
106
+
phorge/ $ ./bin/lipsum help generate
107
+
phorge/ $ ./bin/lipsum generate ...
108
108
```
109
109
110
110
Test data can make your local install feel a little more realistic. With
+208
-1
src/docs/contributor/feature_requests.diviner
+208
-1
src/docs/contributor/feature_requests.diviner
···
1
1
@title Contributing Feature Requests
2
2
@group detail
3
3
4
-
Effective June 1, 2021: Phabricator is no longer actively maintained, and there is no way to file a feature request.
4
+
Describes how to file an effective Phorge feature request.
5
+
6
+
Overview
7
+
========
8
+
9
+
Phorge is an open-source project, and welcomes feature requests from the community
10
+
at large. However, there are some guidelines we ask you to follow.
11
+
12
+
Overview
13
+
========
14
+
15
+
This article describes how to file an effective feature request.
16
+
17
+
The most important things to do are:
18
+
19
+
- understand the upstream;
20
+
- make sure your feature makes sense in the project;
21
+
- align your expectations around timelines and priorities;
22
+
- describe your problem, not your solution.
23
+
24
+
The rest of this article walks through these points in detail.
25
+
26
+
If you have a bug report (not a feature request), see
27
+
@{article:Contributing Bug Reports} for a more tailored guide.
28
+
29
+
For general information on contributing to Phorge, see
30
+
@{article:Contributor Introduction}.
31
+
32
+
33
+
Understanding the Upstream
34
+
==========================
35
+
36
+
Before filing a feature request, it may be useful to understand how the
37
+
upstream operates.
38
+
39
+
Phorge has a designated core team who controls the project and roadmap.
40
+
We have a cohesive vision for the project in the long term, and a general
41
+
roadmap that extends for years into the future. While the specifics of how
42
+
we get there are flexible, many major milestones are well-established.
43
+
44
+
Although we set project direction, the community is also a critical part of
45
+
Phorge. We aren't all-knowing, and we rely on feedback to help us identify
46
+
issues, guide product direction, prioritize changes, and suggest features.
47
+
48
+
Feature requests are an important part of this, but we ultimately build only
49
+
features which make sense as part of the long term plan.
50
+
51
+
Since it's hard to absorb a detailed understanding of that vision, //describing
52
+
a problem// is often more effective than //requesting a feature//. We have the
53
+
context to develop solutions which fit into our plans, address similar use
54
+
cases, make sense with the available infrastructure, and work within the
55
+
boundaries of our product vision. For more details on this, see below.
56
+
57
+
58
+
Target Audiences
59
+
================
60
+
61
+
Some feature requests support very unusual use cases. Although we are broadly
62
+
inclusive of many different kinds of users and use cases, we are not trying
63
+
to make the software all things to all users. Use cases which are far afield
64
+
from the things the majority of users do with Phorge often face substantial
65
+
barriers.
66
+
67
+
Phorge is primarily targeted at software projects and organizations with
68
+
a heavy software focus. We are most likely to design, build, and prioritize
69
+
features which serve these organizations and projects.
70
+
71
+
Phorge is primarily targeted at software professionals and other
72
+
professionals with adjacent responsibilities (like project management and
73
+
operations). Particularly, we assume users are proficient computer users and
74
+
familiar with software development concepts. We are most likely to design, build
75
+
and prioritize features which serve these users.
76
+
77
+
Phorge is primarily targeted at professionals working in teams on full-time
78
+
projects. Particularly, we assume most users will use the software regularly and
79
+
are often willing to spend a little more time up front to get a more efficient
80
+
workflow in the long run. We are most likely to design, build and prioritize
81
+
features which serve these use cases.
82
+
83
+
Phorge is not limited to these kinds of organizations, users and use cases,
84
+
but features which are aimed at a different group of users (like students,
85
+
casual projects, or inexperienced computer users) may be harder to get
86
+
upstreamed. Features aimed at very different groups of users (like wedding
87
+
planners, book clubs, or dogs) will be much harder to get upstreamed.
88
+
89
+
In many cases, a feature makes something better for all users. For example,
90
+
suppose we fixed an issue where colorblind users had difficulty doing something.
91
+
Dogs would benefit the most, but colorblind human users would also benefit, and
92
+
no one would be worse off. If the benefit for core users is very small these
93
+
kinds of features may be hard to prioritize, but there is no exceptional barrier
94
+
to getting them upstreamed.
95
+
96
+
In other cases, a feature makes something better for some users and worse for
97
+
other users. These kinds of features face a high barrier if they make the
98
+
software better at planning weddings and worse at reviewing code.
99
+
100
+
101
+
Setting Expectations
102
+
====================
103
+
104
+
We have a lot of users and a small team. Even if your feature is something we're
105
+
interested in and a good fit for where we want the product to go, it may take
106
+
us a long time to get around to building it.
107
+
108
+
Our long-term roadmap (which we call our
109
+
[[ https://we.phorge.it/w/starmap/ | Starmap ]]) has many years worth
110
+
of work. Your feature request is competing against thousands of other requests
111
+
for priority.
112
+
113
+
In general, we try to prioritize work that will have the greatest impact on the
114
+
most users. Many feature requests are perfectly reasonable requests, but have
115
+
very little impact, impact only a few users, and/or are complex to develop and
116
+
support relative to their impact. It can take us a long time to get to these.
117
+
118
+
Even if your feature request is simple and has substantial impact for a large
119
+
number of users, the size of the request queue means that it is mathematically
120
+
unlikely to be near the top.
121
+
122
+
As a whole, this means that the overwhelming majority of feature requests will
123
+
sit in queue for a long time without any updates, and that we won't be able to
124
+
give you any updates or predictions about timelines. One day, out of nowhere,
125
+
your feature will materialize. That day may be a decade from now. You should
126
+
have realistic expectations about this when filing a feature request.
127
+
128
+
129
+
Describe Problems
130
+
=================
131
+
132
+
When you file a feature request, we need you to describe the problem you're
133
+
facing first, not just your desired solution. Describing the problem you are
134
+
facing is the **most important part** of a feature request.
135
+
136
+
Often, your problem may have a lot in common with other similar problems. If we
137
+
understand your use case we can compare it to other use cases and sometimes find
138
+
a more powerful or more general solution which solves several problems at once.
139
+
140
+
At other times, we'll have a planned solution to the problem that might be
141
+
different from your desired solution but accomplish the same goal. Understanding
142
+
the root issue can let us merge and contextualize things.
143
+
144
+
Sometimes there's already a way to solve your problem that might just not be
145
+
obvious.
146
+
147
+
Finally, your proposed solution may not be compatible with the direction we
148
+
want to take the product, but we may be able to come up with another solution
149
+
which has approximately the same effect and does fit into the product direction.
150
+
151
+
If you only describe the solution and not the problem, we can't generalize,
152
+
contextualize, merge, reframe, or offer alternative solutions or workarounds.
153
+
154
+
You must describe the problem you are facing when filing a feature request. We
155
+
will not accept feature requests which do not contextualize the request by
156
+
describing the root problem.
157
+
158
+
If you aren't sure exactly what we're after when we ask you to describe a root
159
+
problem, you can find examples and more discussion in
160
+
@{article:Describing Root Problems}.
161
+
162
+
163
+
Hypotheticals
164
+
=============
165
+
166
+
We sometimes receive hypothetical feature requests about anticipated problems
167
+
or concerns which haven't actually occurred yet. We usually can't do much about
168
+
these until the problems actually occur, since the context required to
169
+
understand and properly fix the root issue won't exist.
170
+
171
+
One situation where this happens is when installs are thinking about adopting
172
+
Phorge and trying to guess what problems users might encounter during the
173
+
transition. More generally, this includes any request like "if users do **X**,
174
+
they might find **Y** confusing", where no actual users have encountered
175
+
confusion yet.
176
+
177
+
These requests are necessarily missing important context, maybe including the
178
+
answers to questions like these:
179
+
180
+
- Why did users do **X**?
181
+
- What were they trying to do?
182
+
- What did they expect to happen?
183
+
- How often do users do this?
184
+
185
+
The answers to these questions are important in establishing that the issue is
186
+
really a problem, figuring out the best solution for it, and prioritizing the
187
+
issue relative to other issues.
188
+
189
+
Without knowing this information, we can't be confident that we've found a good
190
+
solution to the problem, can't know if we've actually fixed the problem, and
191
+
can't even know if the issue was really a problem in the first place (some
192
+
hypothetical requests describe problems which no users ever encounter).
193
+
194
+
We usually can't move forward without this information. In particular, we don't
195
+
want to spend time solving hypothetical problems which no real users will ever
196
+
encounter: the value of those changes is zero (or negative, by making the
197
+
product more complex without providing a benefit), but they consume development
198
+
time which could be better spent building much more valuable features.
199
+
200
+
Generally, you should wait until a problem actually occurs before filing a
201
+
request about it.
202
+
203
+
204
+
Next Steps
205
+
==========
206
+
207
+
Continue by:
208
+
209
+
- learning about @{article: Contributing Bug Reports}; or
210
+
- reading general support information in @{article:Support Resources}; or
211
+
- returning to the @{article:Contributor Introduction}.
+2
-2
src/docs/contributor/general_coding_standards.diviner
+2
-2
src/docs/contributor/general_coding_standards.diviner
···
1
1
@title General Coding Standards
2
2
@group standards
3
3
4
-
This document is a general coding standard for contributing to Phabricator,
4
+
This document is a general coding standard for contributing to Phorge,
5
5
Arcanist, and Diviner.
6
6
7
7
= Overview =
···
60
60
determine if code is fast or slow by measuring it.
61
61
- Reject performance discussions that aren't rooted in concrete data.
62
62
63
-
In Phabricator, you can usually use the builtin XHProf profiling to quickly
63
+
In Phorge, you can usually use the builtin XHProf profiling to quickly
64
64
gather concrete performance data.
65
65
66
66
+7
-7
src/docs/contributor/internationalization.diviner
+7
-7
src/docs/contributor/internationalization.diviner
···
1
1
@title Internationalization
2
2
@group developer
3
3
4
-
Describes Phabricator translation and localization.
4
+
Describes Phorge translation and localization.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator partially supports internationalization, but many of the tools
9
+
Phorge partially supports internationalization, but many of the tools
10
10
are missing or in a prototype state.
11
11
12
12
This document describes what tools exist today, how to add new translations,
···
23
23
locale.
24
24
25
25
For instructions on adding new classes, see
26
-
@{article@phabcontrib:Adding New Classes}.
26
+
@{article@contrib:Adding New Classes}.
27
27
28
28
29
29
Adding Translations to Locale
···
38
38
locales themselves.
39
39
40
40
For instructions on adding new classes, see
41
-
@{article@phabcontrib:Adding New Classes}.
41
+
@{article@contrib:Adding New Classes}.
42
42
43
43
44
44
Writing Translatable Code
···
58
58
```
59
59
60
60
This allows the code to return the correct Spanish or German or Russian
61
-
version of the text, if the viewer is using Phabricator in one of those
61
+
version of the text, if the viewer is using Phorge in one of those
62
62
languages and a translation is available.
63
63
64
64
Using `pht()` properly so that strings are translatable can be tricky. Briefly,
···
275
275
276
276
If you now load the web UI, you'll see "hour(s)" literally in the UI. To fix
277
277
this so the translation sounds better in English, provide translations for this
278
-
string in the @{class@phabricator:PhabricatorUSEnglishTranslation} file:
278
+
string in the @{class:PhabricatorUSEnglishTranslation} file:
279
279
280
280
```lang=php
281
281
'This will take %s hour(s).' => array(
···
378
378
Continue by:
379
379
380
380
- adding a new locale or translation file with
381
-
@{article@phabcontrib:Adding New Classes}.
381
+
@{article@contrib:Adding New Classes}.
+2
-2
src/docs/contributor/javascript_coding_standards.diviner
+2
-2
src/docs/contributor/javascript_coding_standards.diviner
···
1
1
@title Javascript Coding Standards
2
2
@group standards
3
3
4
-
This document describes Javascript coding standards for Phabricator and Javelin.
4
+
This document describes Javascript coding standards for Phorge and Javelin.
5
5
6
6
= Overview =
7
7
8
8
This document outlines technical and style guidelines which are followed in
9
-
Phabricator and Javelin. Contributors should also follow these guidelines. Many
9
+
Phorge and Javelin. Contributors should also follow these guidelines. Many
10
10
of these guidelines are automatically enforced by lint.
11
11
12
12
These guidelines are essentially identical to the Facebook guidelines, since I
+1
-1
src/docs/contributor/n_plus_one.diviner
+1
-1
src/docs/contributor/n_plus_one.diviner
···
39
39
is on a different machine which is, say, 1-2ms away on the network. In this
40
40
case, issuing 100 queries serially has a minimum cost of 100-200ms, even if they
41
41
can be satisfied instantly by MySQL. This is far higher than the entire
42
-
server-side generation cost for most Phabricator pages should be.
42
+
server-side generation cost for most Phorge pages should be.
43
43
44
44
= Batching Queries =
45
45
+21
-21
src/docs/contributor/phabricator_code_layout.diviner
src/docs/contributor/phorge_code_layout.diviner
+21
-21
src/docs/contributor/phabricator_code_layout.diviner
src/docs/contributor/phorge_code_layout.diviner
···
1
-
@title Phabricator Code Layout
1
+
@title Phorge Code Layout
2
2
@group developer
3
3
4
-
Guide to Phabricator code layout, including how URI mapping works through
4
+
Guide to Phorge code layout, including how URI mapping works through
5
5
application class and subdirectory organization best practices.
6
6
7
7
= URI Mapping =
8
8
9
-
When a user visits a Phabricator URI, the Phabricator infrastructure parses
10
-
that URI with a regular expression to determine what controller class to load.
9
+
When a user visits a Phorge URI, the Phorge infrastructure parses that URI with
10
+
a regular expression to determine what controller class to load.
11
11
12
-
The Phabricator infrastructure knows where a given controller class lives on
12
+
The Phorge infrastructure knows where a given controller class lives on
13
13
disk from a cache file the Arcanist phutil mapper generates. This mapping
14
14
should be updated whenever new classes or files are added:
15
15
16
-
arc liberate /path/to/phabricator/src
16
+
arc liberate /path/to/phorge/src
17
17
18
18
Finally, a given controller class will map to an application which will have
19
19
most of its code in standardized subdirectories and classes.
···
22
22
23
23
Suppose you were working on the application `Derp`.
24
24
25
-
phabricator/src/applications/derp/
25
+
phorge/src/applications/derp/
26
26
27
27
If `Derp` were as simple as possible, it would have one subdirectory:
28
28
29
-
phabricator/src/applications/derp/controller/
29
+
phorge/src/applications/derp/controller/
30
30
31
31
containing the file `DerpController.php` with the class
32
32
···
37
37
If `Derp` were (relatively) complex, one could reasonably expect to see
38
38
the following directory layout:
39
39
40
-
phabricator/src/applications/derp/conduit/
41
-
phabricator/src/applications/derp/constants/
42
-
phabricator/src/applications/derp/controller/
43
-
phabricator/src/applications/derp/editor/
44
-
phabricator/src/applications/derp/exception/
45
-
phabricator/src/applications/derp/query/
46
-
phabricator/src/applications/derp/replyhandler/
47
-
phabricator/src/applications/derp/storage/
48
-
phabricator/src/applications/derp/view/
40
+
phorge/src/applications/derp/conduit/
41
+
phorge/src/applications/derp/constants/
42
+
phorge/src/applications/derp/controller/
43
+
phorge/src/applications/derp/editor/
44
+
phorge/src/applications/derp/exception/
45
+
phorge/src/applications/derp/query/
46
+
phorge/src/applications/derp/replyhandler/
47
+
phorge/src/applications/derp/storage/
48
+
phorge/src/applications/derp/view/
49
49
50
50
(The following two folders are also likely to be included for JavaScript and
51
51
CSS respectively. However, static resources are largely outside the scope of
52
52
this document. See @{article:Adding New CSS and JS}.)
53
53
54
-
phabricator/webroot/rsrc/js/application/derp/
55
-
phabricator/webroot/rsrc/css/application/derp/
54
+
phorge/webroot/rsrc/js/application/derp/
55
+
phorge/webroot/rsrc/css/application/derp/
56
56
57
-
These directories under `phabricator/src/applications/derp/` represent
58
-
the basic set of class types from which most Phabricator applications are
57
+
These directories under `phorge/src/applications/derp/` represent
58
+
the basic set of class types from which most Phorge applications are
59
59
assembled. Each would contain a class file. For `Derp`, these classes could be
60
60
something like:
61
61
+2
-2
src/docs/contributor/php_coding_standards.diviner
+2
-2
src/docs/contributor/php_coding_standards.diviner
···
1
1
@title PHP Coding Standards
2
2
@group standards
3
3
4
-
This document describes PHP coding standards for Phabricator and related
4
+
This document describes PHP coding standards for Phorge and related
5
5
projects (like Arcanist).
6
6
7
7
= Overview =
8
8
9
9
This document outlines technical and style guidelines which are followed in
10
-
Phabricator and Arcanist. Contributors should also follow these guidelines.
10
+
Phorge and Arcanist. Contributors should also follow these guidelines.
11
11
Many of these guidelines are automatically enforced by lint.
12
12
13
13
These guidelines are essentially identical to the Facebook guidelines, since I
+4
-4
src/docs/contributor/rendering_html.diviner
+4
-4
src/docs/contributor/rendering_html.diviner
···
1
1
@title Rendering HTML
2
2
@group developer
3
3
4
-
Rendering HTML in the Phabricator environment.
4
+
Rendering HTML in the Phorge environment.
5
5
6
6
= Overview =
7
7
8
-
Phabricator attempts to prevent XSS by treating strings as default-unsafe when
8
+
Phorge attempts to prevent XSS by treating strings as default-unsafe when
9
9
rendering. This means that if you try to build HTML through string
10
10
concatenation, it won't work: the string will be escaped by the rendering
11
11
pipeline, and the browser will treat it as plain text, not HTML.
···
51
51
array(),
52
52
$content));
53
53
54
-
In Phabricator, the @{function:javelin_tag} function is similar to
54
+
In Phorge, the @{function:javelin_tag} function is similar to
55
55
@{function@arcanist:phutil_tag}, but provides special handling for the
56
56
`sigil` and `meta` attributes.
57
57
···
117
117
118
118
= AphrontView Classes =
119
119
120
-
Subclasses of @{class:AphrontView} in Phabricator should return a
120
+
Subclasses of @{class:AphrontView} in Phorge should return a
121
121
@{class@arcanist:PhutilSafeHTML} object. The easiest way to do this is to
122
122
return `phutil_tag()` or `javelin_tag()`:
123
123
+5
-39
src/docs/contributor/reproduction_steps.diviner
+5
-39
src/docs/contributor/reproduction_steps.diviner
···
6
6
Overview
7
7
========
8
8
9
-
When you submit a bug report about Phabricator, you **MUST** include
9
+
When you submit a bug report about Phorge, you **MUST** include
10
10
reproduction steps. We can not help you with bugs we can not reproduce, and
11
11
will not accept reports which omit reproduction steps or have incomplete or
12
12
insufficient instructions.
···
15
15
Briefly:
16
16
17
17
- Reproduction steps must allow us to reproduce the problem locally on a
18
-
clean, up-to-date install of Phabricator.
18
+
clean, up-to-date install of Phorge.
19
19
- Reproduction should be as simple as possible.
20
20
21
21
Good reproduction steps can take time to write out clearly, simplify, and
···
70
70
=====================
71
71
72
72
When you file a bug report, the first thing we do to fix it is to try to
73
-
reproduce the problem locally on an up-to-date install of Phabricator. We will
73
+
reproduce the problem locally on an up-to-date install of Phorge. We will
74
74
do this by following the steps you provide. If we can recreate the issue
75
75
locally, we can almost always resolve the problem (often very promptly).
76
76
···
80
80
follow these steps, or can't reproduce issues by following them.
81
81
82
82
Reproduction steps must be complete and self-contained, and must allow
83
-
**anyone** to reproduce the issue on a new, empty install of Phabricator. If
83
+
**anyone** to reproduce the issue on a new, empty install of Phorge. If
84
84
the bug you're seeing depends on data or configuration which would not be
85
85
present on a new install, you need to include that information in your steps.
86
86
···
101
101
102
102
Now, to verify that your steps provide a complete, self-contained way to
103
103
reproduce the issue, follow them yourself on a new, empty, up-to-date instance
104
-
of Phabricator.
105
-
106
-
If you can't easily start an empty instance locally, you can launch an empty
107
-
instance on Phacility in about 60 seconds (see the "Resources" section for
108
-
details).
104
+
of Phorge.
109
105
110
106
If you can follow your steps and reproduce the issue on a clean instance,
111
107
we'll probably be able to follow them and reproduce the issue ourselves.
···
128
124
"Simplifying Steps" below.
129
125
130
126
131
-
Resources
132
-
=========
133
-
134
-
We provide some resources which can make it easier to start building steps, or
135
-
to simplify steps.
136
-
137
-
**Phacility Test Instances**: You can launch a new, up-to-date instance of
138
-
Phabricator on Phacility in about a minute at <https://admin.phacility.com>.
139
-
These instances run `stable`.
140
-
141
-
You can use these instances to make sure that issues haven't already been
142
-
fixed, that they reproduce on a clean install, or that your steps are really
143
-
complete, and that the root cause isn't custom code or local extensions. Using
144
-
a test instance will avoid disrupting other users on your install.
145
-
146
-
**Test Repositories**: There are several test repositories on
147
-
`secure.phabricator.com` which you can push commits to if you need to build
148
-
an example to demonstrate a problem.
149
-
150
-
For example, if you're seeing an issue with a certain filename but the commit
151
-
where the problem occurs is in a proprietary internal repository, push a commit
152
-
that affects a file with a similar name to a test repository, then reproduce
153
-
against the test data. This will allow you to generate steps which anyone can
154
-
follow.
155
-
156
-
157
127
Simplifying Steps
158
128
=================
159
129
···
238
208
to a minimal reproduction case, we can't accept it as a bug report. These
239
209
issues are tremendously time consuming for us to pursue and rarely benefit
240
210
more than one install.
241
-
242
-
If the issue is important but falls outside the scope of permissible bug
243
-
reports, we're happy to provide more tailored support at consulting rates. See
244
-
[[ https://secure.phabricator.com/w/consulting/ | Consulting ]] for details.
245
211
246
212
247
213
Next Steps
+2
-2
src/docs/contributor/running_builtin_php_webserver.diviner
+2
-2
src/docs/contributor/running_builtin_php_webserver.diviner
···
3
3
4
4
As of version 5.4.0, the PHP command line interface provides a built-in web
5
5
server. This web server is designed for developmental purposes only, and should
6
-
not be used in production. Phabricator can be executed under it with the
6
+
not be used in production. Phorge can be executed under it with the
7
7
command:
8
8
9
-
$ php -S localhost:8000 -t path/to/phabricator/webroot/ path/to/phabricator/webroot/index.php
9
+
$ php -S localhost:8000 -t path/to/phorge/webroot/ path/to/phorge/webroot/index.php
+7
-7
src/docs/contributor/unit_tests.diviner
+7
-7
src/docs/contributor/unit_tests.diviner
···
1
1
@title Writing Unit Tests
2
2
@group developer
3
3
4
-
Simple guide to Arcanist and Phabricator unit tests.
4
+
Simple guide to Arcanist and Phorge unit tests.
5
5
6
6
= Overview =
7
7
8
-
Arcanist and Phabricator provide and use a simple unit test framework. This
8
+
Arcanist and Phorge provide and use a simple unit test framework. This
9
9
document is aimed at project contributors and describes how to use it to add
10
10
and run tests in these projects or other libphutil libraries.
11
11
···
16
16
17
17
= Adding Tests =
18
18
19
-
To add new tests to a Arcanist or Phabricator module:
19
+
To add new tests to a Arcanist or Phorge module:
20
20
21
21
- Create a `__tests__/` directory in the module if it doesn't exist yet.
22
22
- Add classes to the `__tests__/` directory which extend from
23
-
@{class:PhabricatorTestCase} (in Phabricator) or
23
+
@{class:PhabricatorTestCase} (in Phorge) or
24
24
@{class@arcanist:PhutilTestCase} (elsewhere).
25
25
- Run `arc liberate` on the library root so your classes are loadable.
26
26
···
38
38
Here's a simple example test:
39
39
40
40
lang=php
41
-
class PhabricatorTrivialTestCase extends PhabricatorTestCase {
41
+
class PhorgeTrivialTestCase extends PhabricatorTestCase {
42
42
43
43
private $two;
44
44
···
56
56
57
57
You can see this class at @{class:PhabricatorTrivialTestCase} and run it with:
58
58
59
-
phabricator/ $ arc unit src/infrastructure/testing/testcase/
59
+
phorge/ $ arc unit src/infrastructure/testing/testcase/
60
60
PASS <1ms* testAllIsRightWithTheWorld
61
61
62
62
For more information on writing tests, see
···
64
64
65
65
= Database Isolation =
66
66
67
-
By default, Phabricator isolates unit tests from the database. It makes a crude
67
+
By default, Phorge isolates unit tests from the database. It makes a crude
68
68
effort to simulate some side effects (principally, ID assignment on insert), but
69
69
any queries which read data will fail to select any rows and throw an exception
70
70
about isolation. In general, isolation is good, but this can make certain types
+1
-2
src/docs/contributor/using_edges.diviner
+1
-2
src/docs/contributor/using_edges.diviner
···
6
6
= Overview =
7
7
8
8
Edges are a generic way of storing a relationship between two objects (like a
9
-
Task and its attached files). If you are familiar with the Facebook associations
10
-
framework, Phabricator Edges are substantially similar.
9
+
Task and its attached files).
11
10
12
11
An edge is defined by a source PHID (the edge origin), a destination PHID
13
12
(the edge destination) and an edge type (which describes the relationship,
+9
-9
src/docs/contributor/using_oauthserver.diviner
+9
-9
src/docs/contributor/using_oauthserver.diviner
···
1
-
@title Using the Phabricator OAuth Server
1
+
@title Using the Phorge OAuth Server
2
2
@group developer
3
3
4
-
How to use the Phabricator OAuth Server.
4
+
How to use the Phorge OAuth Server.
5
5
6
6
= Overview =
7
7
8
-
Phabricator includes an OAuth Server which supports the
8
+
Phorge includes an OAuth Server which supports the
9
9
`Authorization Code Grant` flow as described in the OAuth 2.0
10
10
specification:
11
11
12
12
http://tools.ietf.org/html/draft-ietf-oauth-v2-23
13
13
14
14
This functionality can allow clients to integrate with a given
15
-
Phabricator instance in a secure way with granular data access.
16
-
For example, Phabricator can be used as a central identity store for any
15
+
Phorge instance in a secure way with granular data access.
16
+
For example, Phorge can be used as a central identity store for any
17
17
clients that implement OAuth 2.0.
18
18
19
19
= Vocabulary =
···
41
41
42
42
= Obtaining an Authorization Code =
43
43
44
-
POST or GET `https://phabricator.example.com/oauthserver/auth/` with the
44
+
POST or GET `https://phorge.example.com/oauthserver/auth/` with the
45
45
following parameters:
46
46
47
47
- Required - **client_id** - the id of the newly registered client.
···
69
69
70
70
If there is an error, the OAuth Server will return a descriptive error
71
71
message. This error will be presented to the resource owner on the
72
-
Phabricator domain if there is reason to believe there is something fishy
72
+
Phorge domain if there is reason to believe there is something fishy
73
73
with the client. For example, if there is an issue with the redirect_uri.
74
74
Otherwise, the OAuth Server will redirect to the pertinent redirect_uri
75
75
and include the pertinent error information.
76
76
77
77
= Obtaining an Access Token =
78
78
79
-
POST or GET `https://phabricator.example.com/oauthserver/token/`
79
+
POST or GET `https://phorge.example.com/oauthserver/token/`
80
80
with the following parameters:
81
81
82
82
- Required - **client_id** - the id of the client
···
101
101
Simply include a query param with the key of "access_token" and the value
102
102
as the earlier obtained access token. For example:
103
103
104
-
```https://phabricator.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp```
104
+
```https://phorge.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp```
105
105
106
106
If the token has expired or is otherwise invalid, the client will receive
107
107
an error indicating as such. In these cases, the client should re-initiate
+5
-5
src/docs/contributor/version.diviner
+5
-5
src/docs/contributor/version.diviner
···
19
19
up-to-date install. See @{article:Providing Reproduction Steps} for details.
20
20
21
21
22
-
Phabricator Version
23
-
===================
22
+
Phorge Version
23
+
==============
24
24
25
-
To get Phabricator version information:
25
+
To get Phorge version information:
26
26
27
27
- Go to the {nav Config} application. You can type "Config" into the global
28
28
search box, or navigate to `https://your.install.com/config/`. You must
···
52
52
Running a Fork?
53
53
===============
54
54
55
-
If you've forked Phabricator and have local commits, please make sure you are
55
+
If you've forked Phorge and have local commits, please make sure you are
56
56
reporting upstream commit hashes, not local commit hashes. The UI will attempt
57
57
to figure out where you branched from, but it may not be able to in all cases.
58
58
···
68
68
```
69
69
70
70
Note that if you report a bug and have local commits, we will almost always ask
71
-
you to reproduce the issue against a clean copy of Phabricator before we
71
+
you to reproduce the issue against a clean copy of Phorge before we
72
72
continue. You can get help faster by doing this //before// reporting an issue.
73
73
74
74
-9
src/docs/flavor/about_flavor_text.diviner
-9
src/docs/flavor/about_flavor_text.diviner
+32
-29
src/docs/flavor/project_history.diviner
+32
-29
src/docs/flavor/project_history.diviner
···
1
-
@title Phabricator Project History
1
+
@title Phorge Project History
2
2
@group lore
3
3
4
-
A riveting tale of adventure. In this document, I refer to worldly and
5
-
sophisticated engineer Evan Priestley as "I", which is only natural as I am he.
6
-
7
-
This document is mostly just paragraph after paragraph of self-aggrandizement.
4
+
A riveting tale of adventure.
8
5
9
6
= In The Beginning =
10
7
11
-
I wrote the original version of Differential in one night at a Facebook
12
-
Hackathon in April or May 2007, along with Luke Shepard. I joined the company in
13
-
April and code review was already an established and mostly-mandatory part of
14
-
the culture, but it happened over email and was inefficient and hard to keep
15
-
track of. I remember feeling like I was spending a lot of time waiting for code
16
-
review to happen, which was a major motivator for building the tool.
8
+
Evan Priestley wrote the original version of Differential in one night at a
9
+
Facebook Hackathon in April or May 2007, along with Luke Shepard. He joined the
10
+
company in April and code review was already an established and mostly-mandatory
11
+
part of the culture, but it happened over email and was inefficient and hard to
12
+
keep track of. Evan remembers feeling like he was spending a lot of time waiting
13
+
for code review to happen, which was a major motivator for building the tool.
17
14
18
15
The original name of the tool was "Diffcamp". Some time earlier there had been
19
16
an attempt to create a project management tool that was a sort of hybrid between
20
-
Trac and Basecamp called "Traccamp". Since we were writing the code review tool
21
-
at the height of the brief popularity Traccamp enjoyed, we integrated and called
22
-
the new tool Diffcamp even though it had no relation to Basecamp. Traccamp fell
23
-
by the wayside shortly thereafter and was eventually removed.
17
+
Trac and Basecamp called "Traccamp". Since they were writing the code review tool
18
+
at the height of the brief popularity Traccamp enjoyed, Evan and Luke integrated
19
+
and called the new tool Diffcamp even though it had no relation to Basecamp.
20
+
Traccamp fell by the wayside shortly thereafter and was eventually removed.
24
21
25
-
However, Diffcamp didn't share its fate. We spent some more time working on it
26
-
and got good enough to win hearts and minds over emailing diffs around and was
27
-
soon the de facto method of code review at Facebook.
22
+
However, Diffcamp didn't share its fate. Evan and Luke spent some more time
23
+
working on it and got good enough to win hearts and minds over emailing diffs
24
+
around and was soon the de facto method of code review at Facebook.
28
25
29
26
= The Long Bloat =
30
27
···
34
31
SVN bridging by 2010). As these patches were contributed pretty much randomly,
35
32
it also gained a lot of performance problems, usability issues, and bugs.
36
33
37
-
Through 2007 and 2008 I worked mostly on frontend and support infrastructure;
38
-
among other things, I wrote a static resource management system called Haste. In
39
-
2009 I worked on the Facebook Lite site, where I built the Javelin Javascript
40
-
library and an MVC-flavored framework called Alite.
34
+
Through 2007 and 2008 Evan worked mostly on frontend and support infrastructure;
35
+
among other things, he wrote a static resource management system called Haste.
36
+
In 2009 Evan worked on the Facebook Lite site, where he built the Javelin
37
+
Javascript library and an MVC-flavored framework called Alite.
41
38
42
39
But by early 2010, Diffcamp was in pretty bad shape. Two years of having random
43
40
features grafted onto it without real direction had left it slow and difficult
···
49
46
50
47
= Differential =
51
48
52
-
I joined the new Dev Tools team around February 2010 and took over Diffcamp. I
53
-
renamed it to Differential, moved it to a new Alite-based infrastructure with
54
-
Javelin, and started making it somewhat less terrible. I eventually wrote
49
+
Evan joined the new Dev Tools team around February 2010 and took over Diffcamp.
50
+
He renamed it to Differential, moved it to a new Alite-based infrastructure with
51
+
Javelin, and started making it somewhat less terrible. He eventually wrote
55
52
Diffusion and built Herald to replace a very difficult-to-use predecessor. These
56
-
tools were less negatively received than the older versions. By December 2010 I
57
-
started open sourcing them; Haste became //Celerity// and Alite became
58
-
//Aphront//. I wrote Maniphest to track open issues with the project in January
59
-
or February, left Facebook in April, and shortly after, we open sourced
53
+
tools were less negatively received than the older versions. By December 2010,
54
+
Evan started open sourcing them; Haste became //Celerity// and Alite became
55
+
//Aphront//. He wrote Maniphest to track open issues with the project in January
56
+
or February, left Facebook in April, and shortly after, open sourced
60
57
Phabricator.
58
+
59
+
= Phork =
60
+
In 2021, Evan announced that Phabricator was no longer maintained. A group of
61
+
open-source contributors came together and forked it. This new
62
+
group called renamed the project "Phorge" and continues to maintain this
63
+
beloved and well-used project.
+3
-3
src/docs/flavor/recommendations_on_branching.diviner
+3
-3
src/docs/flavor/recommendations_on_branching.diviner
···
7
7
development and release management, not the use of local branches in Git or
8
8
queues or bookmarks in Mercurial.
9
9
10
-
This document is purely advisory. Phabricator works with a variety of branching
10
+
This document is purely advisory. Phorge works with a variety of branching
11
11
strategies, and diverging from the recommendations in this document
12
12
will not impact your ability to use it for code review and source management.
13
13
14
14
= Overview =
15
15
16
-
This document describes a branching strategy used by Facebook and Phabricator to
16
+
This document describes a branching strategy used by Facebook and Phorge to
17
17
develop software. It scales well and removes the pain associated with most
18
18
branching strategies. This strategy is most applicable to web applications, and
19
19
may be less applicable to other types of software. The basics are:
···
118
118
- Martin Fowler discusses these systems in a 2010 blog post here:
119
119
[[http://martinfowler.com/bliki/FeatureToggle.html |
120
120
Martin Fowler's FeatureToggle]].
121
-
- Phabricator just adds config options but defaults them to off. When
121
+
- Phorge just adds config options but defaults them to off. When
122
122
developing, we turn them on locally. Once a feature is ready, we default it
123
123
on. We have a vastly less context to deal with than most projects, however,
124
124
and sometimes get away with simply not linking new features in the UI until
+3
-3
src/docs/flavor/recommendations_on_revision_control.diviner
+3
-3
src/docs/flavor/recommendations_on_revision_control.diviner
···
3
3
4
4
Project recommendations on how to organize revision control.
5
5
6
-
This document is purely advisory. Phabricator works with a variety of revision
6
+
This document is purely advisory. Phorge works with a variety of revision
7
7
control strategies, and diverging from the recommendations in this document
8
8
will not impact your ability to use it for code review and source management.
9
9
10
-
This is my (epriestley's) personal take on the issue and not necessarily
11
-
representative of the views of the Phabricator team as a whole.
10
+
This is Evan's personal take on the issue and not necessarily
11
+
representative of the views of the Phorge team as a whole.
12
12
13
13
= Overview =
14
14
+10
-10
src/docs/flavor/so_many_databases.diviner
+10
-10
src/docs/flavor/so_many_databases.diviner
···
1
-
@title Why does Phabricator need so many databases?
1
+
@title Why does Phorge need so many databases?
2
2
@group lore
3
3
4
-
Phabricator uses about 60 databases (and we may have added more by the time you
4
+
Phorge uses about 60 databases (and we may have added more by the time you
5
5
read this document). This sometimes comes as a surprise, since you might assume
6
6
it would only use one database.
7
7
8
8
The approach we use is designed to work at scale for huge installs with many
9
9
thousands of users. We care a lot about working well for large installs, and
10
10
about scaling up gracefully to meet the needs of growing organizations. We want
11
-
small startups to be able to install Phabricator and have it grow with them as
11
+
small startups to be able to install Phorge and have it grow with them as
12
12
they expand to many thousands of employees.
13
13
14
-
A cost of this approach is that it makes Phabricator more difficult to install
14
+
A cost of this approach is that it makes Phorge more difficult to install
15
15
on shared hosts which require a lot of work to create or authorize access to
16
-
each database. However, Phabricator does a lot of advanced or complex things
16
+
each database. However, Phorge does a lot of advanced or complex things
17
17
which are difficult to configure or manage on shared hosts, and we don't
18
18
recommend installing it on a shared host. The install documentation explicitly
19
19
discourages installing on shared hosts.
···
26
26
Listing Databases
27
27
=================
28
28
29
-
You can get a full list of the databases Phabricator needs with `bin/storage
29
+
You can get a full list of the databases Phorge needs with `bin/storage
30
30
databases`. It will look something like this:
31
31
32
32
```
33
-
$ /core/lib/phabricator/bin/storage databases
33
+
$ /core/lib/phorge/bin/storage databases
34
34
secure_audit
35
35
secure_calendar
36
36
secure_chatlog
···
89
89
easier to work with a large project if you organize source files into
90
90
directories.
91
91
92
-
If you aren't developing Phabricator and never look at the data in the
92
+
If you aren't developing Phorge and never look at the data in the
93
93
database, you probably won't benefit from this organization. However, if you
94
-
are a developer or want to extend Phabricator or look under the hood, it's
94
+
are a developer or want to extend Phorge or look under the hood, it's
95
95
easier to find what you're looking for and work with the tables when they're
96
96
organized by application.
97
97
···
118
118
119
119
However, this cost is an artificial cost imposed by the selected environment,
120
120
and this is only the first of many issues you'll run into trying to install and
121
-
run Phabricator on a shared host. These issues are why we strongly discourage
121
+
run Phorge on a shared host. These issues are why we strongly discourage
122
122
using shared hosts, and recommend against them in the install guide.
123
123
124
124
+1
-1
src/docs/flavor/soon_static_resources.diviner
+1
-1
src/docs/flavor/soon_static_resources.diviner
···
121
121
122
122
= Reference Implementation: Celerity =
123
123
124
-
Some of the ideas discussed here are implemented in Phabricator's //Celerity//
124
+
Some of the ideas discussed here are implemented in Phorge's's //Celerity//
125
125
system, which is essentially a simplified version of the //Haste// system used
126
126
by Facebook.
+1
-1
src/docs/flavor/things_you_should_do_now.diviner
+1
-1
src/docs/flavor/things_you_should_do_now.diviner
···
134
134
135
135
Hopefully, whatever language you're writing in has good query libraries that
136
136
can handle escaping for you. If so, use them. If you're using PHP and don't have
137
-
a solution in place yet, the Phabricator implementation of `qsprintf()` is
137
+
a solution in place yet, the Phorge implementation of `qsprintf()` is
138
138
similar to Facebook's system and was successful there.
+5
-5
src/docs/flavor/writing_reviewable_code.diviner
+5
-5
src/docs/flavor/writing_reviewable_code.diviner
···
3
3
4
4
Project recommendations on how to structure changes.
5
5
6
-
This document is purely advisory. Phabricator works with a variety of revision
6
+
This document is purely advisory. Phorge works with a variety of revision
7
7
control strategies, and diverging from the recommendations in this document
8
8
will not impact your ability to use it for code review and source management.
9
9
10
10
= Overview =
11
11
12
12
This document describes a strategy for structuring changes used successfully at
13
-
Facebook and in Phabricator. In essence:
13
+
Facebook and in Phorge. In essence:
14
14
15
15
- Each commit should be as small as possible, but no smaller.
16
16
- The smallest a commit can be is a single cohesive idea: don't make commits
···
71
71
is for each change to have minimal complexity, line size is just a proxy that is
72
72
often well-correlated with complexity.
73
73
74
-
We generally follow these practices in Phabricator. The median change size for
75
-
Phabricator is 35 lines.
74
+
We generally follow these practices in Phorge. The median change size for
75
+
Phorge is 35 lines.
76
76
77
77
= Write Sensible Commit Messages =
78
78
···
146
146
reasons //why// a change is happening into the commit message.
147
147
- Although maybe the spelling and grammar shouldn't be egregiously bad?
148
148
149
-
Phabricator does not have guidelines for this stuff. You can obviously set
149
+
Phorge does not have guidelines for this stuff. You can obviously set
150
150
guidelines at your organization if you prefer, but getting the //why// into the
151
151
message is the most important part.
152
152
+1
-1
src/docs/tech/celerity.diviner
src/docs/contributor/celerity.diviner
+1
-1
src/docs/tech/celerity.diviner
src/docs/contributor/celerity.diviner
+2
-2
src/docs/tech/handles.diviner
src/docs/contributor/handles.diviner
+2
-2
src/docs/tech/handles.diviner
src/docs/contributor/handles.diviner
···
1
1
@title Handles Technical Documentation
2
-
@group handles
2
+
@group developer
3
3
4
4
Technical overview of Handles.
5
5
6
6
Overview
7
7
========
8
8
9
-
Most objects in Phabricator have PHIDs, which are globally unique identifiers
9
+
Most objects in Phorge have PHIDs, which are globally unique identifiers
10
10
that look like `PHID-USER-2zw4hwdt4i5b5ypikv6x`. If you know the PHID for an
11
11
object, you can load a **handle** for that object to get more information
12
12
about it.
+11
-11
src/docs/user/cluster/cluster.diviner
+11
-11
src/docs/user/cluster/cluster.diviner
···
1
1
@title Clustering Introduction
2
2
@group cluster
3
3
4
-
Guide to configuring Phabricator across multiple hosts for availability and
4
+
Guide to configuring Phorge across multiple hosts for availability and
5
5
performance.
6
6
7
7
···
12
12
adventure when deploying clusters. In the best of times, configuring a
13
13
cluster is complex and requires significant operations experience.
14
14
15
-
Phabricator can be configured to run on multiple hosts with redundant services
15
+
Phorge can be configured to run on multiple hosts with redundant services
16
16
to improve its availability and scalability, and make disaster recovery much
17
17
easier.
18
18
···
20
20
single host, but greatly reduces the cost of recovering from hardware and
21
21
network failures.
22
22
23
-
Each Phabricator service has an array of clustering options that can be
23
+
Each Phorge service has an array of clustering options that can be
24
24
configured somewhat independently. Configuring a cluster is inherently complex,
25
25
and this is an advanced feature aimed at installs with large userbases and
26
26
experienced operations personnel who need this high degree of flexibility.
···
55
55
Preparing for Clustering
56
56
========================
57
57
58
-
To begin deploying Phabricator in cluster mode, set up `cluster.addresses`
58
+
To begin deploying Phorge in cluster mode, set up `cluster.addresses`
59
59
in your configuration.
60
60
61
61
This option should contain a list of network address blocks which are considered
···
65
65
Whitelist Security" below for discussion.
66
66
67
67
If you are deploying hardware in EC2, a reasonable approach is to launch a
68
-
dedicated Phabricator VPC, whitelist the whole VPC as a Phabricator cluster,
69
-
and then deploy only Phabricator services into that VPC.
68
+
dedicated Phorge VPC, whitelist the whole VPC as a Phorge cluster,
69
+
and then deploy only Phorge services into that VPC.
70
70
71
71
If you have additional auxiliary hosts which run builds and tests via Drydock,
72
72
you should //not// include them in the cluster address definition. For more
···
84
84
cluster hosts as small as possible. Hosts on this list gain additional
85
85
capabilities, including these:
86
86
87
-
**Trusted HTTP Headers**: Normally, Phabricator distrusts the load balancer
87
+
**Trusted HTTP Headers**: Normally, Phorge distrusts the load balancer
88
88
HTTP headers `X-Forwarded-For` and `X-Forwarded-Proto` because they may be
89
89
client-controlled and can be set to arbitrary values by an attacker if no load
90
90
balancer is deployed. In particular, clients can set `X-Forwarded-For` to any
···
134
134
most important service to make redundant if your focus is on availability and
135
135
disaster recovery.
136
136
137
-
Configuring replicas allows Phabricator to run in read-only mode if you lose
137
+
Configuring replicas allows Phorge to run in read-only mode if you lose
138
138
the master and to quickly promote the replica as a replacement.
139
139
140
140
For details, see @{article:Cluster: Databases}.
···
147
147
can add multiple daemon or web hosts.
148
148
149
149
Repository replicas are important for availability if you host repositories
150
-
on Phabricator, but less important if you host repositories elsewhere
150
+
on Phorge, but less important if you host repositories elsewhere
151
151
(instead, you should focus on making that service more available).
152
152
153
153
The distributed nature of Git and Mercurial tend to mean that they are
···
243
243
244
244
Configuring search services is relatively simple and has no pre-requisites.
245
245
246
-
By default, Phabricator uses MySQL as a fulltext search engine, so deploying
246
+
By default, Phorge uses MySQL as a fulltext search engine, so deploying
247
247
multiple database hosts will effectively also deploy multiple fulltext search
248
248
hosts.
249
249
···
257
257
===================
258
258
259
259
Although hosts can run a single dedicated service type, certain groups of
260
-
services work well together. Phabricator clusters usually do not need to be
260
+
services work well together. Phorge clusters usually do not need to be
261
261
very large, so deploying a small number of hosts with multiple services is a
262
262
good place to start.
263
263
+2
-2
src/docs/user/cluster/cluster_daemons.diviner
+2
-2
src/docs/user/cluster/cluster_daemons.diviner
···
1
1
@title Cluster: Daemons
2
2
@group cluster
3
3
4
-
Configuring Phabricator to use multiple daemon hosts.
4
+
Configuring Phorge to use multiple daemon hosts.
5
5
6
6
Overview
7
7
========
···
38
38
39
39
You can launch additional daemon hosts without any special configuration.
40
40
Daemon hosts must be able to reach other hosts on the network, but do not need
41
-
to run any services (like HTTP or SSH). Simply deploy the Phabricator software
41
+
to run any services (like HTTP or SSH). Simply deploy the Phorge software
42
42
and configuration and start the daemons.
43
43
44
44
Normally, there is little reason to deploy dedicated daemon hosts. They can
+48
-48
src/docs/user/cluster/cluster_databases.diviner
+48
-48
src/docs/user/cluster/cluster_databases.diviner
···
1
1
@title Cluster: Databases
2
2
@group cluster
3
3
4
-
Configuring Phabricator to use multiple database hosts.
4
+
Configuring Phorge to use multiple database hosts.
5
5
6
6
Overview
7
7
========
8
8
9
-
You can deploy Phabricator with multiple database hosts, configured as a master
9
+
You can deploy Phorge with multiple database hosts, configured as a master
10
10
and a set of replicas. The advantages of doing this are:
11
11
12
12
- faster recovery from disasters by promoting a replica;
···
15
15
16
16
This configuration is complex, and many installs do not need to pursue it.
17
17
18
-
If you lose the master, Phabricator can degrade automatically into read-only
18
+
If you lose the master, Phorge can degrade automatically into read-only
19
19
mode and remain available, but can not fully recover without operational
20
20
intervention unless the master recovers on its own.
21
21
22
-
Phabricator will not currently send read traffic to replicas unless the master
22
+
Phorge will not currently send read traffic to replicas unless the master
23
23
has failed, so configuring a replica will not currently spread any load away
24
-
from the master. Future versions of Phabricator are expected to be able to
24
+
from the master. Future versions of Phorge are expected to be able to
25
25
distribute some read traffic to replicas.
26
26
27
-
Phabricator can not currently be configured into a multi-master mode, nor can
27
+
Phorge can not currently be configured into a multi-master mode, nor can
28
28
it be configured to automatically promote a replica to become the new master.
29
29
There are no current plans to support multi-master mode or autonomous failover,
30
30
although this may change in the future.
31
31
32
-
Phabricator applications //can// be partitioned across multiple database
32
+
Phorge applications //can// be partitioned across multiple database
33
33
masters. This does not provide redundancy and generally does not increase
34
34
resilience or resistance to data loss, but can help you scale and operate
35
-
Phabricator. For details, see
35
+
Phorge. For details, see
36
36
@{article:Cluster: Partitioning and Advanced Configuration}.
37
37
38
38
···
44
44
If you aren't sure how to do this, refer to the MySQL manual for instructions.
45
45
The MySQL documentation is comprehensive and walks through the steps and
46
46
options in good detail. You should understand MySQL replication before
47
-
deploying it in production: Phabricator layers on top of it, and does not
47
+
deploying it in production: Phorge layers on top of it, and does not
48
48
attempt to abstract it away.
49
49
50
-
Some useful notes for configuring replication for Phabricator:
50
+
Some useful notes for configuring replication for Phorge:
51
51
52
-
**Binlog Format**: Phabricator issues some queries which MySQL will detect as
52
+
**Binlog Format**: Phorge issues some queries which MySQL will detect as
53
53
unsafe if you use the `STATEMENT` binlog format (the default). Instead, use
54
54
`MIXED` (recommended) or `ROW` as the `binlog_format`.
55
55
56
-
**Grant `REPLICATION CLIENT` Privilege**: If you give the user that Phabricator
56
+
**Grant `REPLICATION CLIENT` Privilege**: If you give the user that Phorge
57
57
will use to connect to the replica database server the `REPLICATION CLIENT`
58
-
privilege, Phabricator's status console can give you more information about
58
+
privilege, Phorge's status console can give you more information about
59
59
replica health and state.
60
60
61
-
**Copying Data to Replicas**: Phabricator currently uses a mixture of MyISAM
61
+
**Copying Data to Replicas**: Phorge currently uses a mixture of MyISAM
62
62
and InnoDB tables, so it can be difficult to guarantee that a dump is wholly
63
63
consistent and suitable for loading into a replica because MySQL uses different
64
64
consistency mechanisms for the different storage engines.
65
65
66
66
An approach you may want to consider to limit downtime but still produce a
67
-
consistent dump is to leave Phabricator running but configured in read-only
67
+
consistent dump is to leave Phorge running but configured in read-only
68
68
mode while dumping:
69
69
70
70
- Stop all the daemons.
71
71
- Set `cluster.read-only` to `true` and deploy the new configuration. The
72
-
web UI should now show that Phabricator is in "Read Only" mode.
72
+
web UI should now show that Phorge is in "Read Only" mode.
73
73
- Dump the database. You can do this with `bin/storage dump --for-replica`
74
74
to add the `--master-data` flag to the underlying command and include a
75
75
`CHANGE MASTER ...` statement in the dump.
···
81
81
configure this and do not explicitly purge old logs with `PURGE BINARY LOGS`,
82
82
the binary logs on disk will grow unboundedly and relatively quickly.
83
83
84
-
Once you have a working replica, continue below to tell Phabricator about it.
84
+
Once you have a working replica, continue below to tell Phorge about it.
85
85
86
86
87
87
Configuring Replicas
88
88
====================
89
89
90
-
Once your replicas are in working order, tell Phabricator about them by
90
+
Once your replicas are in working order, tell Phorge about them by
91
91
configuring the `cluster.databases` option. This option must be configured from
92
-
the command line or in configuration files because Phabricator needs to read
92
+
the command line or in configuration files because Phorge needs to read
93
93
it //before// it can connect to databases.
94
94
95
-
This option value will list all of the database hosts that you want Phabricator
95
+
This option value will list all of the database hosts that you want Phorge
96
96
to interact with: your master and all your replicas. Each entry in the list
97
97
should have these keys:
98
98
···
105
105
host. If omitted, the default from `mysql.user` will be used.
106
106
- `pass`: //Optional string.// The password to use to connect to this host.
107
107
If omitted, the default from `mysql.pass` will be used.
108
-
- `disabled`: //Optional bool.// If set to `true`, Phabricator will not
108
+
- `disabled`: //Optional bool.// If set to `true`, Phorge will not
109
109
connect to this host. You can use this to temporarily take a host out
110
110
of service.
111
111
···
113
113
The other MySQL connection configuration options (`mysql.port`, `mysql.user`,
114
114
`mysql.pass`) are used only to provide defaults.
115
115
116
-
Once you've configured this option, restart Phabricator for the changes to take
116
+
Once you've configured this option, restart Phorge for the changes to take
117
117
effect, then continue to "Monitoring Replicas" to verify the configuration.
118
118
119
119
···
131
131
may be partial or misleading, and two requests served by different servers may
132
132
see different views of the cluster.
133
133
134
-
**Connection**: Phabricator tries to connect to each configured database, then
134
+
**Connection**: Phorge tries to connect to each configured database, then
135
135
shows the result in this column. If it fails, a brief diagnostic message with
136
136
details about the error is shown. If it succeeds, the column shows a rough
137
137
measurement of latency from the current webserver to the database.
···
141
141
replicating and no more than a few seconds behind master, and the master
142
142
should //not// be replicating from another database.
143
143
144
-
To report this status, the user Phabricator is connecting as must have the
144
+
To report this status, the user Phorge is connecting as must have the
145
145
`REPLICATION CLIENT` privilege (or the `SUPER` privilege) so it can run the
146
146
`SHOW SLAVE STATUS` command. The `REPLICATION CLIENT` privilege only enables
147
147
the user to run diagnostic commands so it should be reasonable to grant it in
···
163
163
appear that their data has been lost, even if it is safe and just hasn't
164
164
replicated yet.
165
165
166
-
Phabricator will attempt to prevent clients from seeing out-of-date views, but
166
+
Phorge will attempt to prevent clients from seeing out-of-date views, but
167
167
sometimes sending traffic to a delayed replica is the best available option
168
168
(for example, if the master can not be reached).
169
169
170
170
**Health**: This column shows the result of recent health checks against the
171
-
server. After several checks in a row fail, Phabricator will mark the server
171
+
server. After several checks in a row fail, Phorge will mark the server
172
172
as unhealthy and stop sending traffic to it until several checks in a row
173
173
later succeed.
174
174
···
189
189
database. Do this with great ceremony, making a cool explosion sound as you
190
190
run the `mysqld stop` command.
191
191
192
-
If things have been set up properly, Phabricator should degrade to a temporary
192
+
If things have been set up properly, Phorge should degrade to a temporary
193
193
read-only mode immediately. After a brief period of unresponsiveness, it will
194
194
degrade further into a longer-term read-only mode. For details on how this
195
195
works internally, see "Unreachable Masters" below.
196
196
197
-
Once satisfied, turn the master back on. After a brief delay, Phabricator
197
+
Once satisfied, turn the master back on. After a brief delay, Phorge
198
198
should recognize that the master is healthy again and recover fully.
199
199
200
200
Throughout this process, the {nav Database Servers} console will show a
···
202
202
request. You can use it to monitor state.
203
203
204
204
You can perform a more narrow test by enabling `cluster.read-only` in
205
-
configuration. This will put Phabricator into read-only mode immediately
205
+
configuration. This will put Phorge into read-only mode immediately
206
206
without turning off any databases.
207
207
208
208
You can use this mode to understand which capabilities will and will not be
···
211
211
accessible.
212
212
213
213
See the next section, "Degradation to Read Only Mode", for more details about
214
-
when, why, and how Phabricator degrades.
214
+
when, why, and how Phorge degrades.
215
215
216
216
If you run custom code or extensions, they may not accommodate read-only mode
217
217
properly. You should specifically test that they function correctly in
···
221
221
Degradation to Read-Only Mode
222
222
=============================
223
223
224
-
Phabricator will degrade to read-only mode when any of these conditions occur:
224
+
Phorge will degrade to read-only mode when any of these conditions occur:
225
225
226
226
- you turn it on explicitly;
227
227
- you configure cluster mode, but don't set up any masters;
228
228
- the master can not be reached while handling a request; or
229
229
- recent attempts to connect to the master have consistently failed.
230
230
231
-
When Phabricator is running in read-only mode, users can still read data and
231
+
When Phorge is running in read-only mode, users can still read data and
232
232
browse and clone repositories, but they can not edit, update, or push new
233
233
changes. For example, users can still read disaster recovery information on
234
234
the wiki or emergency contact information on user profiles.
···
239
239
- to test that the mode works like you expect it to;
240
240
- to make sure that information you need will be available;
241
241
- to prevent new writes while performing database maintenance; or
242
-
- to permanently archive a Phabricator install.
242
+
- to permanently archive a Phorge install.
243
243
244
244
You can also enable this mode implicitly by configuring `cluster.databases`
245
245
but disabling the master, or by not specifying any host as a master. This may
246
246
be more convenient than turning it on explicitly during the course of
247
247
operations work.
248
248
249
-
If Phabricator is unable to reach the master database, it will degrade into
249
+
If Phorge is unable to reach the master database, it will degrade into
250
250
read-only mode automatically. See "Unreachable Masters" below for details on
251
251
how this process works.
252
252
···
258
258
Promoting a Replica
259
259
===================
260
260
261
-
If you lose access to the master database, Phabricator will degrade into
261
+
If you lose access to the master database, Phorge will degrade into
262
262
read-only mode. This is described in greater detail below.
263
263
264
264
The easiest way to get out of read-only mode is to restore the master database.
265
265
If the database recovers on its own or operations staff can revive it,
266
-
Phabricator will return to full working order after a few moments.
266
+
Phorge will return to full working order after a few moments.
267
267
268
268
If you can't restore the master or are unsure you will be able to restore the
269
269
master quickly, you can promote a replica to become the new master instead.
···
295
295
Unreachable Masters
296
296
===================
297
297
298
-
This section describes how Phabricator determines that a master has been lost,
298
+
This section describes how Phorge determines that a master has been lost,
299
299
marks it unreachable, and degrades into read-only mode.
300
300
301
-
Phabricator degrades into read-only mode automatically in two ways: very
301
+
Phorge degrades into read-only mode automatically in two ways: very
302
302
briefly in response to a single connection failure, or more permanently in
303
303
response to a series of connection failures.
304
304
305
305
In the first case, if a request needs to connect to the master but is not able
306
-
to, Phabricator will temporarily degrade into read-only mode for the remainder
307
-
of that request. The alternative is to fail abruptly, but Phabricator can
306
+
to, Phorge will temporarily degrade into read-only mode for the remainder
307
+
of that request. The alternative is to fail abruptly, but Phorge can
308
308
sometimes degrade successfully and still respond to the user's request, so it
309
309
makes an effort to finish serving the request from replicas.
310
310
···
314
314
This temporary mode is intended to recover as gracefully as possible from brief
315
315
interruptions in service (a few seconds), like a server being restarted, a
316
316
network link becoming temporarily unavailable, or brief periods of load-related
317
-
disruption. If the anomaly is temporary, Phabricator should recover immediately
317
+
disruption. If the anomaly is temporary, Phorge should recover immediately
318
318
(on the next request once service is restored).
319
319
320
320
This mode can be slow for users (they need to wait on connection attempts to
321
321
the master which fail) and does not reduce load on the master (requests still
322
322
attempt to connect to it).
323
323
324
-
The second way Phabricator degrades is by running periodic health checks
324
+
The second way Phorge degrades is by running periodic health checks
325
325
against databases, and marking them unhealthy if they fail over a longer period
326
326
of time. This mechanism is very similar to the health checks that most HTTP
327
327
load balancers perform against web servers.
328
328
329
-
If a database fails several health checks in a row, Phabricator will mark it as
329
+
If a database fails several health checks in a row, Phorge will mark it as
330
330
unhealthy and stop sending all traffic (except for more health checks) to it.
331
331
This improves performance during a service interruption and reduces load on the
332
332
master, which may help it recover from load problems.
···
336
336
how many have succeeded.
337
337
338
338
Health checks run every 3 seconds, and 5 checks in a row must fail or succeed
339
-
before Phabricator marks the database as healthy or unhealthy, so it will
339
+
before Phorge marks the database as healthy or unhealthy, so it will
340
340
generally take about 15 seconds for a database to change state after it goes
341
341
down or comes up.
342
342
343
-
If all of the recent checks fail, Phabricator will mark the database as
343
+
If all of the recent checks fail, Phorge will mark the database as
344
344
unhealthy and stop sending traffic to it. If the master was the database that
345
-
was marked as unhealthy, Phabricator will actively degrade into read-only mode
345
+
was marked as unhealthy, Phorge will actively degrade into read-only mode
346
346
until it recovers.
347
347
348
348
This mode only attempts to connect to the unhealthy database once every few
···
350
350
(users rarely need to wait for bad connections to fail or time out) and the
351
351
database will receive less load.
352
352
353
-
Once all of the recent checks succeed, Phabricator will mark the database as
353
+
Once all of the recent checks succeed, Phorge will mark the database as
354
354
healthy again and continue sending traffic to it.
355
355
356
356
Health checks are tracked individually for each web server, so some web servers
···
397
397
Delayed replication is outside the scope of this document, but may be worth
398
398
considering as an additional data security step on top of backup snapshots
399
399
depending on your resources and needs. If you configure a delayed replica, do
400
-
not add it to the `cluster.databases` configuration: Phabricator should never
400
+
not add it to the `cluster.databases` configuration: Phorge should never
401
401
send traffic to it, and does not need to know about it.
402
402
403
403
+17
-17
src/docs/user/cluster/cluster_devices.diviner
+17
-17
src/docs/user/cluster/cluster_devices.diviner
···
6
6
Cluster Context
7
7
===============
8
8
9
-
This document describes a step in configuring Phabricator to run on
9
+
This document describes a step in configuring Phorge to run on
10
10
multiple hosts in a cluster configuration. This is an advanced feature. For
11
11
more information on clustering, see @{article:Clustering Introduction}.
12
12
···
38
38
Using Almanac
39
39
=============
40
40
41
-
The tool Phabricator uses to manage cluster devices is the **Almanac**
41
+
The tool Phorge uses to manage cluster devices is the **Almanac**
42
42
application, and most configuration will occur through the application's web
43
43
UI. If you are not familiar with it, see @{article:Almanac User Guide} first.
44
44
This document assumes you are familiar with Almanac concepts.
···
52
52
53
53
- Create an Almanac device record for each device.
54
54
- Generate, add, and trust SSH keys if necessary.
55
-
- Install Phabricator on the host.
55
+
- Install Phorge on the host.
56
56
- Use `bin/almanac register` from the host to register it as a device.
57
57
58
58
See below for guidance on each of these steps.
···
76
76
Using **shared keys** makes key management easier but safety checks won't be
77
77
able to catch a few kinds of mistakes. This may be a better choice if you are
78
78
setting up a larger cluster, plan to expand the cluster later, or have
79
-
experience with Phabricator clustering.
79
+
experience with Phorge clustering.
80
80
81
81
Because all cluster keys are all-powerful, there is no material difference
82
82
between these methods from a security or trust viewpoint. Unique keys are just
···
87
87
Create Almanac Device Records
88
88
=============================
89
89
90
-
For each host you plan to make part of a Phabricator cluster, go to the
90
+
For each host you plan to make part of a Phorge cluster, go to the
91
91
{nav Almanac} application and create a **device** record. For guidance on this
92
92
application, see @{article:Almanac User Guide}.
93
93
94
-
Add **interfaces** to each device record so Phabricator can tell how to
94
+
Add **interfaces** to each device record so Phorge can tell how to
95
95
connect to these hosts. Normally, you'll add one HTTP interface (usually on
96
96
port 80) and one SSH interface (by default, on port 2222) to each device:
97
97
···
107
107
108
108
Note that these hosts will normally run two `sshd` ports: the standard `sshd`
109
109
which you connect to to operate and administrate the host, and the special
110
-
Phabricator `sshd` that you connect to to clone and push repositories.
110
+
Phorge `sshd` that you connect to to clone and push repositories.
111
111
112
-
You should specify the Phabricator `sshd` port, **not** the standard `sshd`
112
+
You should specify the Phorge `sshd` port, **not** the standard `sshd`
113
113
port.
114
114
115
115
If you're using **unique** SSH keys for each device, continue to the next step.
···
141
141
each key as trusted:
142
142
143
143
```
144
-
phabricator/ $ ./bin/almanac trust-key --id <key-id-1>
145
-
phabricator/ $ ./bin/almanac trust-key --id <key-id-2>
144
+
phorge/ $ ./bin/almanac trust-key --id <key-id-1>
145
+
phorge/ $ ./bin/almanac trust-key --id <key-id-2>
146
146
...
147
147
```
148
148
···
153
153
If you need to revoke trust for a key later, use `untrust-key`:
154
154
155
155
```
156
-
phabricator/ $ ./bin/almanac untrust-key --id <key-id>
156
+
phorge/ $ ./bin/almanac untrust-key --id <key-id>
157
157
```
158
158
159
159
Once the keys are trusted, continue to the next step.
160
160
161
161
162
-
Install Phabricator
162
+
Install Phorge
163
163
===================
164
164
165
-
If you haven't already, install Phabricator on each device you plan to enroll
165
+
If you haven't already, install Phorge on each device you plan to enroll
166
166
in the cluster. Cluster repository devices must provide services over both HTTP
167
167
and SSH, so you need to install and configure both a webserver and a
168
-
Phabricator `sshd` on these hosts.
168
+
Phorge `sshd` on these hosts.
169
169
170
170
Generally, you will follow whatever process you otherwise use when installing
171
-
Phabricator.
171
+
Phorge.
172
172
173
173
NOTE: Do not start the daemons on the new devices yet. They won't work properly
174
174
until you've finished configuring things.
175
175
176
-
Once Phabricator is installed, you can enroll the devices in the cluster by
176
+
Once Phorge is installed, you can enroll the devices in the cluster by
177
177
registering them.
178
178
179
179
···
223
223
to share the same key but still identify as different devices.
224
224
225
225
The overall effect of the `bin/almanac` command is to copy identity and key
226
-
files into `phabricator/conf/keys/`. You can inspect the results by examining
226
+
files into `phorge/conf/keys/`. You can inspect the results by examining
227
227
that directory. The helper script just catches potential mistakes and makes
228
228
sure the process is completed correctly.
229
229
+3
-3
src/docs/user/cluster/cluster_notifications.diviner
+3
-3
src/docs/user/cluster/cluster_notifications.diviner
···
1
1
@title Cluster: Notifications
2
2
@group cluster
3
3
4
-
Configuring Phabricator to use multiple notification servers.
4
+
Configuring Phorge to use multiple notification servers.
5
5
6
6
Overview
7
7
========
···
29
29
For example, if a notification about a task update is not delivered, the next
30
30
page you load will still show the notification in your notification menu.
31
31
32
-
Generally, Phabricator works fine without notifications configured at all, so
32
+
Generally, Phorge works fine without notifications configured at all, so
33
33
clustering assumes that losing some messages during a disruption is acceptable.
34
34
35
35
···
88
88
```
89
89
90
90
91
-
Configuring Phabricator
91
+
Configuring Phorge
92
92
=======================
93
93
94
94
To configure clustering on the client side, add every service you run to
+18
-18
src/docs/user/cluster/cluster_partitioning.diviner
+18
-18
src/docs/user/cluster/cluster_partitioning.diviner
···
1
1
@title Cluster: Partitioning and Advanced Configuration
2
2
@group cluster
3
3
4
-
Guide to partitioning Phabricator applications across multiple database hosts.
4
+
Guide to partitioning Phorge applications across multiple database hosts.
5
5
6
6
Overview
7
7
========
8
8
9
-
You can partition Phabricator's applications across multiple databases. For
9
+
You can partition Phorge's applications across multiple databases. For
10
10
example, you can move an application like Files or Maniphest to a dedicated
11
11
database host.
12
12
···
18
18
operating the cluster easier.
19
19
20
20
This configuration is complex, and very few installs will benefit from pursuing
21
-
it. Phabricator will normally run comfortably with a single database master
21
+
it. Phorge will normally run comfortably with a single database master
22
22
even for large organizations.
23
23
24
24
Partitioning generally does not do much to increase resilience or make it
···
41
41
What Partitioning Does
42
42
======================
43
43
44
-
When you partition Phabricator, you move all of the data for one or more
44
+
When you partition Phorge, you move all of the data for one or more
45
45
applications (like Maniphest) to a new master database host. This is possible
46
-
because Phabricator stores data for each application in its own logical
47
-
database (like `phabricator_maniphest`) and performs no joins between databases.
46
+
because Phorge stores data for each application in its own logical
47
+
database (like `phorge_maniphest`) and performs no joins between databases.
48
48
49
49
If you're running into scale limits on a single master database, you can move
50
50
one or more of your most commonly-used applications to a second database host
···
78
78
{
79
79
"host": "db001.corporation.com",
80
80
"role": "master",
81
-
"user": "phabricator",
81
+
"user": "phorge",
82
82
"pass": "hunter2!trustno1",
83
83
"port": 3306,
84
84
"partition": [
···
88
88
{
89
89
"host": "db002.corporation.com",
90
90
"role": "replica",
91
-
"user": "phabricator",
91
+
"user": "phorge",
92
92
"pass": "hunter2!trustno1",
93
93
"port": 3306,
94
94
"master": "db001.corporation.com:3306"
···
96
96
{
97
97
"host": "db003.corporation.com",
98
98
"role": "master",
99
-
"user": "phabricator",
99
+
"user": "phorge",
100
100
"pass": "hunter2!trustno1",
101
101
"port": 3306,
102
102
"partition": [
···
108
108
{
109
109
"host": "db004.corporation.com",
110
110
"role": "replica",
111
-
"user": "phabricator",
111
+
"user": "phorge",
112
112
"pass": "hunter2!trustno1",
113
113
"port": 3306,
114
114
"master": "db003.corporation.com:3306"
···
137
137
To commit the configuration, run this command:
138
138
139
139
```
140
-
phabricator/ $ ./bin/storage partition
140
+
phorge/ $ ./bin/storage partition
141
141
```
142
142
143
143
Run this command after making any partition or clustering changes. Webservers
···
154
154
- Add the new database to `cluster.databases`, but keep its "partition"
155
155
configuration empty (just an empty list). If this is the first time you
156
156
are partitioning, you will need to configure your existing master as the
157
-
new "default". This will let Phabricator interact with it, but won't send
157
+
new "default". This will let Phorge interact with it, but won't send
158
158
any traffic to it yet.
159
159
- Run `bin/storage partition`.
160
160
- Run `bin/storage upgrade` to initialize the schemata on the new hosts.
161
-
- Stop writes to the applications you want to move by putting Phabricator
161
+
- Stop writes to the applications you want to move by putting Phorge
162
162
in read-only mode, or shutting down the webserver and daemons, or telling
163
163
everyone not to touch anything.
164
164
- Dump the data from the application databases on the old master.
165
165
- Load the data into the application databases on the new master.
166
-
- Reconfigure the "partition" setup so that Phabricator knows the databases
166
+
- Reconfigure the "partition" setup so that Phorge knows the databases
167
167
have moved.
168
168
- Run `bin/storage partition`.
169
169
- While still in read-only mode, check that all the data appears to be
···
178
178
How Partitioning Works
179
179
======================
180
180
181
-
If you have multiple masters, Phabricator keeps the entire set of schemata up
181
+
If you have multiple masters, Phorge keeps the entire set of schemata up
182
182
to date on all of them. When you run `bin/storage upgrade` or other storage
183
183
management commands, they generally affect all masters (if they do not, they
184
184
will prompt you to be more specific).
···
197
197
of which patches have been applied to that particular master so that
198
198
`bin/storage upgrade` can upgrade hosts correctly.
199
199
200
-
Phabricator does not perform joins across logical databases, so there are no
200
+
Phorge does not perform joins across logical databases, so there are no
201
201
meaningful differences in runtime behavior if two applications are on the same
202
202
physical host or different physical hosts.
203
203
···
212
212
213
213
`persistent` //(bool)// Enables persistent connections. Defaults to off.
214
214
215
-
With persistent connections enabled, Phabricator will keep a pool of database
215
+
With persistent connections enabled, Phorge will keep a pool of database
216
216
connections open between web requests and reuse them when serving subsequent
217
217
requests.
218
218
···
224
224
is likely to fix the issue. This option may also slightly increase performance.
225
225
226
226
The cost of using persistent connections is that you may need to raise the
227
-
MySQL `max_connections` setting: although Phabricator will make far fewer
227
+
MySQL `max_connections` setting: although Phorge will make far fewer
228
228
connections, the connections it does make will be longer-lived. Raising this
229
229
setting will increase MySQL memory requirements and may run into other limits,
230
230
like `open_files_limit`, which may also need to be raised.
+28
-28
src/docs/user/cluster/cluster_repositories.diviner
+28
-28
src/docs/user/cluster/cluster_repositories.diviner
···
1
1
@title Cluster: Repositories
2
2
@group cluster
3
3
4
-
Configuring Phabricator to use multiple repository hosts.
4
+
Configuring Phorge to use multiple repository hosts.
5
5
6
6
Overview
7
7
========
8
8
9
-
If you use Git, you can deploy Phabricator with multiple repository hosts,
9
+
If you use Git, you can deploy Phorge with multiple repository hosts,
10
10
configured so that each host is readable and writable. The advantages of doing
11
11
this are:
12
12
···
22
22
How Reads and Writes Work
23
23
=========================
24
24
25
-
Phabricator repository replicas are multi-master: every node is readable and
25
+
Phorge repository replicas are multi-master: every node is readable and
26
26
writable, and a cluster of nodes can (almost always) survive the loss of any
27
27
arbitrary subset of nodes so long as at least one node is still alive.
28
28
29
-
Phabricator maintains an internal version for each repository, and increments
29
+
Phorge maintains an internal version for each repository, and increments
30
30
it when the repository is mutated.
31
31
32
32
Before responding to a read, replicas make sure their version of the repository
···
77
77
Repository Hosts
78
78
================
79
79
80
-
Repository hosts must run a complete, fully configured copy of Phabricator,
80
+
Repository hosts must run a complete, fully configured copy of Phorge,
81
81
including a webserver. They must also run a properly configured `sshd`.
82
82
83
83
If you are converting existing hosts into cluster hosts, you may need to
···
123
123
124
124
- First, register at least one device according to the device clustering
125
125
instructions.
126
-
- Create a new service of type **Phabricator Cluster: Repository** in
126
+
- Create a new service of type **Phorge Cluster: Repository** in
127
127
Almanac.
128
128
- Bind this service to all the interfaces on the device or devices.
129
129
- For each binding, add a `protocol` key with one of these values:
···
170
170
$ ./bin/repository clusterize <repository> --remove-service
171
171
```
172
172
173
-
This command only changes how Phabricator connects to the repository; it does
173
+
This command only changes how Phorge connects to the repository; it does
174
174
not move any data or make any complex structural changes.
175
175
176
-
When Phabricator needs information about a non-clustered repository, it just
177
-
runs a command like `git log` directly on disk. When Phabricator needs
176
+
When Phorge needs information about a non-clustered repository, it just
177
+
runs a command like `git log` directly on disk. When Phorge needs
178
178
information about a clustered repository, it instead makes a service call to
179
179
another server, asking that server to run `git log` instead.
180
180
···
213
213
For instructions on configuring and registering devices, see
214
214
@{article:Cluster: Devices}.
215
215
216
-
As soon as you add active bindings to a service, Phabricator will begin
216
+
As soon as you add active bindings to a service, Phorge will begin
217
217
synchronizing repositories and sending traffic to the new device. You do not
218
-
need to copy any repository data to the device: Phabricator will automatically
218
+
need to copy any repository data to the device: Phorge will automatically
219
219
synchronize it.
220
220
221
221
If you have a large amount of repository data, you may want to help this
···
297
297
This screen shows all the configured devices which are hosting the repository
298
298
and the available version on that device.
299
299
300
-
**Version**: When a repository is mutated by a push, Phabricator increases
300
+
**Version**: When a repository is mutated by a push, Phorge increases
301
301
an internal version number for the repository. This column shows which version
302
302
is on disk on the corresponding device.
303
303
···
335
335
are reachable.
336
336
- **Ambiguous Leaders**: The internal state of the repository is unclear.
337
337
338
-
Phabricator can detect these issues, and responds by freezing the repository
338
+
Phorge can detect these issues, and responds by freezing the repository
339
339
(usually preventing all reads and writes) until the issue is resolved. These
340
-
conditions are normally rare and very little data is at risk, but Phabricator
340
+
conditions are normally rare and very little data is at risk, but Phorge
341
341
errs on the side of caution and requires decisions which may result in data
342
342
loss to be confirmed by a human.
343
343
···
357
357
- During or immediately after the write, lightning strikes the server
358
358
and destroys it.
359
359
360
-
Phabricator can not commit changes to a working copy (stored on disk) and to
360
+
Phorge can not commit changes to a working copy (stored on disk) and to
361
361
the global state (stored in a database) atomically, so there is necessarily a
362
362
narrow window between committing these two different states when some tragedy
363
363
can befall a server, leaving the global and local views of the repository state
364
364
possibly divergent.
365
365
366
-
In these cases, Phabricator fails into a frozen state where further writes
366
+
In these cases, Phorge fails into a frozen state where further writes
367
367
are not permitted until the failure is investigated and resolved. When a
368
368
repository is frozen in this way it remains readable.
369
369
···
391
391
command:
392
392
393
393
```
394
-
phabricator/ $ ./bin/repository thaw <repository> --demote <device>
394
+
phorge/ $ ./bin/repository thaw <repository> --demote <device>
395
395
```
396
396
397
397
{icon exclamation-triangle, color="yellow"} Any committed but unacknowledged
···
411
411
and destroys it.
412
412
413
413
Here, all of the "leader" devices with the most up-to-date copy of the
414
-
repository have been lost. Phabricator will freeze the repository refuse to
414
+
repository have been lost. Phorge will freeze the repository refuse to
415
415
serve requests because it can not serve reads consistently and can not accept
416
416
new writes without data loss.
417
417
···
424
424
present on the leaders but not present on the followers by examining the
425
425
push logs.
426
426
427
-
If you are comfortable discarding these changes, you can instruct Phabricator
427
+
If you are comfortable discarding these changes, you can instruct Phorge
428
428
that it can forget about the leaders by doing this:
429
429
430
430
- Disable the service bindings to all of the leader devices so they are no
···
434
434
To demote a device, run this command:
435
435
436
436
```
437
-
phabricator/ $ ./bin/repository thaw rXYZ --demote repo002.corp.net
437
+
phorge/ $ ./bin/repository thaw rXYZ --demote repo002.corp.net
438
438
```
439
439
440
440
{icon exclamation-triangle, color="red"} Any data which is only present on
···
450
450
dangerous and discards all unreplicated data in any repository on any device.**
451
451
452
452
```
453
-
phabricator/ $ ./bin/repository thaw --demote repo.corp.net --all-repositories
453
+
phorge/ $ ./bin/repository thaw --demote repo.corp.net --all-repositories
454
454
```
455
455
456
456
After you do this, continue below to promote a leader and restore the cluster
···
474
474
475
475
If you are moving repositories into cluster services, you can also reach this
476
476
state if you use `clusterize` to associate a repository with a service that is
477
-
bound to multiple active devices. In this case, Phabricator will not know which
477
+
bound to multiple active devices. In this case, Phorge will not know which
478
478
device or devices have up-to-date information.
479
479
480
-
When Phabricator can not tell which device in a cluster is a leader, it freezes
480
+
When Phorge can not tell which device in a cluster is a leader, it freezes
481
481
the cluster because it is possible that some devices have less data and others
482
482
have more, and if it chooses a leader arbitrarily it may destroy some data
483
483
which you would prefer to retain.
484
484
485
-
To resolve this, you need to tell Phabricator which device has the most
485
+
To resolve this, you need to tell Phorge which device has the most
486
486
up-to-date data and promote that device to become a leader. If you know all
487
487
devices have the same data, you are free to promote any device.
488
488
···
496
496
device will become authoritative:
497
497
498
498
```
499
-
phabricator/ $ ./bin/repository thaw rXYZ --promote repo002.corp.net
499
+
phorge/ $ ./bin/repository thaw rXYZ --promote repo002.corp.net
500
500
```
501
501
502
502
{icon exclamation-triangle, color="red"} Any data which is only present on
···
514
514
will propagate to the replicas.
515
515
516
516
You may be able to manually restore the branches by using tools like the
517
-
Phabricator push log or the Git reflog so it is less important to retain
517
+
Phorge push log or the Git reflog so it is less important to retain
518
518
repository snapshots than database snapshots, but it is still possible for
519
519
data to be lost permanently, especially if you don't notice the problem for
520
520
some time.
···
543
543
propagation.
544
544
545
545
You can encounter conflicts because directly modifying the working copy on disk
546
-
won't prevent users or Phabricator itself from performing writes to the same
547
-
working copy at the same time. Phabricator does not compromise the lower-level
546
+
won't prevent users or Phorge itself from performing writes to the same
547
+
working copy at the same time. Phorge does not compromise the lower-level
548
548
locks provided by the VCS so this is theoretically safe -- and this rarely
549
549
causes any significant problems in practice -- but doesn't make things any
550
550
simpler or easier.
+8
-8
src/docs/user/cluster/cluster_search.diviner
+8
-8
src/docs/user/cluster/cluster_search.diviner
···
4
4
Overview
5
5
========
6
6
7
-
You can configure Phabricator to connect to one or more fulltext search
7
+
You can configure Phorge to connect to one or more fulltext search
8
8
services.
9
9
10
-
By default, Phabricator will use MySQL for fulltext search. This is suitable
10
+
By default, Phorge will use MySQL for fulltext search. This is suitable
11
11
for most installs. However, alternate engines are supported.
12
12
13
13
···
33
33
]
34
34
```
35
35
36
-
When a user makes a change to a document, Phabricator writes the updated
36
+
When a user makes a change to a document, Phorge writes the updated
37
37
document into every configured, writable fulltext service.
38
38
39
-
When a user issues a query, Phabricator tries configured, readable services
39
+
When a user issues a query, Phorge tries configured, readable services
40
40
in order until it is able to execute the query successfully.
41
41
42
42
These options are supported by all service types:
···
141
141
on them. To do this, first initialize the services:
142
142
143
143
```
144
-
phabricator/ $ ./bin/search init
144
+
phorge/ $ ./bin/search init
145
145
```
146
146
147
147
This will perform index setup steps and other one-time configuration.
···
149
149
To populate documents in all indexes, run this command:
150
150
151
151
```
152
-
phabricator/ $ ./bin/search index --force --background --type all
152
+
phorge/ $ ./bin/search index --force --background --type all
153
153
```
154
154
155
155
This initiates an exhaustive rebuild of the document indexes. To get a more
156
156
detailed list of indexing options available, run:
157
157
158
158
```
159
-
phabricator/ $ ./bin/search help index
159
+
phorge/ $ ./bin/search help index
160
160
```
161
161
162
162
···
166
166
This is a more advanced example which shows a configuration with multiple
167
167
different services in different roles. In this example:
168
168
169
-
- Phabricator is using an Elasticsearch 2 service as its primary fulltext
169
+
- Phorge is using an Elasticsearch 2 service as its primary fulltext
170
170
service.
171
171
- An Elasticsearch 5 service is online, but only receiving writes.
172
172
- The MySQL service is serving as a backup if Elasticsearch fails.
+4
-4
src/docs/user/cluster/cluster_ssh.diviner
+4
-4
src/docs/user/cluster/cluster_ssh.diviner
···
1
1
@title Cluster: SSH Servers
2
2
@group cluster
3
3
4
-
Configuring Phabricator to use multiple SSH servers.
4
+
Configuring Phorge to use multiple SSH servers.
5
5
6
6
Overview
7
7
========
8
8
9
-
You can run Phabricator on multiple SSH servers. The advantages of doing this
9
+
You can run Phorge on multiple SSH servers. The advantages of doing this
10
10
are:
11
11
12
12
- you can completely survive the loss of multiple SSH hosts.
···
24
24
After configuring repositories in cluster mode, you can add more web hosts
25
25
at any time.
26
26
27
-
First, deploy the Phabricator software and configuration to a host, then
27
+
First, deploy the Phorge software and configuration to a host, then
28
28
register the host as a cluster device if it is not already registered (for
29
29
help, see @{article:Cluster: Devices}.)
30
30
31
31
Once the host is registered, start the SSH server, and then add the host to the
32
32
SSH load balancer pool.
33
33
34
-
Phabricator SSH servers are stateless, so you can pull them in and out of
34
+
Phorge SSH servers are stateless, so you can pull them in and out of
35
35
production freely.
36
36
37
37
You may also want to run web services on these hosts, since the service is very
+4
-4
src/docs/user/cluster/cluster_webservers.diviner
+4
-4
src/docs/user/cluster/cluster_webservers.diviner
···
1
1
@title Cluster: Web Servers
2
2
@group cluster
3
3
4
-
Configuring Phabricator to use multiple web servers.
4
+
Configuring Phorge to use multiple web servers.
5
5
6
6
Overview
7
7
========
8
8
9
-
You can run Phabricator on multiple web servers. The advantages of doing this
9
+
You can run Phorge on multiple web servers. The advantages of doing this
10
10
are:
11
11
12
12
- you can completely survive the loss of multiple web hosts; and
···
22
22
After configuring repositories in cluster mode, you can add more web hosts
23
23
at any time.
24
24
25
-
First, deploy the Phabricator software and configuration to a host, then
25
+
First, deploy the Phorge software and configuration to a host, then
26
26
register the host as a cluster device if it is not already registered (for
27
27
help, see @{article:Cluster: Devices}.)
28
28
29
29
Once the host is registered, start the web server, and then add the host to the
30
30
load balancer pool.
31
31
32
-
Phabricator web servers are stateless, so you can pull them in and out of
32
+
Phorge web servers are stateless, so you can pull them in and out of
33
33
production freely.
34
34
35
35
You may also want to run SSH services on these hosts, since the service is very
+16
-16
src/docs/user/configuration/advanced_configuration.diviner
+16
-16
src/docs/user/configuration/advanced_configuration.diviner
···
1
1
@title Configuration User Guide: Advanced Configuration
2
2
@group config
3
3
4
-
Configuring Phabricator for multiple environments.
4
+
Configuring Phorge for multiple environments.
5
5
6
6
= Overview =
7
7
8
-
Phabricator reads configuration from multiple sources. This document explains
8
+
Phorge reads configuration from multiple sources. This document explains
9
9
the configuration stack and how to set up advanced configuration sources, which
10
10
may be useful for deployments with multiple environments (e.g., development and
11
11
production).
12
12
13
13
This is a complicated topic for advanced users. You do not need to understand
14
-
this topic to install Phabricator.
14
+
this topic to install Phorge.
15
15
16
16
= Configuration Sources =
17
17
18
-
Phabricator supports the following configuration sources, from highest priority
18
+
Phorge supports the following configuration sources, from highest priority
19
19
to lowest priority:
20
20
21
21
- **Database**: Values are stored in the database and edited from the web UI
···
26
26
- **Config Files**: Values are stored in a config file in `conf/`. The file
27
27
to use is selected by writing to `conf/local/ENVIRONMENT`, or setting the
28
28
`PHABRICATOR_ENV` configuration variable. See below for more information.
29
-
- **Defaults**: Defaults hard-coded in the Phabricator source, which can not
29
+
- **Defaults**: Defaults hard-coded in the Phorge source, which can not
30
30
be edited. They have the lowest priority, and all other settings override
31
31
them.
32
32
33
-
Normally, you install and configure Phabricator by writing enough configuration
33
+
Normally, you install and configure Phorge by writing enough configuration
34
34
into the local config to get access to the database configuration (e.g., the
35
35
MySQL username, password, and hostname), then use the web interface to further
36
-
configure Phabricator.
36
+
configure Phorge.
37
37
38
38
= Configuration Files =
39
39
···
52
52
First, write an `exampleconfig.conf.php` file here (rename it according to the
53
53
name you chose):
54
54
55
-
phabricator/conf/custom/exampleconfig.conf.php
55
+
phorge/conf/custom/exampleconfig.conf.php
56
56
57
57
Its contents should look like this:
58
58
···
77
77
== Selecting a Configuration File ==
78
78
79
79
To select a configuration file, write the name of the file (relative to
80
-
`phabricator/conf/`) to `phabricator/conf/local/ENVIRONMENT`. For example, to
81
-
select `phabricator/conf/custom/exampleconfig.conf.php`, you would write
82
-
"custom/exampleconfig" to `phabricator/conf/local/ENVIRONMENT`:
80
+
`phorge/conf/`) to `phorge/conf/local/ENVIRONMENT`. For example, to
81
+
select `phorge/conf/custom/exampleconfig.conf.php`, you would write
82
+
"custom/exampleconfig" to `phorge/conf/local/ENVIRONMENT`:
83
83
84
-
phabricator/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
85
-
phabricator/ $ cat conf/local/ENVIRONMENT
84
+
phorge/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
85
+
phorge/ $ cat conf/local/ENVIRONMENT
86
86
custom/exampleconfig
87
-
phabricator/ $
87
+
phorge/ $
88
88
89
89
You can also set the environmental variable `PHABRICATOR_ENV`. This is more
90
90
involved but may be easier in some deployment environments. Note that this needs
···
107
107
)
108
108
```
109
109
110
-
After creating and selecting a configuration file, restart Phabricator (for
111
-
help, see @{article:Restarting Phabricator}). Any configuration you set should
110
+
After creating and selecting a configuration file, restart Phorge (for
111
+
help, see @{article:Restarting Phorge}). Any configuration you set should
112
112
take effect immediately, and your file should be visible in the Config
113
113
application when examining configuration.
114
114
+23
-23
src/docs/user/configuration/configuration_guide.diviner
+23
-23
src/docs/user/configuration/configuration_guide.diviner
···
1
1
@title Configuration Guide
2
2
@group config
3
3
4
-
This document contains basic configuration instructions for Phabricator.
4
+
This document contains basic configuration instructions for Phorge.
5
5
6
6
= Prerequisites =
7
7
···
11
11
The next steps are:
12
12
13
13
- Configure your webserver (Apache, nginx, or lighttpd).
14
-
- Access Phabricator with your browser.
14
+
- Access Phorge with your browser.
15
15
- Follow the instructions to complete setup.
16
16
17
17
= Webserver: Configuring Apache =
···
24
24
and `mod_ssl` if you intend to set up SSL.
25
25
26
26
If you haven't already, set up a domain name to point to the host you're
27
-
installing on. You can either install Phabricator on a subdomain (like
28
-
phabricator.example.com) or an entire domain, but you can not install it in
27
+
installing on. You can either install Phorge on a subdomain (like
28
+
phorge.example.com) or an entire domain, but you can not install it in
29
29
some subdirectory of an existing website. Navigate to whatever domain you're
30
30
going to use and make sure Apache serves you something to verify that DNS
31
31
is correctly configured.
···
33
33
NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like
34
34
'http://example/'. Some web browsers will not set cookies otherwise.
35
35
36
-
Now create a VirtualHost entry for Phabricator. It should look something like
36
+
Now create a VirtualHost entry for Phorge. It should look something like
37
37
this:
38
38
39
39
name=httpd.conf
40
40
<VirtualHost *>
41
41
# Change this to the domain which points to your host.
42
-
ServerName phabricator.example.com
42
+
ServerName phorge.example.com
43
43
44
-
# Change this to the path where you put 'phabricator' when you checked it
45
-
# out from GitHub when following the Installation Guide.
44
+
# Change this to the path where you put 'phorge' when you checked it
45
+
# out from the upstream when following the Installation Guide.
46
46
#
47
47
# Make sure you include "/webroot" at the end!
48
-
DocumentRoot /path/to/phabricator/webroot
48
+
DocumentRoot /path/to/phorge/webroot
49
49
50
50
RewriteEngine on
51
51
RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
52
52
</VirtualHost>
53
53
54
54
If Apache isn't currently configured to serve documents out of the directory
55
-
where you put Phabricator, you may also need to add `<Directory />` section. The
55
+
where you put Phorge, you may also need to add `<Directory />` section. The
56
56
syntax for this section depends on which version of Apache you're running.
57
57
(If you don't know, you can usually figure this out by running `httpd -v`.)
58
58
For Apache versions older than 2.4, use this:
59
59
60
60
name="Apache Older Than 2.4"
61
-
<Directory "/path/to/phabricator/webroot">
61
+
<Directory "/path/to/phorge/webroot">
62
62
Order allow,deny
63
63
Allow from all
64
64
</Directory>
···
66
66
For Apache versions 2.4 and newer, use this:
67
67
68
68
name="Apache 2.4 and Newer"
69
-
<Directory "/path/to/phabricator/webroot">
69
+
<Directory "/path/to/phorge/webroot">
70
70
Require all granted
71
71
</Directory>
72
72
···
81
81
82
82
name=nginx.conf
83
83
server {
84
-
server_name phabricator.example.com;
85
-
root /path/to/phabricator/webroot;
84
+
server_name phorge.example.com;
85
+
root /path/to/phorge/webroot;
86
86
87
87
location / {
88
88
index index.php;
···
121
121
122
122
For lighttpd, add a section like this to your lighttpd.conf:
123
123
124
-
$HTTP["host"] =~ "phabricator(\.example\.com)?" {
125
-
server.document-root = "/path/to/phabricator/webroot"
124
+
$HTTP["host"] =~ "phorge(\.example\.com)?" {
125
+
server.document-root = "/path/to/phorge/webroot"
126
126
url.rewrite-once = (
127
127
# This simulates QSA ("query string append") mode in apache
128
128
"^(/[^?]*)\?(.*)" => "/index.php?__path__=$1&$2",
···
167
167
168
168
During setup, you'll need to configure MySQL. To do this, get MySQL running and
169
169
verify you can connect to it. Consult the MySQL documentation for help. When
170
-
MySQL works, you need to load the Phabricator schemata into it. To do this, run:
170
+
MySQL works, you need to load the Phorge schemata into it. To do this, run:
171
171
172
-
phabricator/ $ ./bin/storage upgrade
172
+
phorge/ $ ./bin/storage upgrade
173
173
174
174
If your configuration uses an unprivileged user to connect to the database, you
175
175
may have to override the default user so the schema changes can be applied with
176
176
root or some other admin user:
177
177
178
-
phabricator/ $ ./bin/storage upgrade --user <user> --password <password>
178
+
phorge/ $ ./bin/storage upgrade --user <user> --password <password>
179
179
180
180
You can avoid the prompt the script issues by passing the `--force` flag (for
181
181
example, if you are scripting the upgrade process).
182
182
183
-
phabricator/ $ ./bin/storage upgrade --force
183
+
phorge/ $ ./bin/storage upgrade --force
184
184
185
-
NOTE: When you update Phabricator, run `storage upgrade` again to apply any
185
+
NOTE: When you update Phorge, run `storage upgrade` again to apply any
186
186
new updates.
187
187
188
188
= Next Steps =
···
200
200
@{article:Configuring a Preamble Script}; or
201
201
- configuring where uploaded files and attachments will be stored with
202
202
@{article:Configuring File Storage}; or
203
-
- configuring Phabricator so it can send mail with
203
+
- configuring Phorge so it can send mail with
204
204
@{article:Configuring Outbound Email}; or
205
205
- configuring inbound mail with @{article:Configuring Inbound Email}; or
206
206
- importing repositories with @{article:Diffusion User Guide}; or
···
209
209
@{article:Notifications User Guide: Setup and Configuration}; or
210
210
- configuring backups with
211
211
@{article:Configuring Backups and Performing Migrations}; or
212
-
- contributing to Phabricator with @{article:Contributor Introduction}.
212
+
- contributing to Phorge with @{article:Contributor Introduction}.
+16
-16
src/docs/user/configuration/configuration_locked.diviner
+16
-16
src/docs/user/configuration/configuration_locked.diviner
···
24
24
can edit it from the CLI instead, with `bin/config`:
25
25
26
26
```
27
-
phabricator/ $ ./bin/config set <key> <value>
27
+
phorge/ $ ./bin/config set <key> <value>
28
28
```
29
29
30
30
Some configuration options take complicated values which can be difficult
···
42
42
Then, set it with `--stdin` like this:
43
43
44
44
```
45
-
phabricator/ $ ./bin/config set <key> --stdin < config.json
45
+
phorge/ $ ./bin/config set <key> --stdin < config.json
46
46
```
47
47
48
48
A few settings have alternate CLI tools. Refer to the setting page for
···
57
57
58
58
59
59
**Required for bootstrapping**: Some options, like `mysql.host`, must be
60
-
available before Phabricator can read configuration from the database.
60
+
available before Phorge can read configuration from the database.
61
61
62
-
If you stored `mysql.host` only in the database, Phabricator would not know how
62
+
If you stored `mysql.host` only in the database, Phorge would not know how
63
63
to connect to the database in order to read the value in the first place.
64
64
65
65
These options must be provided in a configuration source which is read earlier
66
-
in the bootstrapping process, before Phabricator connects to the database.
66
+
in the bootstrapping process, before Phorge connects to the database.
67
67
68
68
69
69
**Errors could not be fixed from the web UI**: Some options, like
···
83
83
greater access.
84
84
85
85
For example, an attacker who could modify `cluster.mailers` (and other
86
-
similar options), could potentially reconfigure Phabricator to send mail
86
+
similar options), could potentially reconfigure Phorge to send mail
87
87
through an evil server they controlled, then trigger password resets on other
88
88
user accounts to compromise them.
89
89
···
105
105
You can review (and edit) hidden configuration from the CLI:
106
106
107
107
```
108
-
phabricator/ $ ./bin/config get <key>
109
-
phabricator/ $ ./bin/config set <key> <value>
108
+
phorge/ $ ./bin/config get <key>
109
+
phorge/ $ ./bin/config set <key> <value>
110
110
111
111
```
112
112
···
117
117
You may receive a setup issue warning you that a locked configuration key has a
118
118
value set in the database. Most commonly, this is because:
119
119
120
-
- In some earlier version of Phabricator, this configuration was not locked.
120
+
- In some earlier version of Phorge, this configuration was not locked.
121
121
- In the past, you or some other administrator used the web UI to set a
122
122
value. This value was written to the database.
123
123
- In a later version of the software, the value became locked.
124
124
125
-
When Phabricator was originally released, locked configuration did not yet
125
+
When Phorge was originally released, locked configuration did not yet
126
126
exist. Locked configuration was introduced later, and then configuration options
127
127
were gradually locked for a long time after that.
128
128
···
134
134
Locking values was more common in the past, and it is now relatively rare for
135
135
an unlocked value to become locked: when new values are introduced, they are
136
136
generally locked or hidden appropriately. In most cases, this setup issue only
137
-
affects installs that have used Phabricator for a long time.
137
+
affects installs that have used Phorge for a long time.
138
138
139
-
At time of writing (February 2019), Phabricator currently respects these old
140
-
database values. However, some future version of Phabricator will refuse to
139
+
At time of writing (February 2019), Phorge currently respects these old
140
+
database values. However, some future version of Phorge will refuse to
141
141
read locked configuration from the database, because this improves security if
142
142
an attacker manages to find a way to bypass restrictions on editing locked
143
143
configuration from the web UI.
···
147
147
file. Usually, you'll do this by first copying the value from the database:
148
148
149
149
```
150
-
phabricator/ $ ./bin/config get <key>
150
+
phorge/ $ ./bin/config get <key>
151
151
```
152
152
153
153
...into local configuration:
154
154
155
155
```
156
-
phabricator/ $ ./bin/config set <key> <value>
156
+
phorge/ $ ./bin/config set <key> <value>
157
157
```
158
158
159
159
...and then removing the database value:
160
160
161
161
```
162
-
phabricator/ $ ./bin/config delete --database <key>
162
+
phorge/ $ ./bin/config delete --database <key>
163
163
```
164
164
165
165
See @{Configuration User Guide: Advanced Configuration} for some more detailed
+6
-6
src/docs/user/configuration/configuring_accounts_and_registration.diviner
+6
-6
src/docs/user/configuration/configuring_accounts_and_registration.diviner
···
1
1
@title Configuring Accounts and Registration
2
2
@group config
3
3
4
-
Describes how to configure user access to Phabricator.
4
+
Describes how to configure user access to Phorge.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator supports a number of login systems. You can enable or disable these
9
+
Phorge supports a number of login systems. You can enable or disable these
10
10
systems to configure who can register for and access your install, and how users
11
11
with existing accounts can login.
12
12
···
18
18
- **LDAP:** Users use LDAP credentials to log in or register.
19
19
- **OAuth:** Users use accounts on a supported OAuth2 provider (like
20
20
GitHub, Facebook, or Google) to log in or register.
21
-
- **Other Providers:** More providers are available, and Phabricator
21
+
- **Other Providers:** More providers are available, and Phorge
22
22
can be extended with custom providers. See the "Auth" application for
23
23
a list of available providers.
24
24
···
26
26
add one or more providers after you complete the installation process.
27
27
28
28
After you add a provider, you can link it to existing accounts (for example,
29
-
associate an existing Phabricator account with a GitHub OAuth account) or users
29
+
associate an existing Phorge account with a GitHub OAuth account) or users
30
30
can use it to register new accounts (assuming you enable these options).
31
31
32
32
33
33
Recovering Inaccessible Accounts
34
34
================================
35
35
36
-
If you accidentally lock yourself out of Phabricator (for example, by disabling
36
+
If you accidentally lock yourself out of Phorge (for example, by disabling
37
37
all authentication providers), you can normally use the "send a login link"
38
38
action from the login screen to email yourself a login link and regain access
39
39
to your account.
···
43
43
access, run:
44
44
45
45
```
46
-
phabricator/ $ ./bin/auth recover <username>
46
+
phorge/ $ ./bin/auth recover <username>
47
47
```
48
48
49
49
...where `<username>` is the account username you want to recover access
+20
-20
src/docs/user/configuration/configuring_backups.diviner
+20
-20
src/docs/user/configuration/configuring_backups.diviner
···
1
1
@title Configuring Backups and Performing Migrations
2
2
@group config
3
3
4
-
Advice for backing up Phabricator, or migrating from one machine to another.
4
+
Advice for backing up Phorge, or migrating from one machine to another.
5
5
6
6
7
7
Overview
8
8
========
9
9
10
-
Phabricator does not currently have a comprehensive backup system, but creating
11
-
backups is not particularly difficult and Phabricator does have a few basic
10
+
Phorge does not currently have a comprehensive backup system, but creating
11
+
backups is not particularly difficult and Phorge does have a few basic
12
12
tools which can help you set up a reasonable process. In particular, the things
13
13
which needs to be backed up are:
14
14
15
15
- the MySQL databases;
16
16
- hosted repositories;
17
17
- uploaded files; and
18
-
- your Phabricator configuration files.
18
+
- your Phorge configuration files.
19
19
20
20
This document discusses approaches for backing up this data.
21
21
···
24
24
will just backup the old machine and then restore the data onto the new
25
25
machine.
26
26
27
-
WARNING: You need to restart Phabricator after restoring data.
27
+
WARNING: You need to restart Phorge after restoring data.
28
28
29
-
Restarting Phabricator after performing a restore makes sure that caches are
29
+
Restarting Phorge after performing a restore makes sure that caches are
30
30
flushed properly. For complete instructions, see
31
-
@{article:Restarting Phabricator}.
31
+
@{article:Restarting Phorge}.
32
32
33
33
34
34
Backup: MySQL Databases
35
35
=======================
36
36
37
-
Most of Phabricator's data is stored in MySQL, and it's the most important thing
37
+
Most of Phorge's data is stored in MySQL, and it's the most important thing
38
38
to back up. You can run `bin/storage dump` to get a dump of all the MySQL
39
39
databases. This is a convenience script which just runs a normal `mysqldump`,
40
-
but will only dump databases Phabricator owns.
40
+
but will only dump databases Phorge owns.
41
41
42
42
Since most of this data is compressible, it may be helpful to run it through
43
43
gzip prior to storage. For example:
44
44
45
-
phabricator/ $ ./bin/storage dump --compress --output backup.sql.gz
45
+
phorge/ $ ./bin/storage dump --compress --output backup.sql.gz
46
46
47
47
Then store the backup somewhere safe, like in a box buried under an old tree
48
48
stump. No one will ever think to look for it there.
···
59
59
Backup: Hosted Repositories
60
60
===========================
61
61
62
-
If you host repositories in Phabricator, you should back them up. You can use
62
+
If you host repositories in Phorge, you should back them up. You can use
63
63
`bin/repository list-paths` to show the local paths on disk for each
64
64
repository. To back them up, copy them elsewhere.
65
65
···
87
87
**Amazon S3**: If you use Amazon S3, redundancy and backups are built in to the
88
88
service. This is probably sufficient for most installs. If you trust Amazon with
89
89
your data //except not really//, you can backup your S3 bucket outside of
90
-
Phabricator.
90
+
Phorge.
91
91
92
92
**Local Disk**: If you use the local disk storage engine, you'll need to back up
93
93
files manually. You can do this by creating a copy of the root directory where
94
-
you told Phabricator to put files (the `storage.local-disk.path` configuration
94
+
you told Phorge to put files (the `storage.local-disk.path` configuration
95
95
setting).
96
96
97
97
For more information about configuring how files are stored, see
···
108
108
===========================
109
109
110
110
You should also backup your configuration files, and any scripts you use to
111
-
deploy or administrate Phabricator (like a customized upgrade script). The best
111
+
deploy or administrate Phorge (like a customized upgrade script). The best
112
112
way to do this is to check them into a private repository somewhere and just use
113
113
whatever backup process you already have in place for repositories. Just copying
114
114
them somewhere will work fine too, of course.
115
115
116
-
In particular, you should backup this configuration file which Phabricator
116
+
In particular, you should backup this configuration file which Phorge
117
117
creates:
118
118
119
-
phabricator/conf/local/local.json
119
+
phorge/conf/local/local.json
120
120
121
121
This file contains all of the configuration settings that have been adjusted
122
122
by using `bin/config set <key> <value>`.
···
126
126
============================
127
127
128
128
To restore configuration files, just copy them into the right locations. Copy
129
-
your backup of `local.json` to `phabricator/conf/local/local.json`.
129
+
your backup of `local.json` to `phorge/conf/local/local.json`.
130
130
131
131
Security
132
132
========
133
133
134
-
MySQL dumps have no builtin encryption and most data in Phabricator is stored in
134
+
MySQL dumps have no builtin encryption and most data in Phorge is stored in
135
135
a raw, accessible form, so giving a user access to backups is a lot like giving
136
-
them shell access to the machine Phabricator runs on. In particular, a user who
136
+
them shell access to the machine Phorge runs on. In particular, a user who
137
137
has the backups can:
138
138
139
139
- read data that policies do not permit them to see;
···
141
141
- read other users' session and conduit tokens and impersonate them.
142
142
143
143
Some of this information is durable, so disclosure of even a very old backup may
144
-
present a risk. If you restrict access to the Phabricator host or database, you
144
+
present a risk. If you restrict access to the Phorge host or database, you
145
145
should also restrict access to the backups.
146
146
147
147
+7
-7
src/docs/user/configuration/configuring_encryption.diviner
+7
-7
src/docs/user/configuration/configuring_encryption.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator supports at-rest encryption of uploaded file data stored in the
9
+
Phorge supports at-rest encryption of uploaded file data stored in the
10
10
"Files" application.
11
11
12
12
Configuring at-rest file data encryption does not encrypt any other data or
13
13
resources. In particular, it does not encrypt the database and does not encrypt
14
14
Passphrase credentials.
15
15
16
-
Attackers who compromise a Phabricator host can read the master key and decrypt
16
+
Attackers who compromise a Phorge host can read the master key and decrypt
17
17
the data. In most configurations, this does not represent a significant
18
18
barrier above and beyond accessing the file data. Thus, configuring at-rest
19
19
encryption is primarily useful for two types of installs:
···
81
81
82
82
The `raw` storage format is automatically selected for all newly uploaded
83
83
file data if no key is marked as the `default` key in the keyring. This is
84
-
the behavior of Phabricator if you haven't configured anything.
84
+
the behavior of Phorge if you haven't configured anything.
85
85
86
86
This format stores raw data without modification.
87
87
···
104
104
You can generate a valid, properly encoded AES256 master key with this command:
105
105
106
106
```
107
-
phabricator/ $ ./bin/files generate-key --type aes-256-cbc
107
+
phorge/ $ ./bin/files generate-key --type aes-256-cbc
108
108
```
109
109
110
110
This mode is generally similar to the default server-side encryption mode
···
134
134
To change the format of an individual file, run this command:
135
135
136
136
```
137
-
phabricator/ $ ./bin/files encode --as <format> F123 [--key <key>]
137
+
phorge/ $ ./bin/files encode --as <format> F123 [--key <key>]
138
138
```
139
139
140
140
This will change the storage format of the specified file.
···
167
167
To cycle an individual file, run this command:
168
168
169
169
```
170
-
phabricator/ $ ./bin/files cycle F123
170
+
phorge/ $ ./bin/files cycle F123
171
171
```
172
172
173
173
Verify that cycling worked properly by examining the command output and
···
177
177
You can cycle all files with this command:
178
178
179
179
```
180
-
phabricator/ $ ./bin/files cycle --all
180
+
phorge/ $ ./bin/files cycle --all
181
181
```
182
182
183
183
Once all files have been cycled, remove the old master key from the keyring.
+17
-17
src/docs/user/configuration/configuring_file_domain.diviner
+17
-17
src/docs/user/configuration/configuring_file_domain.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Serving files that users upload from the same domain that Phabricator runs on
9
+
Serving files that users upload from the same domain that Phorge runs on
10
10
is a security risk.
11
11
12
12
In general, doing this creates a risk that users who have permission to upload
···
17
17
executing the file and gain access to their session.
18
18
19
19
The best way to mitigate this threat is to serve files from a separate domain.
20
-
For example, if Phabricator is hosted at `https://phabricator.example.com/`,
20
+
For example, if Phorge is hosted at `https://phorge.example.com/`,
21
21
you can serve files from `https://files.exampleusercontent.com/`.
22
22
23
23
The alternate file domain should be a completely different domain from your
···
48
48
particular sense to use if you're hosting your install in AWS.
49
49
50
50
To configure it, set up a new CloudFront distribution which is pointed at
51
-
your Phabricator install as an origin (make sure you point it at the primary
51
+
your Phorge install as an origin (make sure you point it at the primary
52
52
domain name of your install, not just a load balancer or instance). You do not
53
53
need to set up a new domain name, which makes setup a bit more straightforward.
54
54
···
57
57
`GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`.
58
58
59
59
Once configured, accessing the distribution's domain name should return a
60
-
Phabricator error page indicating that Phabricator does not recognize the
60
+
Phorge error page indicating that Phorge does not recognize the
61
61
domain. If you see this page, it means you've configured things correctly.
62
62
63
-
Continue to "Configuring Phabricator", below.
63
+
Continue to "Configuring Phorge", below.
64
64
65
65
Approach: CloudFlare
66
66
========
···
68
68
WARNING: You should review all your CloudFlare settings, and be very
69
69
sure to turn off all JavaScript, HTML, CSS minification and
70
70
optimization features, including systems like "Rocket Loader". These
71
-
features will break Phabricator in strange and mysterious ways that
71
+
features will break Phorge in strange and mysterious ways that
72
72
are unpredictable. Only allow CloudFlare to cache files, and never
73
73
optimize them.
74
74
···
76
76
77
77
To set up CloudFlare, you'll need to register a second domain and go through
78
78
their enrollment process to host the alternate domain on their servers. Use a
79
-
CNAME record to forward a subdomain to your Phabricator install.
79
+
CNAME record to forward a subdomain to your Phorge install.
80
80
81
81
CloudFlare will automatically generate SSL certificates for hosted domains,
82
82
which can significantly reduce the cost and complexity of setup.
83
83
84
84
Once configured, accessing the CNAME-forwarded subdomain should return a
85
-
Phabricator error page indicating that Phabricator does not recognize the
85
+
Phorge error page indicating that Phorge does not recognize the
86
86
domain. If you see this page, it means you've configured things correctly.
87
87
88
-
Continue to "Configuring Phabricator", below.
88
+
Continue to "Configuring Phorge", below.
89
89
90
90
Approach: Self Hosted
91
91
========
92
92
93
93
To do this, just set up a second domain exactly like your primary domain is
94
-
set up. When setup is complete, visiting the domain should return a Phabricator
95
-
error page indicating that Phabricator does not recognize the domain. This
94
+
set up. When setup is complete, visiting the domain should return a Phorge
95
+
error page indicating that Phorge does not recognize the domain. This
96
96
means that you've configured things correctly.
97
97
98
98
Note that if you use SSL (which you should), you'll also need to get a
···
102
102
to provide some of the performance benefits of a CDN, but this is advanced and
103
103
outside the scope of this documentation.
104
104
105
-
Continue to "Configuring Phabricator", below.
105
+
Continue to "Configuring Phorge", below.
106
106
107
-
Configuring Phabricator
107
+
Configuring Phorge
108
108
========
109
109
110
-
After you've set up a CDN or an alternate domain, configure Phabricator to
110
+
After you've set up a CDN or an alternate domain, configure Phorge to
111
111
recognize the domain. Run this command, providing the domain you have
112
112
configured in place of the `<domain>` token. You should include the protocol,
113
-
so an example domain might be `https://cdn.phabcdn.net/`.
113
+
so an example domain might be `https://cdn.examplecdn.com/`.
114
114
115
-
phabricator/ $ ./bin/config set security.alternate-file-domain <domain>
115
+
phorge/ $ ./bin/config set security.alternate-file-domain <domain>
116
116
117
-
Phabricator should now serve CSS, JS, images, profile pictures, and user
117
+
Phorge should now serve CSS, JS, images, profile pictures, and user
118
118
content through the file domain. You can verify this with "View Source" or
119
119
by downloading a file and checking the URL.
+18
-18
src/docs/user/configuration/configuring_file_storage.diviner
+18
-18
src/docs/user/configuration/configuring_file_storage.diviner
···
6
6
Overview
7
7
========
8
8
9
-
This document describes how to configure Phabricator to support large file
10
-
uploads, and how to choose where Phabricator stores files.
9
+
This document describes how to configure Phorge to support large file
10
+
uploads, and how to choose where Phorge stores files.
11
11
12
12
There are two major things to configure:
13
13
···
17
17
The following sections will guide you through this configuration.
18
18
19
19
20
-
How Phabricator Stores Files
20
+
How Phorge Stores Files
21
21
============================
22
22
23
-
Phabricator stores files in "storage engines", which are modular backends
23
+
Phorge stores files in "storage engines", which are modular backends
24
24
that implement access to some storage system (like MySQL, the filesystem, or
25
25
a cloud storage service like Amazon S3).
26
26
27
-
Phabricator stores large files by breaking them up into many chunks (a few
27
+
Phorge stores large files by breaking them up into many chunks (a few
28
28
megabytes in size) and storing the chunks in an underlying storage engine.
29
-
This makes it easier to implement new storage engines and gives Phabricator
29
+
This makes it easier to implement new storage engines and gives Phorge
30
30
more flexibility in managing file data.
31
31
32
32
The first section of this document discusses configuring your install so that
···
45
45
one.
46
46
47
47
To upload large files, you need to increase all the limits to at least
48
-
**32MB**. This will allow you to upload file chunks, which will let Phabricator
48
+
**32MB**. This will allow you to upload file chunks, which will let Phorge
49
49
store arbitrarily large files.
50
50
51
51
The settings which limit file uploads are:
···
62
62
- **lighttpd**: lighttpd limits requests with the lighttpd
63
63
`server.max-request-size` directive.
64
64
65
-
Set the applicable limit to at least **32MB**. Phabricator can not read these
65
+
Set the applicable limit to at least **32MB**. Phorge can not read these
66
66
settings, so it can not raise setup warnings if they are misconfigured.
67
67
68
68
**PHP**: PHP has several directives which limit uploads. These directives are
69
69
found in `php.ini`.
70
70
71
71
- **post_max_size**: Maximum POST request size PHP will accept. If you
72
-
exceed this, Phabricator will give you a useful error. This often defaults
73
-
to `8M`. Set this to at least `32MB`. Phabricator will give you a setup
72
+
exceed this, Phorge will give you a useful error. This often defaults
73
+
to `8M`. Set this to at least `32MB`. Phorge will give you a setup
74
74
warning about this if it is set too low.
75
75
- **memory_limit**: For some uploads, file data will be read into memory
76
-
before Phabricator can adjust the memory limit. If you exceed this, PHP
76
+
before Phorge can adjust the memory limit. If you exceed this, PHP
77
77
may give you a useful error, depending on your configuration. It is
78
-
recommended that you set this to `-1` to disable it. Phabricator will
78
+
recommended that you set this to `-1` to disable it. Phorge will
79
79
give you a setup warning about this if it is set too low.
80
80
81
81
You may also want to configure these PHP options:
···
87
87
- **upload_max_filesize**: Maximum file size PHP will accept in a raw file
88
88
upload. This is not normally used when uploading files via drag-and-drop,
89
89
but affects some other kinds of file uploads. If you exceed this,
90
-
Phabricator will give you a useful error. This often defaults to `2M`. Set
90
+
Phorge will give you a useful error. This often defaults to `2M`. Set
91
91
this to at least `32MB`.
92
92
93
93
Once you've adjusted all this configuration, your server will be able to
···
98
98
Storage Engines
99
99
===============
100
100
101
-
Phabricator supports several different file storage engines:
101
+
Phorge supports several different file storage engines:
102
102
103
103
| Engine | Setup | Cost | Notes |
104
104
|--------|-------|------|-------|
···
110
110
You can review available storage engines and their configuration by navigating
111
111
to {nav Applications > Files > Help/Options > Storage Engines} in the web UI.
112
112
113
-
By default, Phabricator is configured to store files up to 1MB in MySQL, and
113
+
By default, Phorge is configured to store files up to 1MB in MySQL, and
114
114
reject files larger than 1MB. To store larger files, you can either:
115
115
116
116
- increase the MySQL limit to at least 8MB; or
···
172
172
=======================
173
173
174
174
You can test that things are correctly configured by dragging and dropping
175
-
a file onto the Phabricator home page. If engines have been configured
175
+
a file onto the Phorge home page. If engines have been configured
176
176
properly, the file should upload.
177
177
178
178
Migrating Files Between Engines
···
183
183
recently set up S3 and want to migrate all your files there. First, migrate one
184
184
file to make sure things work:
185
185
186
-
phabricator/ $ ./bin/files migrate --engine amazon-s3 F12345
186
+
phorge/ $ ./bin/files migrate --engine amazon-s3 F12345
187
187
188
188
If that works properly, you can then migrate everything:
189
189
190
-
phabricator/ $ ./bin/files migrate --engine amazon-s3 --all
190
+
phorge/ $ ./bin/files migrate --engine amazon-s3 --all
191
191
192
192
You can use `--dry-run` to show which migrations would be performed without
193
193
taking any action. Run `bin/files help` for more options and information.
+36
-36
src/docs/user/configuration/configuring_inbound_email.diviner
+36
-36
src/docs/user/configuration/configuring_inbound_email.diviner
···
2
2
@group config
3
3
4
4
This document contains instructions for configuring inbound email, so users
5
-
may interact with some Phabricator applications via email.
5
+
may interact with some Phorge applications via email.
6
6
7
7
Preamble
8
8
========
9
9
10
-
Phabricator can process inbound mail in two general ways:
10
+
Phorge can process inbound mail in two general ways:
11
11
12
12
**Handling Replies**: When users reply to email notifications about changes,
13
-
Phabricator can turn email into comments on the relevant discussion thread.
13
+
Phorge can turn email into comments on the relevant discussion thread.
14
14
15
15
**Creating Objects**: You can configure an address like `bugs@yourcompany.com`
16
16
to create new objects (like tasks) when users send email.
···
21
21
22
22
To configure inbound mail, you will generally:
23
23
24
-
- Configure some mail domain to submit mail to Phabricator for processing.
24
+
- Configure some mail domain to submit mail to Phorge for processing.
25
25
- For handling replies, set `metamta.reply-handler-domain` in your
26
26
configuration.
27
27
- For handling email that creates objects, configure inbound addresses in the
···
34
34
======================
35
35
36
36
Usually, the most challenging part of configuring inbound mail is getting mail
37
-
delivered to Phabricator for processing. This step can be made much easier if
38
-
you use a third-party mail service which can submit mail to Phabricator via
37
+
delivered to Phorge for processing. This step can be made much easier if
38
+
you use a third-party mail service which can submit mail to Phorge via
39
39
webhooks.
40
40
41
-
Some available approaches for delivering mail to Phabricator are:
41
+
Some available approaches for delivering mail to Phorge are:
42
42
43
43
| Receive Mail With | Setup | Cost | Notes |
44
44
|--------|-------|------|-------|
···
47
47
| SendGrid | Easy | Cheap | |
48
48
| Local MTA | Difficult | Free | Discouraged |
49
49
50
-
The remainder of this document walks through configuring Phabricator to
50
+
The remainder of this document walks through configuring Phorge to
51
51
receive mail, and then configuring your chosen transport to deliver mail
52
-
to Phabricator.
52
+
to Phorge.
53
53
54
54
55
55
Configuring "Reply" Email
56
56
=========================
57
57
58
-
By default, Phabricator uses a `noreply@phabricator.example.com` email address
58
+
By default, Phorge uses a `noreply@phorge.example.com` email address
59
59
as the "From" address when it sends mail. The exact address it uses can be
60
60
configured with `metamta.default-address`.
61
61
62
-
When a user takes an action that generates mail, Phabricator sets the
62
+
When a user takes an action that generates mail, Phorge sets the
63
63
"Reply-To" addresss for the mail to that user's name and address. This means
64
64
that users can reply to email to discuss changes, but: the conversation won't
65
-
be recorded in Phabricator; and users will not be able to use email commands
65
+
be recorded in Phorge; and users will not be able to use email commands
66
66
to take actions or make edits.
67
67
68
-
To change this behavior so that users can interact with objects in Phabricator
68
+
To change this behavior so that users can interact with objects in Phorge
69
69
over email, change the configuration key `metamta.reply-handler-domain` to some
70
70
domain you configure according to the instructions below, e.g.
71
-
`phabricator.example.com`. Once you set this key, email will use a
72
-
"Reply-To" like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
71
+
`phorge.example.com`. Once you set this key, email will use a
72
+
"Reply-To" like `T123+273+af310f9220ad@phorge.example.com`, which -- when
73
73
configured correctly, according to the instructions below -- will parse incoming
74
74
email and allow users to interact with Differential revisions, Maniphest tasks,
75
75
etc. over email.
76
76
77
-
If you don't want Phabricator to take up an entire domain (or subdomain) you
77
+
If you don't want Phorge to take up an entire domain (or subdomain) you
78
78
can configure a general prefix so you can use a single mailbox to receive mail
79
79
on. To make use of this set `metamta.single-reply-handler-prefix` to the
80
-
prefix of your choice, and Phabricator will prepend this to the "Reply-To"
80
+
prefix of your choice, and Phorge will prepend this to the "Reply-To"
81
81
mail address. This works because everything up to the first (optional) '+'
82
82
character in an email address is considered the receiver, and everything
83
83
after is essentially ignored.
···
87
87
==========================
88
88
89
89
You can set up application email addresses to allow users to create objects via
90
-
email. For example, you could configure `bugs@phabricator.example.com` to
90
+
email. For example, you could configure `bugs@phorge.example.com` to
91
91
create a Maniphest task out of any email which is sent to it.
92
92
93
93
You can find application email settings for each application at:
···
104
104
route or handle objects based on which address mail was sent to.
105
105
106
106
You'll also need to configure the actual mail domain to submit mail to
107
-
Phabricator by following the instructions below. Phabricator will let you add
107
+
Phorge by following the instructions below. Phorge will let you add
108
108
any address as an application address, but can only process mail which is
109
109
actually delivered to it.
110
110
···
130
130
project and need to interact with users whose email accounts you have no control
131
131
over).
132
132
133
-
You can also set `metamta.public-replies`, which will change how Phabricator
133
+
You can also set `metamta.public-replies`, which will change how Phorge
134
134
delivers email. Instead of sending each recipient a unique mail with a personal
135
135
reply-to address, it will send a single email to everyone with a public reply-to
136
136
address. This decreases security because anyone who can spoof a "From" address
···
142
142
If you enable application email addresses, those addresses also use the weaker
143
143
"From" authentication mechanism.
144
144
145
-
NOTE: Phabricator does not currently attempt to verify "From" addresses because
145
+
NOTE: Phorge does not currently attempt to verify "From" addresses because
146
146
this is technically complex, seems unreasonably difficult in the general case,
147
147
and no installs have had a need for it yet. If you have a specific case where a
148
148
reasonable mechanism exists to provide sender verification (e.g., DKIM
···
155
155
===================================
156
156
157
157
You can use the `bin/mail` utility to test and review inbound mail. This can
158
-
help you determine if mail is being delivered to Phabricator or not:
158
+
help you determine if mail is being delivered to Phorge or not:
159
159
160
-
phabricator/ $ ./bin/mail list-inbound # List inbound messages.
161
-
phabricator/ $ ./bin/mail show-inbound # Show details about a message.
160
+
phorge/ $ ./bin/mail list-inbound # List inbound messages.
161
+
phorge/ $ ./bin/mail show-inbound # Show details about a message.
162
162
163
163
You can also test receiving mail, but note that this just simulates receiving
164
164
the mail and doesn't send any information over the network. It is
165
165
primarily aimed at developing email handlers: it will still work properly
166
166
if your inbound email configuration is incorrect or even disabled.
167
167
168
-
phabricator/ $ ./bin/mail receive-test # Receive test message.
168
+
phorge/ $ ./bin/mail receive-test # Receive test message.
169
169
170
170
Run `bin/mail help <command>` for detailed help on using these commands.
171
171
···
179
179
180
180
- Configure a mail domain according to Mailgun's instructions.
181
181
- Add a Mailgun route with a `catch_all()` rule which takes the action
182
-
`forward("https://phabricator.example.com/mail/mailgun/")`. Replace the
182
+
`forward("https://phorge.example.com/mail/mailgun/")`. Replace the
183
183
example domain with your actual domain.
184
184
- Configure a mailer in `cluster.mailers` with your Mailgun API key.
185
185
···
191
191
webhook URI in the Postmark control panel:
192
192
193
193
```
194
-
https://<phabricator.yourdomain.com>/mail/postmark/
194
+
https://<phorge.yourdomain.com>/mail/postmark/
195
195
```
196
196
197
197
See also the Postmark section in @{article:Configuring Outbound Email} for
···
206
206
inbound email. Provided you have such an account, configure it like this:
207
207
208
208
- Configure an MX record according to SendGrid's instructions, i.e. add
209
-
`phabricator.example.com MX 10 mx.sendgrid.net.` or similar.
209
+
`phorge.example.com MX 10 mx.sendgrid.net.` or similar.
210
210
- Go to the "Parse Incoming Emails" page on SendGrid
211
211
(<http://sendgrid.com/developer/reply>) and add the domain as the
212
212
"Hostname".
213
-
- Add the URL `https://phabricator.example.com/mail/sendgrid/` as the "Url",
213
+
- Add the URL `https://phorge.example.com/mail/sendgrid/` as the "Url",
214
214
using your domain (and HTTP instead of HTTPS if you are not configured with
215
215
SSL).
216
216
- If you get an error that the hostname "can't be located or verified", it
217
217
means your MX record is either incorrectly configured or hasn't propagated
218
218
yet.
219
-
- Set `metamta.reply-handler-domain` to `phabricator.example.com`
219
+
- Set `metamta.reply-handler-domain` to `phorge.example.com`
220
220
(whatever you configured the MX record for).
221
221
222
222
That's it! If everything is working properly you should be able to send email
223
-
to `anything@phabricator.example.com` and it should appear in
223
+
to `anything@phorge.example.com` and it should appear in
224
224
`bin/mail list-inbound` within a few seconds.
225
225
226
226
···
264
264
- add your host to /etc/mail/local-host-names; and
265
265
- restart sendmail.
266
266
267
-
Now, you can actually configure sendmail to deliver to Phabricator. In
267
+
Now, you can actually configure sendmail to deliver to Phorge. In
268
268
`/etc/aliases`, add an entry like this:
269
269
270
-
phabricator: "| /path/to/phabricator/scripts/mail/mail_handler.php"
270
+
phorge: "| /path/to/phorge/scripts/mail/mail_handler.php"
271
271
272
272
If you use the `PHABRICATOR_ENV` environmental variable to select a
273
273
configuration, you can pass the value to the script as an argument:
···
280
280
After making this change, run `sudo newaliases`. Now you likely need to symlink
281
281
this script into `/etc/smrsh/`:
282
282
283
-
sudo ln -s /path/to/phabricator/scripts/mail/mail_handler.php /etc/smrsh/
283
+
sudo ln -s /path/to/phorge/scripts/mail/mail_handler.php /etc/smrsh/
284
284
285
285
Finally, edit `/etc/mail/virtusertable` and add an entry like this:
286
286
287
-
@yourdomain.com phabricator@localhost
287
+
@yourdomain.com phorge@localhost
288
288
289
-
That will forward all mail to @yourdomain.com to the Phabricator processing
289
+
That will forward all mail to @yourdomain.com to the Phorge processing
290
290
script. Run `sudo /etc/mail/make` or similar and then restart sendmail with
291
291
`sudo /etc/init.d/sendmail restart`.
+25
-25
src/docs/user/configuration/configuring_outbound_email.diviner
+25
-25
src/docs/user/configuration/configuring_outbound_email.diviner
···
1
1
@title Configuring Outbound Email
2
2
@group config
3
3
4
-
Instructions for configuring Phabricator to send email and other types of
4
+
Instructions for configuring Phorge to send email and other types of
5
5
messages, like text messages.
6
6
7
7
Overview
8
8
========
9
9
10
-
Phabricator sends outbound messages through "mailers". Most mailers send
10
+
Phorge sends outbound messages through "mailers". Most mailers send
11
11
email and most messages are email messages, but mailers may also send other
12
12
types of messages (like text messages).
13
13
14
-
Phabricator can send outbound messages through multiple different mailers,
14
+
Phorge can send outbound messages through multiple different mailers,
15
15
including a local mailer or various third-party services. Options include:
16
16
17
17
| Send Mail With | Setup | Cost | Inbound | Media | Notes |
···
41
41
If you have some internal mail or messaging service you'd like to use you can
42
42
also write a custom mailer, but this requires digging into the code.
43
43
44
-
Phabricator sends mail in the background, so the daemons need to be running for
44
+
Phorge sends mail in the background, so the daemons need to be running for
45
45
it to be able to deliver mail. You should receive setup warnings if they are
46
46
not. For more information on using daemons, see
47
47
@{article:Managing Daemons with phd}.
···
50
50
Outbound "From" and "To" Addresses
51
51
==================================
52
52
53
-
When Phabricator sends outbound mail, it must select some "From" address to
53
+
When Phorge sends outbound mail, it must select some "From" address to
54
54
send mail from, since mailers require this.
55
55
56
-
When mail only has "CC" recipients, Phabricator generates a dummy "To" address,
56
+
When mail only has "CC" recipients, Phorge generates a dummy "To" address,
57
57
since some mailers require this and some users write mail rules that depend
58
58
on whether they appear in the "To" or "CC" line.
59
59
···
65
65
of mail they probably don't want.
66
66
67
67
If you plan to configure //inbound// mail later, you usually don't need to do
68
-
anything. Phabricator will automatically create a `noreply@` mailbox which
68
+
anything. Phorge will automatically create a `noreply@` mailbox which
69
69
works the right way (accepts and discards all mail it receives) and
70
70
automatically use it when generating addresses.
71
71
72
72
If you don't plan to configure inbound mail, you may need to configure an
73
-
address for Phabricator to use. You can do this by setting
73
+
address for Phorge to use. You can do this by setting
74
74
`metamta.default-address`.
75
75
76
76
···
131
131
- `smtp`: Connect directly to an SMTP server.
132
132
- `test`: Internal mailer for testing. Does not send mail.
133
133
134
-
You can also write your own mailer by extending `PhabricatorMailAdapter`.
134
+
You can also write your own mailer by extending `PhorgeMailAdapter`.
135
135
136
136
The `media` field supports these values:
137
137
···
169
169
Then set the value like this:
170
170
171
171
```
172
-
phabricator/ $ ./bin/config set --stdin cluster.mailers < mailers.json
172
+
phorge/ $ ./bin/config set --stdin cluster.mailers < mailers.json
173
173
```
174
174
175
175
For alternatives and more information on configuration, see
···
310
310
<https://sendgrid.com/>.
311
311
312
312
You can configure SendGrid in two ways: you can send via SMTP or via the REST
313
-
API. To use SMTP, configure Phabricator to use an `smtp` mailer.
313
+
API. To use SMTP, configure Phorge to use an `smtp` mailer.
314
314
315
315
To use the REST API mailer, set `type` to `sendgrid`, then configure
316
316
these `options`:
···
343
343
344
344
To use this mailer, set `type` to `sendmail`, then configure these `options`:
345
345
346
-
- `message-id`: Optional bool. Set to `false` if Phabricator will not be
346
+
- `message-id`: Optional bool. Set to `false` if Phorge will not be
347
347
able to select a custom "Message-ID" header when sending mail via this
348
348
mailer. See "Message-ID Headers" below.
349
349
···
365
365
- `password`: Optional string. Password for authentication.
366
366
- `protocol`: Optional string. Set to `tls` or `ssl` if necessary. Use
367
367
`ssl` for Gmail.
368
-
- `message-id`: Optional bool. Set to `false` if Phabricator will not be
368
+
- `message-id`: Optional bool. Set to `false` if Phorge will not be
369
369
able to select a custom "Message-ID" header when sending mail via this
370
370
mailer. See "Message-ID Headers" below.
371
371
···
390
390
You can use the `bin/mail` utility to test, debug, and examine outbound mail. In
391
391
particular:
392
392
393
-
phabricator/ $ ./bin/mail list-outbound # List outbound mail.
394
-
phabricator/ $ ./bin/mail show-outbound # Show details about messages.
395
-
phabricator/ $ ./bin/mail send-test # Send test messages.
393
+
phorge/ $ ./bin/mail list-outbound # List outbound mail.
394
+
phorge/ $ ./bin/mail show-outbound # Show details about messages.
395
+
phorge/ $ ./bin/mail send-test # Send test messages.
396
396
397
397
Run `bin/mail help <command>` for more help on using these commands.
398
398
···
406
406
Priorities
407
407
==========
408
408
409
-
By default, Phabricator will try each mailer in order: it will try the first
409
+
By default, Phorge will try each mailer in order: it will try the first
410
410
mailer first. If that fails (for example, because the service is not available
411
411
at the moment) it will try the second mailer, and so on.
412
412
413
413
If you want to load balance between multiple mailers instead of using one as
414
-
a primary, you can set `priority`. Phabricator will start with mailers in the
414
+
a primary, you can set `priority`. Phorge will start with mailers in the
415
415
highest priority group and go through them randomly, then fall back to the
416
416
next group.
417
417
···
441
441
}
442
442
```
443
443
444
-
Phabricator will start with servers in the highest priority group (the group
444
+
Phorge will start with servers in the highest priority group (the group
445
445
with the **largest** `priority` number). In this example, the highest group is
446
446
`300`, which has the two SMTP servers. They'll be tried in random order first.
447
447
448
-
If both fail, Phabricator will move on to the next priority group. In this
448
+
If both fail, Phorge will move on to the next priority group. In this
449
449
example, there are no other priority groups.
450
450
451
-
If it still hasn't sent the mail, Phabricator will try servers which are not
451
+
If it still hasn't sent the mail, Phorge will try servers which are not
452
452
in any priority group, in the configured order. In this example there is
453
453
only one such server, so it will try to send via Mailgun.
454
454
···
457
457
==================
458
458
459
459
Email has a "Message-ID" header which is important for threading messages
460
-
correctly in mail clients. Normally, Phabricator is free to select its own
460
+
correctly in mail clients. Normally, Phorge is free to select its own
461
461
"Message-ID" header values for mail it sends.
462
462
463
463
However, some mailers (including Amazon SES) do not allow selection of custom
464
464
"Message-ID" values and will ignore or replace the "Message-ID" in mail that
465
465
is submitted through them.
466
466
467
-
When Phabricator adds other mail headers which affect threading, like
467
+
When Phorge adds other mail headers which affect threading, like
468
468
"In-Reply-To", it needs to know if its "Message-ID" headers will be respected
469
469
or not to select header values which will produce good threading behavior. If
470
470
we guess wrong and think we can set a "Message-ID" header when we can't, you
···
493
493
494
494
If the outbound pathway does not actually allow selection of a "Message-ID"
495
495
header, you can set the `message-id` option on the mailer to `false` to tell
496
-
Phabricator that it should not assume it can select a value for this header.
496
+
Phorge that it should not assume it can select a value for this header.
497
497
498
498
For example, if you are sending mail via a local Postfix server which then
499
499
forwards the mail to Amazon SES (a service which does not allow selection of
500
-
a "Message-ID" header), your `smtp` configuration in Phabricator should
500
+
a "Message-ID" header), your `smtp` configuration in Phorge should
501
501
specify `"message-id": false`.
502
502
503
503
+11
-11
src/docs/user/configuration/configuring_preamble.diviner
+11
-11
src/docs/user/configuration/configuring_preamble.diviner
···
6
6
Overview
7
7
========
8
8
9
-
If Phabricator is deployed in an environment where HTTP headers behave oddly
9
+
If Phorge is deployed in an environment where HTTP headers behave oddly
10
10
(usually, because it is behind a load balancer), it may not be able to detect
11
11
some environmental features (like the client's IP, or the presence of SSL)
12
12
correctly.
13
13
14
14
You can use a special preamble script to make arbitrary adjustments to the
15
-
environment and some parts of Phabricator's configuration in order to fix these
16
-
problems and set up the environment which Phabricator expects.
15
+
environment and some parts of Phorge's configuration in order to fix these
16
+
problems and set up the environment which Phorge expects.
17
17
18
18
19
19
Creating a Preamble Script
···
21
21
22
22
To create a preamble script, write a file to:
23
23
24
-
phabricator/support/preamble.php
24
+
phorge/support/preamble.php
25
25
26
-
(This file is in Phabricator's `.gitignore`, so you do not need to worry about
26
+
(This file is in Phorge's `.gitignore`, so you do not need to worry about
27
27
colliding with `git` or interacting with updates.)
28
28
29
29
This file should be a valid PHP script. If you aren't very familiar with PHP,
30
30
you can check for syntax errors with `php -l`:
31
31
32
-
phabricator/ $ php -l support/preamble.php
32
+
phorge/ $ php -l support/preamble.php
33
33
No syntax errors detected in support/preamble.php
34
34
35
35
If present, this script will be executed at the very beginning of each web
···
40
40
Adjusting Client IPs
41
41
====================
42
42
43
-
If your install is behind a load balancer, Phabricator may incorrectly detect
43
+
If your install is behind a load balancer, Phorge may incorrectly detect
44
44
all requests as originating from the load balancer, rather than from the
45
45
correct client IPs.
46
46
47
47
In common cases where networks are configured like this, the `X-Forwarded-For`
48
48
header will have trustworthy information about the real client IP. You
49
49
can use the function `preamble_trust_x_forwarded_for_header()` in your
50
-
preamble to tell Phabricator that you expect to receive requests from a
50
+
preamble to tell Phorge that you expect to receive requests from a
51
51
load balancer or proxy which modifies this header:
52
52
53
53
```name="Trust X-Forwarded-For Header", lang=php
···
89
89
Adjusting SSL
90
90
=============
91
91
92
-
If your install is behind an SSL terminating load balancer, Phabricator may
92
+
If your install is behind an SSL terminating load balancer, Phorge may
93
93
detect requests as HTTP when the client sees them as HTTPS. This can cause
94
-
Phabricator to generate links with the wrong protocol, issue cookies without
94
+
Phorge to generate links with the wrong protocol, issue cookies without
95
95
the SSL-only flag, or reject requests outright.
96
96
97
97
To fix this, you can set `$_SERVER['HTTPS']` explicitly:
···
103
103
$_SERVER['HTTPS'] = true;
104
104
```
105
105
106
-
You can also set this value to `false` to explicitly tell Phabricator that a
106
+
You can also set this value to `false` to explicitly tell Phorge that a
107
107
request is not an SSL request.
108
108
109
109
+7
-7
src/docs/user/configuration/custom_fields.diviner
+7
-7
src/docs/user/configuration/custom_fields.diviner
···
5
5
6
6
= Overview =
7
7
8
-
Several Phabricator applications allow the configuration of custom fields. These
8
+
Several Phorge applications allow the configuration of custom fields. These
9
9
fields allow you to add more information to objects, and in some cases reorder
10
10
or remove builtin fields.
11
11
···
134
134
- **search.default** Text for the search interface, defaults to "(Any)".
135
135
- **search.require** Text for the search interface, defaults to "Require".
136
136
137
-
Internally, Phabricator implements some additional custom field types and
137
+
Internally, Phorge implements some additional custom field types and
138
138
options. These are not intended for general use and are subject to abrupt
139
139
change, but are documented here for completeness:
140
140
···
149
149
150
150
If you want custom fields to have advanced behaviors (sophisticated rendering,
151
151
advanced validation, complicated controls, interaction with other systems, etc),
152
-
you can write a custom field as an extension and add it to Phabricator.
152
+
you can write a custom field as an extension and add it to Phorge.
153
153
154
154
NOTE: This API is somewhat new and fairly large. You should expect that there
155
155
will be occasional changes to the API requiring minor updates in your code.
···
167
167
| Projects | @{class:PhabricatorProjectCustomField} |
168
168
169
169
The easiest way to get started is to drop your subclass into
170
-
`phabricator/src/extensions/`. If Phabricator is configured in development
170
+
`phorge/src/extensions/`. If Phorge is configured in development
171
171
mode, the class should immediately be available in the UI. If not, you can
172
-
restart Phabricator (for help, see @{article:Restarting Phabricator}).
172
+
restart Phorge (for help, see @{article:Restarting Phorge}).
173
173
174
174
For example, this is a simple template which adds a custom field to Maniphest:
175
175
···
211
211
212
212
Continue by:
213
213
214
-
- learning more about extending Phabricator with custom code in
215
-
@{article@phabcontrib:Adding New Classes};
214
+
- learning more about extending Phorge with custom code in
215
+
@{article@contrib:Adding New Classes};
216
216
- or returning to the @{article: Configuration Guide}.
+8
-8
src/docs/user/configuration/managing_caches.diviner
+8
-8
src/docs/user/configuration/managing_caches.diviner
···
1
1
@title Managing Caches
2
2
@group config
3
3
4
-
Discusses Phabricator caches and cache management.
4
+
Discusses Phorge caches and cache management.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator uses various caches to improve performance, similar to the caches
9
+
Phorge uses various caches to improve performance, similar to the caches
10
10
a web browser uses to improve web performance.
11
11
12
12
In particular, blocks of text which are expensive to render (like formatted
13
13
text and syntax highlighted code) are often cached after they're rendered for
14
-
the first time. When they're rendered again, Phabricator can read the cache
14
+
the first time. When they're rendered again, Phorge can read the cache
15
15
instead of recomputing the result.
16
16
17
17
Because text is cached, you may continue to see the old result even after you
···
28
28
eventually (usually within 30 days).
29
29
30
30
If you don't want to wait, you can purge the caches. This will remove any
31
-
cached data and force Phabricator to recompute the results.
31
+
cached data and force Phorge to recompute the results.
32
32
33
33
Purging Caches
34
34
==============
35
35
36
-
If you need to purge Phabricator's caches, you can use the CLI tool. Run it
36
+
If you need to purge Phorge's caches, you can use the CLI tool. Run it
37
37
with the `--help` flag to see options:
38
38
39
-
phabricator/ $ ./bin/cache purge --help
39
+
phorge/ $ ./bin/cache purge --help
40
40
41
41
This tool can purge caches in a granular way, but it's normally easiest to
42
42
just purge all of the caches:
43
43
44
-
phabricator/ $ ./bin/cache purge --all
44
+
phorge/ $ ./bin/cache purge --all
45
45
46
46
You can purge caches safely. The data they contain can always be rebuilt from
47
-
other data if Phabricator needs it.
47
+
other data if Phorge needs it.
+12
-12
src/docs/user/configuration/managing_daemons.diviner
+12
-12
src/docs/user/configuration/managing_daemons.diviner
···
1
1
@title Managing Daemons with phd
2
2
@group config
3
3
4
-
Explains Phabricator daemons and the daemon control program `phd`.
4
+
Explains Phorge daemons and the daemon control program `phd`.
5
5
6
6
= Overview =
7
7
8
-
Phabricator uses daemons (background processing scripts) to handle a number of
8
+
Phorge uses daemons (background processing scripts) to handle a number of
9
9
tasks:
10
10
11
11
- tracking repositories, discovering new commits, and importing and parsing
···
16
16
Daemons are started and stopped with **phd** (the **Ph**abricator **D**aemon
17
17
launcher). Daemons can be monitored via a web console.
18
18
19
-
You do not need to run daemons for most parts of Phabricator to work, but some
19
+
You do not need to run daemons for most parts of Phorge to work, but some
20
20
features (principally, repository tracking with Diffusion) require them and
21
21
several features will benefit in performance or stability if you configure
22
22
daemons.
23
23
24
24
= phd =
25
25
26
-
**phd** is a command-line script (located at `phabricator/bin/phd`). To get
26
+
**phd** is a command-line script (located at `phorge/bin/phd`). To get
27
27
a list of commands, run `phd help`:
28
28
29
-
phabricator/ $ ./bin/phd help
29
+
phorge/ $ ./bin/phd help
30
30
NAME
31
-
phd - phabricator daemon launcher
31
+
phd - phorge daemon launcher
32
32
...
33
33
34
34
Generally, you will use:
···
43
43
- **phd launch** to launch individual daemons; and
44
44
- **phd debug** to debug problems with daemons.
45
45
46
-
NOTE: When you upgrade Phabricator or change configuration, you should restart
46
+
NOTE: When you upgrade Phorge or change configuration, you should restart
47
47
the daemons by running `phd restart`.
48
48
49
49
= Daemon Console =
···
81
81
82
82
To debug a daemon, use `phd debug`:
83
83
84
-
phabricator/bin/ $ ./phd debug <daemon>
84
+
phorge/bin/ $ ./phd debug <daemon>
85
85
86
86
You can pass arguments like this (normal arguments are passed to the daemon
87
87
control mechanism, not to the daemon itself):
88
88
89
-
phabricator/bin/ $ ./phd debug <daemon> -- --flavor apple
89
+
phorge/bin/ $ ./phd debug <daemon> -- --flavor apple
90
90
91
91
In debug mode, daemons do not daemonize, and they print additional debugging
92
92
output to the console. This should make it easier to debug problems. You can
···
94
94
95
95
To launch a nonstandard daemon, use `phd launch`:
96
96
97
-
phabricator/bin/ $ ./phd launch <daemon>
97
+
phorge/bin/ $ ./phd launch <daemon>
98
98
99
99
This daemon will daemonize and run normally.
100
100
···
109
109
just those started with `phd start`. If you're writing a restart script,
110
110
have it launch any custom daemons explicitly after `phd restart`.
111
111
- You can write your own daemons and manage them with `phd` by extending
112
-
@{class:PhabricatorDaemon}. See @{article@phabcontrib:Adding New Classes}.
112
+
@{class:PhabricatorDaemon}. See @{article@contrib:Adding New Classes}.
113
113
- See @{article:Diffusion User Guide} for details about tuning the repository
114
114
daemon.
115
115
···
128
128
129
129
- learning about the repository daemon with @{article:Diffusion User Guide};
130
130
or
131
-
- writing your own daemons with @{article@phabcontrib:Adding New Classes}.
131
+
- writing your own daemons with @{article@contrib:Adding New Classes}.
+3
-3
src/docs/user/configuration/managing_garbage.diviner
+3
-3
src/docs/user/configuration/managing_garbage.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator generates various logs and caches during normal operation. Some of
9
+
Phorge generates various logs and caches during normal operation. Some of
10
10
these logs and caches are usually of very little use after some time has
11
11
passed, so they are deleted automatically (often after a month or two) in a
12
12
process called "garbage collection".
···
35
35
`bin/garbage set-policy` to select a new policy:
36
36
37
37
```
38
-
phabricator/ $ ./bin/garbage set-policy --collector cache.markup --days 7
38
+
phorge/ $ ./bin/garbage set-policy --collector cache.markup --days 7
39
39
```
40
40
41
41
You can use `--days` to select how long data is retained for. You can also use
···
53
53
You can manually run a collector with `bin/garbage collect`.
54
54
55
55
```
56
-
phabricator/ $ ./bin/garbage collect --collector cache.general
56
+
phorge/ $ ./bin/garbage collect --collector cache.general
57
57
```
58
58
59
59
By using the `--trace` flag, you can inspect the operation of the collector
+20
-20
src/docs/user/configuration/notifications.diviner
+20
-20
src/docs/user/configuration/notifications.diviner
···
6
6
Overview
7
7
========
8
8
9
-
By default, Phabricator delivers information about events (like users creating
9
+
By default, Phorge delivers information about events (like users creating
10
10
tasks or commenting on code reviews) through email and in-application
11
11
notifications.
12
12
13
-
Phabricator can also be configured to deliver notifications in real time, by
13
+
Phorge can also be configured to deliver notifications in real time, by
14
14
popping up a message in any open browser windows if something has happened or
15
15
an object has been updated.
16
16
···
44
44
You will also need to install the `ws` module for Node. This needs to be
45
45
installed into the notification server directory:
46
46
47
-
phabricator/ $ cd support/aphlict/server/
48
-
phabricator/support/aphlict/server/ $ npm install ws
47
+
phorge/ $ cd support/aphlict/server/
48
+
phorge/support/aphlict/server/ $ npm install ws
49
49
50
50
Once Node.js and the `ws` module are installed, you're ready to start the
51
51
server.
···
57
57
After installing Node.js, you can control the notification server with the
58
58
`bin/aphlict` command. To start the server:
59
59
60
-
phabricator/ $ bin/aphlict start
60
+
phorge/ $ bin/aphlict start
61
61
62
62
By default, the server must be able to listen on port `22280`. If you're using
63
63
a host firewall (like a security group in EC2), make sure traffic can reach the
64
64
server.
65
65
66
66
The server configuration is controlled by a configuration file, which is
67
-
separate from Phabricator's configuration settings. The default file can
68
-
be found at `phabricator/conf/aphlict/aphlict.default.json`.
67
+
separate from Phorge's configuration settings. The default file can
68
+
be found at `phorge/conf/aphlict/aphlict.default.json`.
69
69
70
70
To make adjustments to the default configuration, either copy this file to
71
71
create `aphlict.custom.json` in the same directory (this file will be used if
72
72
it exists) or specify a configuration file explicitly with the `--config` flag:
73
73
74
-
phabricator/ $ bin/aphlict start --config path/to/config.json
74
+
phorge/ $ bin/aphlict start --config path/to/config.json
75
75
76
76
The configuration file has these settings:
77
77
···
118
118
The defaults are appropriate for simple cases, but you may need to adjust them
119
119
if you are running a more complex configuration.
120
120
121
-
Configuring Phabricator
121
+
Configuring Phorge
122
122
=======================
123
123
124
-
After starting the server, configure Phabricator to connect to it by adjusting
124
+
After starting the server, configure Phorge to connect to it by adjusting
125
125
`notification.servers`. This configuration option should have a list of servers
126
-
that Phabricator should interact with.
126
+
that Phorge should interact with.
127
127
128
128
Normally, you'll list one client server and one admin server, like this:
129
129
···
131
131
[
132
132
{
133
133
"type": "client",
134
-
"host": "phabricator.mycompany.com",
134
+
"host": "phorge.mycompany.com",
135
135
"port": 22280,
136
136
"protocol": "https"
137
137
},
···
165
165
166
166
You can run `aphlict` in the foreground to get output to your console:
167
167
168
-
phabricator/ $ ./bin/aphlict debug
168
+
phorge/ $ ./bin/aphlict debug
169
169
170
170
Because the notification server uses WebSockets, your browser error console
171
171
may also have information that is useful in figuring out what's wrong.
···
178
178
SSL and HTTPS
179
179
=============
180
180
181
-
If you serve Phabricator over HTTPS, you must also serve websockets over HTTPS.
181
+
If you serve Phorge over HTTPS, you must also serve websockets over HTTPS.
182
182
Browsers will refuse to connect to `ws://` websockets from HTTPS pages.
183
183
184
-
If a client connects to Phabricator over HTTPS, Phabricator will automatically
184
+
If a client connects to Phorge over HTTPS, Phorge will automatically
185
185
select an appropriate HTTPS service from `notification.servers` and instruct
186
186
the browser to open a websocket connection with `wss://`.
187
187
···
241
241
}
242
242
```
243
243
244
-
```lang=nginx, name=/etc/nginx/sites-enabled/phabricator.example.com.conf
244
+
```lang=nginx, name=/etc/nginx/sites-enabled/phorge.example.com.conf
245
245
server {
246
-
server_name phabricator.example.com;
247
-
root /path/to/phabricator/webroot;
246
+
server_name phorge.example.com;
247
+
root /path/to/phorge/webroot;
248
248
249
249
// ...
250
250
···
260
260
261
261
With this approach, you should make these additional adjustments:
262
262
263
-
**Phabricator Configuration**: The entry in `notification.servers` with type
263
+
**Phorge Configuration**: The entry in `notification.servers` with type
264
264
`"client"` should have these adjustments made:
265
265
266
-
- Set `host` to the Phabricator host.
266
+
- Set `host` to the Phorge host.
267
267
- Set `port` to the standard HTTPS port (usually `443`).
268
268
- Set `protocol` to `"https"`.
269
269
- Set `path` to `/ws/`, so it matches the special `location` in your
+15
-15
src/docs/user/configuration/storage_adjust.diviner
+15
-15
src/docs/user/configuration/storage_adjust.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator uses a workflow called //storage adjustment// to make some minor
9
+
Phorge uses a workflow called //storage adjustment// to make some minor
10
10
kinds of changes to the MySQL schema. This workflow compliments the //storage
11
11
upgrade// workflow, which makes major changes.
12
12
13
13
You can perform storage adjustment by running:
14
14
15
-
phabricator/ $ ./bin/storage adjust
15
+
phorge/ $ ./bin/storage adjust
16
16
17
17
This document describes what adjustments are, how they relate to storage
18
18
upgrades, how to perform them, and how to troubleshoot issues with storage
···
22
22
Understanding Adjustments
23
23
===================
24
24
25
-
Storage adjustments make minor changes to the Phabricator MySQL schemata to
25
+
Storage adjustments make minor changes to the Phorge MySQL schemata to
26
26
improve consistency, unicode handling, and performance. Changes covered by
27
27
adjustment include:
28
28
···
62
62
63
63
You can also review adjustments from the CLI, by running:
64
64
65
-
phabricator/ $ ./bin/storage adjust
65
+
phorge/ $ ./bin/storage adjust
66
66
67
67
Before you're prompted to actually apply adjustments, you'll be given a list of
68
68
available adjustments. You can then make a choice to apply them.
···
73
73
74
74
To perform adjustments, run the `adjust` workflow:
75
75
76
-
phabricator/ $ ./bin/storage adjust
76
+
phorge/ $ ./bin/storage adjust
77
77
78
78
For details about flags, use:
79
79
80
-
phabricator/ $ ./bin/storage help adjust
80
+
phorge/ $ ./bin/storage help adjust
81
81
82
82
You do not normally need to run this workflow manually: it will be run
83
83
automatically after you run the `upgrade` workflow.
···
97
97
98
98
The adjustment workflow allows us to alter the schema to primarily use
99
99
`binary` character sets on older MySQL, and primarily use `utf8mb4` character
100
-
sets on newer MySQL. The net effect is that Phabricator works consistently and
100
+
sets on newer MySQL. The net effect is that Phorge works consistently and
101
101
can store 4-byte unicode characters regardless of the MySQL version. Under
102
102
newer MySQL, we can also take advantage of the better collation rules the
103
103
`utf8mb4` character set offers.
···
143
143
144
144
In general, adjustments are not critical. If you run into issues applying
145
145
adjustments, it is safe to file a task in the upstream describing the problem
146
-
you've encountered and continue using Phabricator normally until the issue can
146
+
you've encountered and continue using Phorge normally until the issue can
147
147
be resolved.
148
148
149
149
Surplus Schemata
···
154
154
155
155
| Target | Error |
156
156
| --- | --- |
157
-
| phabricator_example.example_table | Surplus |
157
+
| phorge_example.example_table | Surplus |
158
158
159
-
Generally, "Surplus" means that Phabricator does not expect the table or column
159
+
Generally, "Surplus" means that Phorge does not expect the table or column
160
160
to exist. These surpluses usually exist because you (or someone else
161
161
with database access) added the table or column manually. Rarely, they can
162
162
also exist for other reasons. They are usually safe to delete, but because
163
-
deleting them destroys data and Phabricator can not be sure that the table or
163
+
deleting them destroys data and Phorge can not be sure that the table or
164
164
column doesn't have anything important in it, it does not delete them
165
165
automatically.
166
166
···
174
174
175
175
```lang=sql
176
176
CREATE DATABASE my_backups;
177
-
RENAME TABLE phabricator_example.example_table
177
+
RENAME TABLE phorge_example.example_table
178
178
TO my_backups.example_table;
179
179
```
180
180
181
-
Phabricator will ignore tables that aren't in databases it owns, so you can
182
-
safely move anything you aren't sure about outside of the Phabricator databases.
181
+
Phorge will ignore tables that aren't in databases it owns, so you can
182
+
safely move anything you aren't sure about outside of the Phorge databases.
183
183
184
184
If you're sure you don't need a table, use `DROP TABLE` to destroy it,
185
185
specifying the correct table name (the one given in the error message):
186
186
187
187
```lang=sql
188
-
DROP TABLE phabricator_example.example_table;
188
+
DROP TABLE phorge_example.example_table;
189
189
```
190
190
191
191
This will destroy the table permanently.
+4
-4
src/docs/user/configuration/troubleshooting_https.diviner
+4
-4
src/docs/user/configuration/troubleshooting_https.diviner
···
5
5
6
6
= Overview =
7
7
8
-
If you're having trouble connecting to an HTTPS install of Phabricator, and
8
+
If you're having trouble connecting to an HTTPS install of Phorge, and
9
9
particularly if you're receiving a "There was an error negotiating the SSL
10
10
connection." error, this document may be able to help you diagnose and resolve
11
11
the problem.
···
17
17
certificates).
18
18
- The SSL certificate is signed for the wrong domain. For example, a
19
19
certificate signed for `www.example.com` will not work for
20
-
`phabricator.example.com`.
20
+
`phorge.example.com`.
21
21
- The server rejects TLSv1 SNI connections for the domain (this is
22
22
complicated, see below).
23
23
···
50
50
$ openssl x509 -text -in <certificate>
51
51
52
52
If the certificate was accidentally generated for, e.g. `www.example.com` but
53
-
you installed Phabricator on `phabricator.example.com`, you need to generate a
53
+
you installed Phorge on `phorge.example.com`, you need to generate a
54
54
new certificate for the right domain.
55
55
56
56
= SNI Problems =
···
73
73
/SourceCache/OpenSSL098/OpenSSL098-44/src/ssl/s23_clnt.c:602:
74
74
75
75
...it indicates server is misconfigured. The most common cause of this problem
76
-
is an Apache server that does not explicitly name the Phabricator domain as a
76
+
is an Apache server that does not explicitly name the Phorge domain as a
77
77
valid VirtualHost.
78
78
79
79
This error occurs only for some versions of the OpenSSL client library
-7
src/docs/user/feedback.diviner
-7
src/docs/user/feedback.diviner
+1
-1
src/docs/user/field/conduit_changes.diviner
+1
-1
src/docs/user/field/conduit_changes.diviner
···
25
25
them before they stabilize.
26
26
- **Stable**: This is an established method which generally will not change.
27
27
- **Deprecated**: This method will be removed in a future version of
28
-
Phabricator and callers should cease using it.
28
+
Phorge and callers should cease using it.
29
29
30
30
Normally, a method is deprecated only when it is obsolete or a new, more
31
31
powerful method is available to replace it.
+2
-2
src/docs/user/field/darkconsole.diviner
+2
-2
src/docs/user/field/darkconsole.diviner
···
6
6
Overview
7
7
========
8
8
9
-
DarkConsole is a debugging console built into Phabricator which exposes
9
+
DarkConsole is a debugging console built into Phorge which exposes
10
10
configuration, performance and error information. It can help you detect,
11
-
understand and resolve bugs and performance problems in Phabricator
11
+
understand and resolve bugs and performance problems in Phorge
12
12
applications.
13
13
14
14
+10
-11
src/docs/user/field/exit_codes.diviner
+10
-11
src/docs/user/field/exit_codes.diviner
···
1
1
@title Command Line Exit Codes
2
2
@group fieldmanual
3
3
4
-
Explains the use of exit codes in Phabricator command line scripts.
4
+
Explains the use of exit codes in Phorge command line scripts.
5
5
6
6
Overview
7
7
========
···
21
21
The code `0` means success. Other codes signal some sort of error or status
22
22
condition, depending on the system and command.
23
23
24
-
With rare exception, Phabricator uses //all other codes// to signal
24
+
With rare exception, Phorge uses //all other codes// to signal
25
25
**catastrophic failure**.
26
26
27
27
This is an explicit architectural decision and one we are unlikely to deviate
···
35
35
operational environment. This document explains the reasoning behind our use of
36
36
exit codes in more detail.
37
37
38
-
In particular, this approach is informed by a focus on operating Phabricator
38
+
In particular, this approach is informed by a focus on operating Phorge
39
39
clusters at scale. This is not a common deployment scenario, but we consider it
40
40
the most important one. Our use of exit codes makes it easier to deploy and
41
-
operate a Phabricator cluster at larger scales. It makes it slightly harder to
41
+
operate a Phorge cluster at larger scales. It makes it slightly harder to
42
42
deploy and operate a small cluster or single host by gluing together `bash`
43
43
scripts. We are willingly trading the small scale away for advantages at larger
44
44
scales.
···
56
56
in the 1970s, particularly at scale.
57
57
58
58
We consider correctness to be very important to modern operations environments.
59
-
In particular, we manage a Phabricator cluster (Phacility) and believe that
60
-
having reliable, repeatable processes for provisioning, configuration and
61
-
deployment is critical to maintaining and scaling our operations. Our use of
62
-
exit codes makes it easier to implement processes that are correct and reliable
63
-
on top of Phabricator management scripts.
59
+
In particular, we believe that having reliable, repeatable processes for
60
+
provisioning, configuration and deployment is critical to maintaining and
61
+
scaling our operations. Our use of exit codes makes it easier to implement
62
+
processes that are correct and reliable on top of Phorge management scripts.
64
63
65
64
Exit codes as signals for application state are problematic because they are
66
65
ambiguous: you can't use them to distinguish between dissimilar failure states
···
228
227
229
228
We are broadly willing to make output machine parseable or provide an explicit
230
229
machine output mode (often a `--json` flag) if there is a reasonable use case
231
-
for it. However, we operate a large production cluster of Phabricator instances
230
+
for it. However, we operate a large production cluster of Phorge instances
232
231
with the tools available in the upstream, so the lack of machine parseable
233
232
output is not sufficient to motivate adding such output on its own: we also
234
233
need to understand the problem you're facing, and why it isn't a problem we
235
234
face. A simpler or cleaner approach to the problem may already exist.
236
235
237
-
If you just want to write `bash` scripts on top of Phabricator scripts and you
236
+
If you just want to write `bash` scripts on top of Phorge scripts and you
238
237
are unswayed by these concerns, you can often just build a composite command to
239
238
get roughly the same effect that you'd get out of an exit code.
240
239
+4
-4
src/docs/user/field/performance.diviner
+4
-4
src/docs/user/field/performance.diviner
···
23
23
============================
24
24
25
25
Performance issues and hangs will often require upstream involvement to fully
26
-
resolve. The intent is for Phabricator to perform well in all reasonable cases,
26
+
resolve. The intent is for Phorge to perform well in all reasonable cases,
27
27
not require tuning for different workloads (as long as those workloads are
28
28
generally reasonable). Poor performance with a reasonable workload is likely a
29
29
bug, not a configuration problem.
30
30
31
-
However, some pages are slow because Phabricator legitimately needs to do a lot
31
+
However, some pages are slow because Phorge legitimately needs to do a lot
32
32
of work to generate them. For example, if you write a 100MB wiki document,
33
-
Phabricator will need substantial time to process it, it will take a long time
33
+
Phorge will need substantial time to process it, it will take a long time
34
34
to download over the network, and your browser will probably not be able to
35
35
render it especially quickly.
36
36
37
-
We may be able to improve performance in some cases, but Phabricator is not
37
+
We may be able to improve performance in some cases, but Phorge is not
38
38
magic and can not wish away real complexity. The best solution to these problems
39
39
is usually to find another way to solve your problem: for example, maybe the
40
40
100MB document can be split into several smaller documents.
+7
-7
src/docs/user/field/permanently_destroying_data.diviner
+7
-7
src/docs/user/field/permanently_destroying_data.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator intentionally makes it difficult to permanently destroy data, but
9
+
Phorge intentionally makes it difficult to permanently destroy data, but
10
10
provides a command-line tool for destroying objects if you're certain that
11
11
you want to destroy something.
12
12
···
24
24
To permanently destroy an object, run this command from the command line:
25
25
26
26
```
27
-
phabricator/ $ ./bin/remove destroy <object>
27
+
phorge/ $ ./bin/remove destroy <object>
28
28
```
29
29
30
30
The `<object>` may be an object monogram or PHID. For instance, you can use
···
36
36
CLI Access Required
37
37
===================
38
38
39
-
In almost all cases, Phabricator requires operational access from the CLI to
39
+
In almost all cases, Phorge requires operational access from the CLI to
40
40
permanently destroy data. One major reason for this requirement is that it
41
41
limits the reach of an attacker who compromises a privileged account.
42
42
···
56
56
like an API key or another credential. For example, an engineer might
57
57
accidentally send a change for review which includes a sensitive private key.
58
58
59
-
No Phabricator command can rewind time, and once data is written to Phabricator
59
+
No Phorge command can rewind time, and once data is written to Phorge
60
60
the cat is often out of the bag: it has often been transmitted to external
61
-
systems which Phabricator can not interact with via email, webhooks, API calls,
61
+
systems which Phorge can not interact with via email, webhooks, API calls,
62
62
repository mirroring, CDN caching, and so on. You can try to clean up the mess,
63
63
but you're generally already too late.
64
64
···
66
66
destroy objects, but this is just an attempt. It can not unsend email or uncall
67
67
the API, and no command can rewind time and undo a leak.
68
68
69
-
**Revoking Credentials**: If Phabricator credentials were accidentally
69
+
**Revoking Credentials**: If Phorge credentials were accidentally
70
70
disclosed, you can revoke them so they no longer function. See
71
71
@{article:Revoking Credentials} for more information.
72
72
···
75
75
================
76
76
77
77
Because time can not be rewound, it is best to prevent sensitive data from
78
-
leaking in the first place. Phabricator supports some technical measures that
78
+
leaking in the first place. Phorge supports some technical measures that
79
79
can make it more difficult to accidentally disclose secrets:
80
80
81
81
**Differential Diff Herald Rules**: You can write "Differential Diff" rules
+7
-7
src/docs/user/field/repository_hints.diviner
+7
-7
src/docs/user/field/repository_hints.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Some repositories have unusual commits. You can provide "hints" to Phabricator
9
+
Some repositories have unusual commits. You can provide "hints" to Phorge
10
10
about these commits to improve behavior.
11
11
12
12
Supported hints are:
···
17
17
new pages.
18
18
- **Unreadable Commits**: If some commits are not readable (which is rare,
19
19
but can happen in some cases if they are generated with an external tool)
20
-
you can provide hints so that Phabricator doesn't try to read them.
20
+
you can provide hints so that Phorge doesn't try to read them.
21
21
22
22
The remainder of this document explains how to create and remove hints, and how
23
23
to specify each type of hint.
···
28
28
To create hints, pipe a JSON list of hints to `bin/repository hint`:
29
29
30
30
```
31
-
phabricator/ $ cat hints.json | ./bin/repository hint
31
+
phorge/ $ cat hints.json | ./bin/repository hint
32
32
```
33
33
34
34
The hints should be a list of objects like this:
···
76
76
]
77
77
```
78
78
79
-
Phabricator won't treat commits without any hint specially.
79
+
Phorge won't treat commits without any hint specially.
80
80
81
81
82
82
Hint: Rewritten Commits
···
104
104
]
105
105
```
106
106
107
-
Phabricator will show users that the commit was rewritten in the web UI.
107
+
Phorge will show users that the commit was rewritten in the web UI.
108
108
109
109
110
110
Hint: Unreadable Commits
111
111
========================
112
112
113
-
The `"unreadable"` hint allows you to tell Phabricator that it should not
113
+
The `"unreadable"` hint allows you to tell Phorge that it should not
114
114
bother trying to read the changes associated with a particular commit. In
115
115
some rare cases, repositories can contain commits which aren't readable
116
116
(for example, if they were created by external tools during an import or
···
130
130
]
131
131
```
132
132
133
-
Phabricator won't try to read, parse, import, or display the changes associated
133
+
Phorge won't try to read, parse, import, or display the changes associated
134
134
with this commit.
+13
-13
src/docs/user/field/repository_imports.diviner
+13
-13
src/docs/user/field/repository_imports.diviner
···
7
7
========
8
8
9
9
When you first import an external source code repository (or push new commits to
10
-
a hosted repository), Phabricator imports those commits in the background.
10
+
a hosted repository), Phorge imports those commits in the background.
11
11
12
12
While a repository is initially importing, some features won't work. While
13
13
individual commits are importing, some of their metadata won't be available in
···
20
20
Understanding the Import Pipeline
21
21
=================================
22
22
23
-
Phabricator first performs commit discovery on repositories. This examines
23
+
Phorge first performs commit discovery on repositories. This examines
24
24
a repository and identifies all the commits in it at a very shallow level,
25
25
then creates stub objects for them. These stub objects primarily serve to
26
26
assign various internal IDs to each commit.
···
54
54
First, to identify which commits have missing import steps, run this command:
55
55
56
56
```
57
-
phabricator/ $ ./bin/repository importing rXYZ
57
+
phorge/ $ ./bin/repository importing rXYZ
58
58
```
59
59
60
60
That will show what work remains to be done. Each line shows a commit which
···
69
69
Third, run this command to look at the daemon logs:
70
70
71
71
```
72
-
phabricator/ $ ./bin/phd log
72
+
phorge/ $ ./bin/phd log
73
73
```
74
74
75
75
This can show you any errors the daemons have encountered recently.
···
104
104
foreground:
105
105
106
106
```
107
-
phabricator/ $ ./bin/repository reparse --importing --trace rXYZabcdef012...
107
+
phorge/ $ ./bin/repository reparse --importing --trace rXYZabcdef012...
108
108
```
109
109
110
110
This command is always safe to run, no matter what the actual root cause of
111
111
the problem is.
112
112
113
113
If this fails with an error, you've likely identified a problem with
114
-
Phabricator. Collect as much information as you can about what makes the commit
114
+
Phorge. Collect as much information as you can about what makes the commit
115
115
special and file a bug in the upstream by following the instructions in
116
116
@{article:Contributing Bug Reports}.
117
117
···
132
132
133
133
In the Daemon console, temporarily failures usually look like tasks in the
134
134
"Leased Tasks" column with a large "Expires" value but a low "Failures" count
135
-
(usually 0 or 1). The "Expires" column is showing how long Phabricator is
135
+
(usually 0 or 1). The "Expires" column is showing how long Phorge is
136
136
waiting to retry these tasks.
137
137
138
138
In the daemon log, these temporary failures might have created log entries, but
···
150
150
long time will run right away:
151
151
152
152
```
153
-
phabricator/ $ ./bin/phd restart
153
+
phorge/ $ ./bin/phd restart
154
154
```
155
155
156
156
This command is always safe to run, no matter what the actual root cause of
···
172
172
extra things they shouldn't have.
173
173
174
174
There is no normal set of conditions under which this should occur, but you can
175
-
force Phabricator to re-queue the tasks to recover from it if it does occur.
175
+
force Phorge to re-queue the tasks to recover from it if it does occur.
176
176
177
177
This will look like missing steps in `repository importing`, but nothing in the
178
178
"Queued Tasks" or "Leased Tasks" sections of the daemon console. The daemon
···
182
182
up all of the missing work in `repository importing`:
183
183
184
184
```
185
-
phabricator/ $ ./bin/repository reparse --importing --all rXYZ
185
+
phorge/ $ ./bin/repository reparse --importing --all rXYZ
186
186
```
187
187
188
188
This command may cause duplicate work to occur if you have misdiagnosed the
189
189
problem and the tasks aren't actually lost. For example, it could queue a
190
-
second task to perform publishing, which could cause Phabricator to send a
190
+
second task to perform publishing, which could cause Phorge to send a
191
191
second copy of email about the commit. Other than that, it is safe to run even
192
192
if this isn't the problem.
193
193
···
215
215
command:
216
216
217
217
```
218
-
phabricator/ $ ./bin/repository mark-imported rXYZ
218
+
phorge/ $ ./bin/repository mark-imported rXYZ
219
219
```
220
220
221
221
If you do this by mistake, you can reverse it later by using the
···
231
231
you can use `help` to learn more about what it does and which flag it takes:
232
232
233
233
```
234
-
phabricator/ $ bin/repository help <command>
234
+
phorge/ $ bin/repository help <command>
235
235
```
236
236
237
237
In particular, you can use flags with the `repository reparse` command to
+3
-3
src/docs/user/field/restarting.diviner
+3
-3
src/docs/user/field/restarting.diviner
···
1
-
@title Restarting Phabricator
1
+
@title Restarting Phorge
2
2
@group fieldmanual
3
3
4
4
Instructions on how to restart HTTP and PHP servers to reload configuration
5
-
changes in Phabricator.
5
+
changes in Phorge.
6
6
7
7
8
8
Overview
9
9
========
10
10
11
-
Phabricator's setup and configuration instructions sometimes require you to
11
+
Phorge's setup and configuration instructions sometimes require you to
12
12
restart your server processes, particularly after making configuration changes.
13
13
This document explains how to restart them properly.
14
14
+8
-8
src/docs/user/field/revoking_credentials.diviner
+8
-8
src/docs/user/field/revoking_credentials.diviner
···
21
21
key compromised, you can revoke her keys like this:
22
22
23
23
```
24
-
phabricator/ $ ./bin/auth revoke --type ssh --from @alice
24
+
phorge/ $ ./bin/auth revoke --type ssh --from @alice
25
25
```
26
26
27
27
The flag `--everything` revokes all credential types.
···
41
41
To list all revokable credential types:
42
42
43
43
```
44
-
phabricator/ $ ./bin/auth revoke --list
44
+
phorge/ $ ./bin/auth revoke --list
45
45
```
46
46
47
47
To get details about exactly how a specific revoker works:
48
48
49
49
```
50
-
phabricator/ $ ./bin/auth revoke --list --type ssh
50
+
phorge/ $ ./bin/auth revoke --list --type ssh
51
51
```
52
52
53
53
···
79
79
You can revoke these credentials by running these commands:
80
80
81
81
```
82
-
phabricator/ $ ./bin/auth revoke --type password --everywhere
83
-
phabricator/ $ ./bin/auth revoke --type conduit --everywhere
84
-
phabricator/ $ ./bin/auth revoke --type session --everywhere
85
-
phabricator/ $ ./bin/auth revoke --type temporary --everywhere
82
+
phorge/ $ ./bin/auth revoke --type password --everywhere
83
+
phorge/ $ ./bin/auth revoke --type conduit --everywhere
84
+
phorge/ $ ./bin/auth revoke --type session --everywhere
85
+
phorge/ $ ./bin/auth revoke --type temporary --everywhere
86
86
```
87
87
88
88
Depending on the nature of the compromise you may also consider revoking `ssh`
···
97
97
You can revoke all credentials for a user by running this command:
98
98
99
99
```
100
-
phabricator/ $ ./bin/auth revoke --everything --from @alice
100
+
phorge/ $ ./bin/auth revoke --everything --from @alice
101
101
```
+6
-6
src/docs/user/field/worker_queue.diviner
+6
-6
src/docs/user/field/worker_queue.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator uses daemonized worker processes to execute some tasks (like
9
+
Phorge uses daemonized worker processes to execute some tasks (like
10
10
importing repositories and sending mail) in the background.
11
11
12
12
In most cases, this queue will automatically execute tasks in an appropriate
···
16
16
Reference: Priority Levels
17
17
==========================
18
18
19
-
Tasks queued by Phabricator use these default priority levels:
19
+
Tasks queued by Phorge use these default priority levels:
20
20
21
21
| Priority | Name | Tasks |
22
22
|---|---|---|
···
33
33
34
34
Any positive integer is a valid priority level, and if you adjust the priority
35
35
of tasks with `bin/worker priority` you may select any level even if
36
-
Phabricator would never naturally queue tasks at that level. For example, you
36
+
Phorge would never naturally queue tasks at that level. For example, you
37
37
may adjust tasks to priority `5678`, which will make them execute after all
38
38
other types of natural tasks.
39
39
···
48
48
behavior of the worker queue is when importing a very large repository like
49
49
the Linux kernel.
50
50
51
-
Although Phabricator will automatically process imports of new repositories at
51
+
Although Phorge will automatically process imports of new repositories at
52
52
a lower priority level than all other non-import tasks, you may still run into
53
53
issues like these:
54
54
···
63
63
new repositories), you can run a command like this:
64
64
65
65
```
66
-
phabricator/ $ ./bin/worker priority --priority 5000 --container R123
66
+
phorge/ $ ./bin/worker priority --priority 5000 --container R123
67
67
```
68
68
69
69
This means: set all tasks associated with container `R123` (in this example,
···
75
75
pause an import for 6 hours, run a command like this:
76
76
77
77
```
78
-
phabricator/ $ ./bin/worker delay --until "6 hours" --container R123
78
+
phorge/ $ ./bin/worker delay --until "6 hours" --container R123
79
79
```
80
80
81
81
The selected tasks will not execute until 6 hours from the time this command
+2
-2
src/docs/user/field/xhprof.diviner
+2
-2
src/docs/user/field/xhprof.diviner
···
7
7
========
8
8
9
9
XHProf is a profiling tool which will let you understand application
10
-
performance in Phabricator.
10
+
performance in Phorge.
11
11
12
12
After you install XHProf, you can use it from the web UI and the CLI to
13
13
generate detailed performance profiles. It is the most powerful tool available
···
60
60
From the command line, use the `--xprofile <filename>` flag to generate a
61
61
profile of any script.
62
62
63
-
You can then upload this file to Phabricator (using `arc upload` may be easiest)
63
+
You can then upload this file to Phorge (using `arc upload` may be easiest)
64
64
and view it in the web UI.
65
65
66
66
+26
-26
src/docs/user/installation_guide.diviner
+26
-26
src/docs/user/installation_guide.diviner
···
1
1
@title Installation Guide
2
2
@group intro
3
3
4
-
This document contains basic install instructions to get Phabricator up and
4
+
This document contains basic install instructions to get Phorge up and
5
5
running.
6
6
7
7
Overview
8
8
========
9
9
10
-
Phabricator is a LAMP (Linux, Apache, MySQL, PHP) application. To install
11
-
Phabricator, you will need:
10
+
Phorge is a LAMP (Linux, Apache, MySQL, PHP) application. To install
11
+
Phorge, you will need:
12
12
13
13
- a normal computer to install it on (shared hosts and unusual environments
14
14
are not supported) running some flavor of Linux or a similar OS;
15
-
- a domain name (like `phabricator.mycompany.com`);
15
+
- a domain name (like `phorge.example.com`);
16
16
- basic sysadmin skills;
17
17
- Apache, nginx, or another webserver;
18
18
- PHP, MySQL, and Git.
···
25
25
You will need **a computer**. Options include:
26
26
27
27
- **A Normal Computer**: This is strongly recommended. Many installs use a VM
28
-
in EC2. Phabricator installs properly and works well on a normal computer.
28
+
in EC2. Phorge installs properly and works well on a normal computer.
29
29
- **A Shared Host**: This may work, but is not recommended. Many shared
30
-
hosting environments have restrictions which prevent some of Phabricator's
30
+
hosting environments have restrictions which prevent some of Phorge's
31
31
features from working. Consider using a normal computer instead. We do not
32
32
support shared hosts.
33
33
- **A SAN Appliance, Network Router, Gaming Console, Raspberry Pi, etc.**:
34
-
Although you may be able to install Phabricator on specialized hardware, it
34
+
Although you may be able to install Phorge on specialized hardware, it
35
35
is unlikely to work well and will be difficult for us to support. Strongly
36
36
consider using a normal computer instead. We do not support specialized
37
37
hardware.
38
38
- **A Toaster, Car, Firearm, Thermostat, etc.**: Yes, many modern devices now
39
39
have embedded computing capability. We live in interesting times. However,
40
-
you should not install Phabricator on these devices. Instead, install it on
40
+
you should not install Phorge on these devices. Instead, install it on
41
41
a normal computer. We do not support installing on noncomputing devices.
42
42
43
-
To install the Phabricator server software, you will need an **operating
43
+
To install the Phorge server software, you will need an **operating
44
44
system** on your normal computer which is **not Windows**. Note that the
45
45
command line interface //does// work on Windows, and you can //use//
46
-
Phabricator from any operating system with a web browser. However, the server
46
+
Phorge from any operating system with a web browser. However, the server
47
47
software does not run on Windows. It does run on most other operating systems,
48
48
so choose one of these instead:
49
49
50
50
- **Linux**: Most installs use Linux.
51
51
- **Mac OS X**: Mac OS X is an acceptable flavor of Linux.
52
52
- **FreeBSD**: While FreeBSD is certainly not a flavor of Linux, it is a fine
53
-
operating system possessed of many desirable qualities, and Phabricator will
53
+
operating system possessed of many desirable qualities, and Phorge will
54
54
install and run properly on FreeBSD.
55
55
- **Solaris, etc.**: Other systems which look like Linux and quack like Linux
56
56
will generally work fine, although we may suffer a reduced ability to
···
64
64
works fine.
65
65
- **Other**: Other webservers which can run PHP are also likely to work fine,
66
66
although these installation instructions will not cover how to set them up.
67
-
- **PHP Builtin Server**: Phabricator will not work with the builtin
68
-
webserver because Phabricator depends on making requests to itself on some
67
+
- **PHP Builtin Server**: Phorge will not work with the builtin
68
+
webserver because Phorge depends on making requests to itself on some
69
69
workflows, and the builtin webserver is single-threaded.
70
70
71
71
You will also need:
···
76
76
You'll probably also need a **domain name**. In particular, you should read this
77
77
note:
78
78
79
-
NOTE: Phabricator must be installed on an entire domain. You can not install it
80
-
to a path on an existing domain, like `example.com/phabricator/`. Instead,
81
-
install it to an entire domain or subdomain, like `phabricator.example.com`.
79
+
NOTE: Phorge must be installed on an entire domain. You can not install it
80
+
to a path on an existing domain, like `example.com/phorge/`. Instead,
81
+
install it to an entire domain or subdomain, like `phorge.example.com`.
82
82
83
83
Level Requirements
84
84
==================
85
85
86
-
To install and administrate Phabricator, you'll need to be comfortable with
86
+
To install and administrate Phorge, you'll need to be comfortable with
87
87
common system administration skills. For example, you should be familiar with
88
88
using the command line, installing software on your operating system of choice,
89
89
working with the filesystem, managing processes, dealing with permissions,
···
95
95
this set of skills to troubleshoot and resolve problems, you may encounter
96
96
issues which you have substantial difficulty working through.
97
97
98
-
We assume users installing and administrating Phabricator are comfortable with
98
+
We assume users installing and administrating Phorge are comfortable with
99
99
common system administration skills and concepts. If you aren't, proceed at
100
100
your own risk and expect that your skills may be tested.
101
101
···
107
107
document for you:
108
108
109
109
- **RedHat Derivatives**:
110
-
[[ https://secure.phabricator.com/diffusion/P/browse/master/scripts/install/install_rhel-derivs.sh
110
+
[[ https://we.phorge.it/diffusion/P/browse/master/scripts/install/install_rhel-derivs.sh
111
111
| install_rhel-derivs.sh ]]
112
112
- **Ubuntu**:
113
-
[[ https://secure.phabricator.com/diffusion/P/browse/master/scripts/install/install_ubuntu.sh
113
+
[[ https://we.phorge.it/diffusion/P/browse/master/scripts/install/install_ubuntu.sh
114
114
| install_ubuntu.sh ]]
115
115
116
116
If those work for you, you can skip directly to the
···
131
131
It may also be helpful to refer to the install scripts above, even if they don't
132
132
work for your system.
133
133
134
-
Now that you have all that stuff installed, grab Phabricator and its
134
+
Now that you have all that stuff installed, grab Phorge and its
135
135
dependencies:
136
136
137
137
$ cd somewhere/ # pick some install directory
138
-
somewhere/ $ git clone https://github.com/phacility/arcanist.git
139
-
somewhere/ $ git clone https://github.com/phacility/phabricator.git
138
+
somewhere/ $ git clone https://we.phorge.it/source/arcanist.git
139
+
somewhere/ $ git clone https://we.phorge.it/source/phorge.git
140
140
141
141
Next Steps
142
142
==========
143
143
144
144
Continue by:
145
145
146
-
- configuring Phabricator with the @{article:Configuration Guide}; or
147
-
- learning how to keep Phabricator up to date with
148
-
@{article:Upgrading Phabricator}.
146
+
- configuring Phorge with the @{article:Configuration Guide}; or
147
+
- learning how to keep Phorge up to date with
148
+
@{article:Upgrading Phorge}.
+13
-12
src/docs/user/introduction.diviner
+13
-12
src/docs/user/introduction.diviner
···
1
1
@title Introduction
2
2
@group intro
3
3
4
-
This document provides a high-level overview of the Phabricator project.
4
+
This document provides a high-level overview of the Phorge project.
5
5
6
-
= What is Phabricator? =
6
+
= What is Phorge? =
7
7
8
-
**Phabricator** (pronounced like the word //fabricator//) is a suite of web
8
+
**Phorge** (pronounced like the word //forge//) is a suite of web
9
9
applications which make it easier to build software, particularly when working
10
-
with teams. Phabricator is largely based on Facebook's internal tools.
10
+
with teams. Phorge is a fork of Phabricator, which in turn is largely based on
11
+
Facebook's internal tools.
11
12
12
-
The major components of Phabricator are:
13
+
The major components of Phorge are:
13
14
14
15
- **Differential**, a code review tool; and
15
16
- **Diffusion**, a repository browser; and
16
17
- **Maniphest**, a bug tracker; and
17
18
- **Phriction**, a wiki.
18
19
19
-
Phabricator also includes a number of smaller tools.
20
+
Phorge also includes a number of smaller tools.
20
21
21
-
= Why use Phabricator? =
22
+
= Why use Phorge? =
22
23
23
-
Phabricator gives you a box of solid tools for a comparatively small setup cost.
24
+
Phorge gives you a box of solid tools for a comparatively small setup cost.
24
25
The tools all work together and are richly integrated. The whole thing is free
25
-
and open source. You own all your data. Phabricator is extremely fast and proven
26
+
and open source. You own all your data. Phorge is extremely fast and proven
26
27
to scale both to large datasets (Facebook has 500,000+ commits across many
27
28
repositories) and large organizations (Facebook has 500+ fulltime engineers).
28
-
Phabricator's tools are easy to learn, understand, and use.
29
+
Phorge's tools are easy to learn, understand, and use.
29
30
30
-
However, Phabricator may also not be a good solution for you:
31
+
However, Phorge may also not be a good solution for you:
31
32
32
33
- If you develop primarily on Windows, you are likely to find integration
33
34
with the toolsets you use lacking.
···
40
41
41
42
Continue by:
42
43
43
-
- installing Phabricator with the @{article:Installation Guide}.
44
+
- installing Phorge with the @{article:Installation Guide}.
+8
-27
src/docs/user/reporting_security.diviner
+8
-27
src/docs/user/reporting_security.diviner
···
1
1
@title Reporting Security Vulnerabilities
2
2
@group intro
3
3
4
-
Describes how to report security vulnerabilities in Phabricator.
4
+
Describes how to report security vulnerabilities in Phorge.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator runs a disclosure and award program through
10
-
[[ https://www.hackerone.com/ | HackerOne ]]. This program is the best way to
11
-
submit security issues to us, and awards responsible disclosure of
12
-
vulnerabilities with cash bounties. You can find our project page
13
-
here:
14
-
15
-
(NOTE) https://hackerone.com/phabricator
9
+
Phorge accepts bug reports on the upstream install. Please use the
10
+
[[https://we.phorge.it/maniphest/task/edit/form/1/ | security reporting form]]
11
+
to report security vulnerabilities.
16
12
17
-
The project page has detailed information about the scope of the program and
18
-
how to participate.
13
+
If you aren't sure if something qualifies, you can submit the issue as a normal
14
+
bug report. For instructions, see @{article:Contributing Bug Reports}.
19
15
20
-
We have a 24 hour response timeline, and are usually able to respond to (and,
21
-
very often, fix) issues more quickly than that.
22
-
23
-
24
-
Other Channels
25
-
==============
26
-
27
-
If you aren't sure if something qualifies or don't want to report via
28
-
HackerOne, you can submit the issue as a normal bug report. For instructions,
29
-
see @{article:Contributing Bug Reports}.
30
-
31
-
32
-
Get Updated
33
-
===========
34
-
35
-
General information about security changes is reported weekly in the
36
-
[[ https://secure.phabricator.com/w/changelog/ | Changelog ]].
16
+
General information about security changes is reported in the
17
+
[[ https://we.phorge.it/w/changelog/ | Changelog ]].
+32
-1
src/docs/user/support.diviner
+32
-1
src/docs/user/support.diviner
···
2
2
@short Support
3
3
@group intro
4
4
5
-
Effective June 1, 2021: Phabricator is no longer actively supported.
5
+
Resources for reporting bugs, requesting features, and getting support.
6
+
7
+
Overview
8
+
========
9
+
10
+
The upstream provides free support for a range of problems.
11
+
12
+
13
+
Reporting Security Vulnerabilities
14
+
==================================
15
+
16
+
The upstream accepts, fixes, and awards bounties for reports of material
17
+
security issues with the software.
18
+
19
+
To report security issues, see @{article:Reporting Security Vulnerabilities}.
20
+
21
+
22
+
Reporting Bugs
23
+
==============
24
+
25
+
The upstream will accept **reproducible** bug reports in modern, first-party
26
+
production code running in reasonable environments. Before submitting a bug
27
+
report you **must update** to the latest version of Phorge.
28
+
29
+
To report bugs, see @{article:Contributing Bug Reports}.
30
+
31
+
32
+
Contributing
33
+
============
34
+
35
+
If you'd like to contribute to Phorge, start with
36
+
@{article:Contributor Introduction}.
+31
-34
src/docs/user/upgrading.diviner
+31
-34
src/docs/user/upgrading.diviner
···
1
-
@title Upgrading Phabricator
1
+
@title Upgrading Phorge
2
2
@group intro
3
3
4
-
This document contains instructions for keeping Phabricator up to date.
4
+
This document contains instructions for keeping Phorge up to date.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator is under active development, and new features are released
9
+
Phorge is under active development, and new features are released
10
10
continuously. Staying up to date will keep your install secure.
11
11
12
12
We recommend installs upgrade regularly (every 1-2 weeks). Upgrades usually go
···
18
18
Staying On Top of Changes
19
19
=========================
20
20
21
-
We release a weekly [[https://secure.phabricator.com/w/changelog | Changelog]],
22
-
which describes changes in the previous week. You can look at the changelogs
21
+
We release a [[https://we.phorge.it/w/changelog | Changelog]],
22
+
which describes changes over time. You can look at the changelogs
23
23
for an idea of what new features are available, upcoming changes, security
24
24
information, and warnings about compatibility issues or migrations.
25
25
···
27
27
Stable Branch
28
28
=============
29
29
30
-
You can either run the `master` or `stable` branch of Phabricator. The `stable`
31
-
branch is run in the [[ https://phacility.com | Phacility Cluster ]], and lags
32
-
about a week behind `master`.
30
+
You can either run the `master` or `stable` branch of Phorge. The `stable`
31
+
branch is a little more stable than `master`, and may be helpful if you
32
+
administrate a larger install.
33
33
34
-
The `stable` branch is a little more stable than `master`, and may be helpful
35
-
if you administrate a larger install.
36
-
37
-
We promote `master` to `stable` about once a week, then publish the changelog
38
-
and deploy the cluster. During the week, major bugfixes are cherry-picked to
39
-
the `stable` branch. The changelog lists the `stable` hashes for that week,
40
-
as well as any fixes which were cherry-picked.
34
+
We promote `master` to `stable` frequently, then publish the changelog. During
35
+
the week, major bugfixes are cherry-picked to the `stable` branch. The changelog
36
+
lists the `stable` hashes for that week, as well as any fixes which were
37
+
cherry-picked.
41
38
42
39
To switch to `stable`, check the branch out in each working copy:
43
40
44
-
phabricator/ $ git checkout stable
41
+
phorge/ $ git checkout stable
45
42
arcanist/ $ git checkout stable
46
43
47
44
You can now follow the upgrade process normally.
···
50
47
Upgrade Process
51
48
===============
52
49
53
-
IMPORTANT: You **MUST** restart Phabricator after upgrading. For help, see
54
-
@{article:Restarting Phabricator}.
50
+
IMPORTANT: You **MUST** restart Phorge after upgrading. For help, see
51
+
@{article:Restarting Phorge}.
55
52
56
-
IMPORTANT: You **MUST** upgrade `arcanist` and `phabricator` at the same time.
53
+
IMPORTANT: You **MUST** upgrade `arcanist` and `phorge` at the same time.
57
54
58
-
Phabricator runs on many different systems, with many different webservers.
55
+
Phorge runs on many different systems, with many different webservers.
59
56
Given this diversity, we don't currently maintain a comprehensive upgrade
60
57
script which can work on any system. However, the general steps are the same
61
58
on every system:
62
59
63
60
- Stop the webserver (including `php-fpm`, if you use it).
64
-
- Stop the daemons, with `phabricator/bin/phd stop`.
65
-
- Run `git pull` in `arcanist/` and `phabricator/`.
66
-
- Run `phabricator/bin/storage upgrade`.
67
-
- Start the daemons, with `phabricator/bin/phd start`.
61
+
- Stop the daemons, with `phorge/bin/phd stop`.
62
+
- Run `git pull` in `arcanist/` and `phorge/`.
63
+
- Run `phorge/bin/storage upgrade`.
64
+
- Start the daemons, with `phorge/bin/phd start`.
68
65
- Restart the webserver (and `php-fpm`, if you stopped it earlier).
69
66
70
67
For some more discussion details, see @{article:Configuration Guide}.
71
68
72
-
This template script roughly outlines the steps required to upgrade Phabricator.
69
+
This template script roughly outlines the steps required to upgrade Phorge.
73
70
You'll need to adjust paths and commands a bit for your particular system:
74
71
75
72
```lang=sh
···
78
75
set -e
79
76
set -x
80
77
81
-
# This is an example script for updating Phabricator, similar to the one used to
82
-
# update <https://secure.phabricator.com/>. It might not work perfectly on your
78
+
# This is an example script for updating Phorge, similar to the one used to
79
+
# update <https://we.phorge.it/>. It might not work perfectly on your
83
80
# system, but hopefully it should be easy to adapt. This script is not intended
84
81
# to work without modifications.
85
82
86
83
# NOTE: This script assumes you are running it from a directory which contains
87
-
# arcanist/, and phabricator/.
84
+
# arcanist/, and phorge/.
88
85
89
86
ROOT=`pwd` # You can hard-code the path here instead.
90
87
91
88
### STOP WEB SERVER AND DAEMONS ###############################################
92
89
93
90
# Stop daemons.
94
-
$ROOT/phabricator/bin/phd stop
91
+
$ROOT/phorge/bin/phd stop
95
92
96
93
# If running the notification server, stop it.
97
-
# $ROOT/phabricator/bin/aphlict stop
94
+
# $ROOT/phorge/bin/aphlict stop
98
95
99
96
# Stop the webserver (apache, nginx, lighttpd, etc). This command will differ
100
97
# depending on which system and webserver you are running: replace it with an
···
108
105
cd $ROOT/arcanist
109
106
git pull
110
107
111
-
cd $ROOT/phabricator
108
+
cd $ROOT/phorge
112
109
git pull
113
110
114
111
# Upgrade the database schema. You may want to add the "--force" flag to allow
115
112
# this script to run noninteractively.
116
-
$ROOT/phabricator/bin/storage upgrade
113
+
$ROOT/phorge/bin/storage upgrade
117
114
118
115
# Restart the webserver. As above, this depends on your system and webserver.
119
116
# NOTE: If you're running php-fpm, restart it here too.
120
117
sudo /etc/init.d/httpd start
121
118
122
119
# Restart daemons.
123
-
$ROOT/phabricator/bin/phd start
120
+
$ROOT/phorge/bin/phd start
124
121
125
122
# If running the notification server, start it.
126
-
# $ROOT/phabricator/bin/aphlict start
123
+
# $ROOT/phorge/bin/aphlict start
127
124
```
+3
-3
src/docs/user/userguide/almanac.diviner
+3
-3
src/docs/user/userguide/almanac.diviner
···
11
11
use to keep track of what is running where.
12
12
13
13
Almanac is an infrastructure application that will normally be used by
14
-
administrators to configure advanced Phabricator features. In most cases,
14
+
administrators to configure advanced Phorge features. In most cases,
15
15
normal users will very rarely interact with Almanac directly.
16
16
17
17
At a very high level, Almanac can be thought of as a bit like a DNS server.
···
19
19
about which devices host those services. However, it can respond to a broader
20
20
range of queries and provide more detailed responses than DNS alone can.
21
21
22
-
Today, the primary use cases for Almanac are internal to Phabricator:
22
+
Today, the primary use cases for Almanac are internal to Phorge:
23
23
24
24
- Providing a list of build servers to Drydock so it can run build and
25
25
integration tasks.
26
-
- Configuring Phabricator to operate in a cluster setup.
26
+
- Configuring Phorge to operate in a cluster setup.
27
27
28
28
Beyond internal uses, Almanac is a general-purpose service and device inventory
29
29
application and can be used to configure and manage other types of service and
+1
-1
src/docs/user/userguide/amazon_rds.diviner
+1
-1
src/docs/user/userguide/amazon_rds.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator works with Amazon RDS. However, most of our documentation and setup
9
+
Phorge works with Amazon RDS. However, most of our documentation and setup
10
10
checks assume you are using local MySQL, and upstream support is less available
11
11
for RDS.
12
12
+4
-4
src/docs/user/userguide/arcanist.diviner
+4
-4
src/docs/user/userguide/arcanist.diviner
···
1
1
@title Arcanist User Guide
2
2
@group userguide
3
3
4
-
Guide to Arcanist, a command-line interface to Phabricator.
4
+
Guide to Arcanist, a command-line interface to Phorge.
5
5
6
-
Arcanist provides command-line access to many Phabricator tools (like
6
+
Arcanist provides command-line access to many Phorge tools (like
7
7
Differential, Files, and Paste), integrates with static analysis ("lint") and
8
8
unit tests, and manages common workflows like getting changes into Differential
9
9
for review.
···
12
12
document provides an overview of common workflows and installation.
13
13
14
14
Arcanist has technical, contributor-focused documentation here:
15
-
<https://secure.phabricator.com/book/arcanist/>
15
+
<https://we.phorge.it/book/arcanist/>
16
16
17
17
= Quick Start =
18
18
···
143
143
# User configuration is read from `~/.arcconfig`. This file is JSON, and can
144
144
be updated using `arc set-config`.
145
145
# Host configuration is read from `/etc/arcconfig` (on Windows, the path
146
-
is `C:\ProgramData\Phabricator\Arcanist\config`).
146
+
is `C:\ProgramData\Phorge\Arcanist\config`).
147
147
148
148
Arcanist uses the first definition it encounters as the runtime setting.
149
149
+3
-3
src/docs/user/userguide/arcanist_coverage.diviner
+3
-3
src/docs/user/userguide/arcanist_coverage.diviner
···
1
1
@title Arcanist User Guide: Code Coverage
2
2
@group userguide
3
3
4
-
Explains code coverage features in Arcanist and Phabricator.
4
+
Explains code coverage features in Arcanist and Phorge.
5
5
6
6
This is a configuration guide that helps you set up advanced features. If you're
7
7
just getting started, you don't need to look at this yet. Instead, start with
···
27
27
If the test engine enables coverage by default, it will be uploaded to
28
28
Differential and displayed in the right gutter when viewing diffs.
29
29
30
-
= Enabling Coverage for Arcanist and Phabricator =
30
+
= Enabling Coverage for Arcanist and Phorge =
31
31
32
-
If you're contributing, Arcanist and Phabricator support coverage if
32
+
If you're contributing, Arcanist and Phorge support coverage if
33
33
you install Xdebug:
34
34
35
35
http://xdebug.org/
+2
-2
src/docs/user/userguide/arcanist_diff.diviner
+2
-2
src/docs/user/userguide/arcanist_diff.diviner
···
14
14
= Overview =
15
15
16
16
While `arc` has a large number of commands that interface with various
17
-
Phabricator applications, the primary use of `arc` is to send changes for
17
+
Phorge applications, the primary use of `arc` is to send changes for
18
18
review in Differential (for more information on Differential, see
19
19
@{article:Differential User Guide}). If you aren't familiar with Differential,
20
20
it may be instructive to read that article first to understand the big picture
···
167
167
Differential will make a guess about a next step on accepted revisions, but it
168
168
may not be the best next step for your workflow.
169
169
170
-
Phabricator will also automatically close revisions if the changes are pushed
170
+
Phorge will also automatically close revisions if the changes are pushed
171
171
to a repository that is tracked in Diffusion. Specifically, it will close
172
172
revisions based on commit and tree hashes, and `Differential Revision`
173
173
identifiers in commit messages.
+1
-1
src/docs/user/userguide/arcanist_lint_unit.diviner
+1
-1
src/docs/user/userguide/arcanist_lint_unit.diviner
···
38
38
39
39
If you haven't created a library for the class to live in yet, you need to do
40
40
that first. Follow the instructions in
41
-
@{article@phabcontrib:Adding New Classes}, then make the library loadable by
41
+
@{article@contrib:Adding New Classes}, then make the library loadable by
42
42
adding it to your `.arcconfig` like this:
43
43
44
44
{
+7
-7
src/docs/user/userguide/arcanist_new_project.diviner
+7
-7
src/docs/user/userguide/arcanist_new_project.diviner
···
15
15
16
16
Arcanist uses `.arcconfig` files to customize a number of things about its
17
17
behavior. The first thing you're likely to want to configure is the URI
18
-
for your Phabricator install. A simple, valid file looks something like this:
18
+
for your Phorge install. A simple, valid file looks something like this:
19
19
20
20
name=.arcconfig
21
21
{
22
-
"phabricator.uri" : "https://phabricator.example.com/"
22
+
"phabricator.uri" : "https://phorge.example.com/"
23
23
}
24
24
25
25
For details on available options, see below.
···
31
31
32
32
Common options are:
33
33
34
-
- **phabricator.uri**: the URI for the Phabricator install that `arc` should
34
+
- **phabricator.uri**: the URI for the Phorge install that `arc` should
35
35
connect to when run in this project. This option was previously called
36
36
`conduit_uri`.
37
37
- **repository.callsign**: The callsign of this repository in Diffusion.
···
47
47
48
48
- **load**: list of additional Phutil libraries to load at startup.
49
49
See below for details about path resolution, or see
50
-
@{article@phabcontrib:Adding New Classes} for a general introduction to
50
+
@{article@contrib:Adding New Classes} for a general introduction to
51
51
libphutil libraries.
52
52
- **https.cabundle**: specifies the path to an alternate certificate bundle
53
53
for use when making HTTPS connections.
···
62
62
These options are supported, but their use is discouraged:
63
63
64
64
- **http.basicauth.user**: specify an HTTP basic auth username for use when
65
-
connecting to Phabricator.
65
+
connecting to Phorge.
66
66
- **http.basicauth.pass**: specify an HTTP basic auth password for use when
67
-
connecting to Phabricator.
67
+
connecting to Phorge.
68
68
- **https.blindly-trust-domains**: a list of domains to trust blindly over
69
69
HTTPS, even if their certificates are invalid. This is a brute force
70
70
solution to certificate validity problems, and is discouraged. Instead,
···
182
182
183
183
Without `.arcconfig`:
184
184
185
-
- You will need to set a default Phabricator URI with
185
+
- You will need to set a default Phorge URI with
186
186
`arc set-config default <uri>`, or specify an explicit URI
187
187
with `--conduit-uri` each time you run a command.
188
188
- You will not be able to run linters through arc unless you pass `--engine`
+4
-4
src/docs/user/userguide/arcanist_quick_start.diviner
+4
-4
src/docs/user/userguide/arcanist_quick_start.diviner
···
40
40
yourproject/ $ $EDITOR .arcconfig
41
41
yourproject/ $ cat .arcconfig
42
42
{
43
-
"phabricator.uri" : "https://phabricator.example.com/"
43
+
"phabricator.uri" : "https://phorge.example.com/"
44
44
}
45
45
46
-
Set `phabricator.uri` to the URI for your Phabricator install (where `arc`
46
+
Set `phabricator.uri` to the URI for your Phorge install (where `arc`
47
47
should send changes to).
48
48
49
49
NOTE: You should **commit this file** to the repository.
50
50
51
51
= Install Arcanist Credentials =
52
52
53
-
Credentials allow you to authenticate. You must have an account on Phabricator
53
+
Credentials allow you to authenticate. You must have an account on Phorge
54
54
before you can perform this step.
55
55
56
56
$ cd yourproject/
···
58
58
...
59
59
60
60
Follow the instructions. This will link your user account on your local machine
61
-
to your Phabricator account.
61
+
to your Phorge account.
62
62
63
63
= Send Changes For Review =
64
64
+5
-5
src/docs/user/userguide/audit.diviner
+5
-5
src/docs/user/userguide/audit.diviner
···
1
1
@title Audit User Guide
2
2
@group userguide
3
3
4
-
Guide to using Phabricator to audit published commits.
4
+
Guide to using Phorge to audit published commits.
5
5
6
6
7
7
Overview
8
8
========
9
9
10
-
Phabricator supports two code review workflows, "review" (pre-publish) and
10
+
Phorge supports two code review workflows, "review" (pre-publish) and
11
11
"audit" (post-publish). To understand the differences between the two, see
12
12
@{article:User Guide: Review vs Audit}.
13
13
···
59
59
- Alice publishes a commit containing some Javascript.
60
60
- This triggers an audit request to Bailey, the Javascript technical
61
61
lead on the project (see below for a description of trigger mechanisms).
62
-
- Later, Bailey logs into Phabricator and sees the audit request. She ignores
62
+
- Later, Bailey logs into Phorge and sees the audit request. She ignores
63
63
it for the moment, since it isn't blocking anything. At the end of the
64
64
week she looks through her open requests to see what the team has been
65
65
up to.
66
66
- Bailey notices a few minor problems with Alice's commit. She leaves
67
67
comments describing improvements and uses "Raise Concern" to send the
68
68
commit back into Alice's queue.
69
-
- Later, Alice logs into Phabricator and sees that Bailey has raised a
69
+
- Later, Alice logs into Phorge and sees that Bailey has raised a
70
70
concern (usually, Alice will also get an email). She resolves the issue
71
71
somehow, maybe by making a followup commit with fixes.
72
72
- After the issues have been dealt with, she uses "Request Verification" to
···
163
163
Get more information about a command by running:
164
164
165
165
```
166
-
phabricator/ $ ./bin/audit help <command>
166
+
phorge/ $ ./bin/audit help <command>
167
167
```
168
168
169
169
Supported operations are:
+1
-1
src/docs/user/userguide/calendar.diviner
+1
-1
src/docs/user/userguide/calendar.diviner
···
29
29
Availability
30
30
============
31
31
32
-
Across all applications, Phabricator shows a red dot next to usernames if the
32
+
Across all applications, Phorge shows a red dot next to usernames if the
33
33
user is currently attending an event. This provides a hint that they may be in
34
34
a meeting (or on vacation) and could take a while to get back to you about a
35
35
revision or task.
+4
-4
src/docs/user/userguide/calendar_exports.diviner
+4
-4
src/docs/user/userguide/calendar_exports.diviner
···
9
9
IMPORTANT: Calendar is a prototype application. See
10
10
@{article:User Guide: Prototype Applications}.
11
11
12
-
You can export events from Phabricator to other calendar applications like
12
+
You can export events from Phorge to other calendar applications like
13
13
**Google Calendar** or **Calendar.app**. This document will guide you through
14
-
how to export event data from Phabricator.
14
+
how to export event data from Phorge.
15
15
16
16
When you export events into another application, they generally will not be
17
17
editable from that application. Exporting events allows you to create one
18
18
calendar that shows all the events you care about in whatever application you
19
19
prefer (so you can keep track of everything you need to do), but does not let
20
-
you edit Phabricator events from another application.
20
+
you edit Phorge events from another application.
21
21
22
22
When exporting events, you can either export individual events one at a time
23
23
or export an entire group of events (for example, all events you are attending).
···
75
75
information, as though they were logged in with your account.
76
76
77
77
WARNING: Anyone who learns the URI for an export can see the data you choose
78
-
to export, even if they don't have a Phabricator account! Be careful about how
78
+
to export, even if they don't have a Phorge account! Be careful about how
79
79
much data you export and treat the URI as a secret. If you accidentally share
80
80
a URI, you can disable the export.
81
81
+12
-12
src/docs/user/userguide/calendar_imports.diviner
+12
-12
src/docs/user/userguide/calendar_imports.diviner
···
9
9
IMPORTANT: Calendar is a prototype application. See
10
10
@{article:User Guide: Prototype Applications}.
11
11
12
-
You can import events into Phabricator to other calendar applications or from
12
+
You can import events into Phorge to other calendar applications or from
13
13
`.ics` files. This document will guide you through how to import event data
14
-
into Phabricator.
14
+
into Phorge.
15
15
16
16
When you import events from another application, they can not be edited in
17
-
Phabricator. Importing events allows you to share events or keep track of
17
+
Phorge. Importing events allows you to share events or keep track of
18
18
events from different sources, but does not let you edit events from other
19
-
applications in Phabricator.
19
+
applications in Phorge.
20
20
21
21
22
22
Import Policies
···
36
36
event or an entire event calendar.
37
37
38
38
If you have an event or calendar in `.ics` format, you can import it into
39
-
Phabricator in two ways:
39
+
Phorge in two ways:
40
40
41
41
- Navigate to {nav Calendar > Imports > Import Events > Import .ics File}.
42
42
- Drag and drop the file onto a Calendar.
43
43
44
-
This will create a copy of the event in Phabricator.
44
+
This will create a copy of the event in Phorge.
45
45
46
46
If you want to update an imported event later, just repeat this process. The
47
47
event will be updated with the latest information.
48
48
49
49
Many applications send `.ics` files as email attachments. You can import these
50
-
into Phabricator.
50
+
into Phorge.
51
51
52
52
53
53
.ics Files: Google Calendar
···
68
68
You can also convert an individual event into an `.ics` file by dragging it
69
69
from the calendar to your desktop (or any other folder).
70
70
71
-
When you import an event using an `.ics` file, Phabricator can not
71
+
When you import an event using an `.ics` file, Phorge can not
72
72
automatically keep the event up to date. You'll need to repeat the process if
73
-
there are changes to the event or calendar later, so Phabricator can learn
73
+
there are changes to the event or calendar later, so Phorge can learn
74
74
about the updates.
75
75
76
76
···
78
78
=====================
79
79
80
80
If you have a calendar in another application that supports publishing a
81
-
`.ics` URI, you can subscribe to it in Phabricator. This will import the entire
81
+
`.ics` URI, you can subscribe to it in Phorge. This will import the entire
82
82
calendar, and can be configured to automatically keep it up to date and in sync
83
83
with the external calendar.
84
84
···
87
87
{nav Calendar > Imports > Import Events > Import .ics URI}.
88
88
89
89
When you import a URI, you can choose to enable automatic updates. If you do,
90
-
Phabricator will periodically update the events it imports from this source.
90
+
Phorge will periodically update the events it imports from this source.
91
91
You can stop this later by turning off the automatic updates or disabling
92
92
the import.
93
93
···
121
121
**Calendar.app** does not support subscriptions via `.ics` URIs.
122
122
123
123
You can export a calendar as an `.ics` file by following the steps above, but
124
-
Phabricator can not automatically keep events imported in this way up to date.
124
+
Phorge can not automatically keep events imported in this way up to date.
125
125
126
126
127
127
Next Steps
+2
-2
src/docs/user/userguide/conduit.diviner
+2
-2
src/docs/user/userguide/conduit.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Conduit is the HTTP API for Phabricator. It is roughly JSON-RPC: you usually
9
+
Conduit is the HTTP API for Phorge. It is roughly JSON-RPC: you usually
10
10
pass a JSON blob, and usually get a JSON blob back, although both call and
11
11
result formats are flexible in some cases.
12
12
···
30
30
includes examples which show how to format calls.
31
31
32
32
**Other Clients**: There are also clients available in other languages. You
33
-
can check the [[ https://secure.phabricator.com/w/community_resources/ |
33
+
can check the [[ https://we.phorge.it/w/community_resources/ |
34
34
Community Resources ]] page for links.
35
35
36
36
API Console
+2
-2
src/docs/user/userguide/differential.diviner
+2
-2
src/docs/user/userguide/differential.diviner
···
5
5
6
6
= Overview =
7
7
8
-
Phabricator supports two code review workflows, "review" (pre-push) and
8
+
Phorge supports two code review workflows, "review" (pre-push) and
9
9
"audit" (post-push). To understand the differences between the two, see
10
10
@{article:User Guide: Review vs Audit}.
11
11
···
14
14
15
15
= How Review Works =
16
16
17
-
Code review in Phabricator is a lightweight, asynchronous web-based process. If
17
+
Code review in Phorge is a lightweight, asynchronous web-based process. If
18
18
you are familiar with GitHub, it is similar to how pull requests work:
19
19
20
20
- An author prepares a change to a codebase, then sends it for review. They
+2
-2
src/docs/user/userguide/differential_land.diviner
+2
-2
src/docs/user/userguide/differential_land.diviner
···
1
1
@title Differential User Guide: Automated Landing
2
2
@group userguide
3
3
4
-
Configuring Phabricator so you can "Land Revision" from the web UI.
4
+
Configuring Phorge so you can "Land Revision" from the web UI.
5
5
6
6
7
7
Overview
···
9
9
10
10
IMPORTANT: This feature is a prototype and has substantial limitations.
11
11
12
-
Phabricator can be configured so that approved revisions may be published
12
+
Phorge can be configured so that approved revisions may be published
13
13
directly from the web interface. This can make publishing changes more
14
14
convenient, particularly for open source projects where authors may not have
15
15
commit access to the repository. This document explains the workflow and how to
+4
-4
src/docs/user/userguide/diffusion.diviner
+4
-4
src/docs/user/userguide/diffusion.diviner
···
1
1
@title Diffusion User Guide
2
2
@group userguide
3
3
4
-
Guide to Diffusion, the Phabricator application for hosting and browsing
4
+
Guide to Diffusion, the Phorge application for hosting and browsing
5
5
repositories.
6
6
7
7
Overview
···
16
16
interacted with, but hosted repositories support some additional triggers
17
17
and access controls which are not available for observed repositories.
18
18
19
-
Diffusion is integrated with the other tools in the Phabricator suite. For
19
+
Diffusion is integrated with the other tools in the Phorge suite. For
20
20
instance:
21
21
22
22
- when you commit Differential revisions to a tracked repository, they are
···
61
61
Repository Clustering
62
62
=====================
63
63
64
-
Phabricator repository hosts can be set up in a cluster configuration so you
64
+
Phorge repository hosts can be set up in a cluster configuration so you
65
65
can lose hosts with minimal downtime and data loss. This is an advanced feature
66
66
which most installs do not need to pursue.
67
67
···
88
88
89
89
- get details about automatically taking actions in response to commits in
90
90
@{article:Diffusion User Guide: Permanent Refs}; or
91
-
- understand how Phabricator updates repositories with
91
+
- understand how Phorge updates repositories with
92
92
@{article:Diffusion User Guide: Repository Updates}; or
93
93
- fix issues with repository imports with
94
94
@{article:Troubleshooting Repository Imports}.
+1
-1
src/docs/user/userguide/diffusion_api.diviner
+1
-1
src/docs/user/userguide/diffusion_api.diviner
···
90
90
and if you're creating a //hosted// repository you may be able to skip this
91
91
step.
92
92
93
-
However, if you want Phabricator to observe an existing remote, you'll
93
+
However, if you want Phorge to observe an existing remote, you'll
94
94
configure it here by adding a URI in "Observe" mode. Use the PHID from the
95
95
previous step to identify the repository you want to add a URI to, and call
96
96
`diffusion.uri.edit` to create a new URI in Observe mode for the repository.
+2
-2
src/docs/user/userguide/diffusion_existing.diviner
+2
-2
src/docs/user/userguide/diffusion_existing.diviner
···
10
10
If you have an existing repository, you can observe or import it into
11
11
Diffusion.
12
12
13
-
Observing a repository creates a read-only copy in Phabricator that is kept
13
+
Observing a repository creates a read-only copy in Phorge that is kept
14
14
up to date by continuously importing new changes.
15
15
16
16
Importing a repository creates a read-write copy.
···
31
31
**URIs** section, in **Observe** mode.
32
32
- Activate the repository in Diffusion.
33
33
34
-
This creates a read-only copy of the repository in Phabricator. Phabricator
34
+
This creates a read-only copy of the repository in Phorge. Phorge
35
35
will keep its copy in sync with the remote by periodically polling the remote
36
36
for changes.
37
37
+4
-4
src/docs/user/userguide/diffusion_hooks.diviner
+4
-4
src/docs/user/userguide/diffusion_hooks.diviner
···
5
5
6
6
= Overview =
7
7
8
-
Phabricator installs pre-receive/pre-commit hooks in hosted repositories
8
+
Phorge installs pre-receive/pre-commit hooks in hosted repositories
9
9
automatically. They enforce a few rules automatically (like preventing
10
10
dangerous changes unless a repository is configured to allow them). They can
11
11
also enforce more complex rules via Herald, using the "Commit Hook:
···
26
26
27
27
- **SVN** Put hooks in `hooks/pre-commit-phabricator.d/`.
28
28
- **Git** Put hooks in `hooks/pre-receive-phabricator.d/`.
29
-
- **Mercurial** Phabricator does not currently support custom hooks in
29
+
- **Mercurial** Phorge does not currently support custom hooks in
30
30
Mercurial.
31
31
32
32
These hooks act like normal `pre-commit` or `pre-receive` hooks:
···
37
37
passed.
38
38
- They should emit output and return codes like normal hooks do.
39
39
- These hooks will run only after all the Herald rules have passed and
40
-
Phabricator is otherwise ready to accept the commit or push.
40
+
Phorge is otherwise ready to accept the commit or push.
41
41
42
42
These additional variables will be available in the environment, in addition
43
43
to the variables the VCS normally provides:
44
44
45
45
- `PHABRICATOR_REPOSITORY` The PHID of the repository the hook is
46
46
executing for.
47
-
- `PHABRICATOR_USER` The Phabricator username that the session is
47
+
- `PHABRICATOR_USER` The Phorge username that the session is
48
48
authenticated under.
49
49
- `PHABRICATOR_REMOTE_ADDRESS` The connection's remote address (that is,
50
50
the IP address of whoever is pushing or committing).
+55
-55
src/docs/user/userguide/diffusion_hosting.diviner
+55
-55
src/docs/user/userguide/diffusion_hosting.diviner
···
1
1
@title Diffusion User Guide: Repository Hosting
2
2
@group userguide
3
3
4
-
Guide to configuring Phabricator repository hosting.
4
+
Guide to configuring Phorge repository hosting.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator can host repositories and provide authenticated read and write
9
+
Phorge can host repositories and provide authenticated read and write
10
10
access to them over HTTP and SSH. This document describes how to configure
11
11
repository hosting.
12
12
13
13
Understanding Supported Protocols
14
14
=================================
15
15
16
-
Phabricator supports hosting over these protocols:
16
+
Phorge supports hosting over these protocols:
17
17
18
18
| VCS | SSH | HTTP |
19
19
|-----|-----|------|
···
47
47
Creating System User Accounts
48
48
=============================
49
49
50
-
Phabricator uses two system user accounts, plus a third account if you
50
+
Phorge uses two system user accounts, plus a third account if you
51
51
configure SSH access. This section will guide you through creating and
52
-
configuring them. These are system user accounts on the machine Phabricator
53
-
runs on, not Phabricator user accounts.
52
+
configuring them. These are system user accounts on the machine Phorge
53
+
runs on, not Phorge user accounts.
54
54
55
-
The system accounts Phabricator uses are:
55
+
The system accounts Phorge uses are:
56
56
57
57
- The user the webserver runs as. We'll call this `www-user`.
58
58
- The user the daemons run as. We'll call this `daemon-user`. This
···
73
73
the daemons to start as this user.
74
74
- Create a `vcs-user` if one does not already exist and you plan to set up
75
75
SSH. When users clone repositories, they will use a URI like
76
-
`vcs-user@phabricator.yourcompany.com`, so common names for this user are
76
+
`vcs-user@phorge.yourcompany.com`, so common names for this user are
77
77
`git` or `hg`.
78
78
79
79
Continue below to configure these accounts.
80
80
81
81
82
-
Configuring Phabricator
82
+
Configuring Phorge
83
83
=======================
84
84
85
-
Now that you have created or identified these accounts, update the Phabricator
85
+
Now that you have created or identified these accounts, update the Phorge
86
86
configuration to specify them.
87
87
88
88
First, set `phd.user` to the `daemon-user`:
89
89
90
90
```
91
-
phabricator/ $ ./bin/config set phd.user daemon-user
91
+
phorge/ $ ./bin/config set phd.user daemon-user
92
92
```
93
93
94
94
Restart the daemons to make sure this configuration works properly. They should
···
97
97
If you're using a `vcs-user` for SSH, you should also configure that:
98
98
99
99
```
100
-
phabricator/ $ ./bin/config set diffusion.ssh-user vcs-user
100
+
phorge/ $ ./bin/config set diffusion.ssh-user vcs-user
101
101
```
102
102
103
103
Next, you'll set up `sudo` permissions so these users can interact with one
···
214
214
If you plan to use authenticated HTTP, you (and all other users) also need to
215
215
configure a VCS password for your account in {nav Settings > VCS Password}.
216
216
217
-
Your VCS password must be a different password than your main Phabricator
217
+
Your VCS password must be a different password than your main Phorge
218
218
password because VCS passwords are very easy to accidentally disclose. They are
219
219
often stored in plaintext in world-readable files, observable in `ps` output,
220
220
and present in command output and logs. We strongly encourage you to use SSH
···
234
234
SSH access requires some additional setup. You will configure and run a second,
235
235
restricted copy of `sshd` on the machine, on a different port from the standard
236
236
`sshd`. This special copy of `sshd` will serve repository requests and provide
237
-
other Phabricator SSH services.
237
+
other Phorge SSH services.
238
238
239
-
NOTE: The Phabricator `sshd` service **MUST** be 6.2 or newer, because
240
-
Phabricator relies on the `AuthorizedKeysCommand` option.
239
+
NOTE: The Phorge `sshd` service **MUST** be 6.2 or newer, because
240
+
Phorge relies on the `AuthorizedKeysCommand` option.
241
241
242
242
Before continuing, you must choose a strategy for which port each copy of
243
243
`sshd` will run on. The next section lays out various approaches.
···
273
273
is often the simplest and cleanest approach.
274
274
275
275
**Swap Ports**: You can move the administrative `sshd` to a new port, then run
276
-
Phabricator `sshd` on port 22. This is somewhat complicated and can be a bit
276
+
Phorge `sshd` on port 22. This is somewhat complicated and can be a bit
277
277
risky if you make a mistake. See "Moving the sshd Port" below for help.
278
278
279
279
**Change Client Config**: You can run on a nonstandard port, but configure SSH
···
282
282
`~/.ssh/config`:
283
283
284
284
```
285
-
Host phabricator.corporation.com
285
+
Host phorge.corporation.com
286
286
Port 2222
287
287
```
288
288
···
295
295
`~/.ssh/config` files individually.
296
296
297
297
This file also allows you to define short names for hosts using the `Host` and
298
-
`HostName` options. If you choose to do this, be aware that Phabricator uses
298
+
`HostName` options. If you choose to do this, be aware that Phorge uses
299
299
remote/clone URIs to figure out which repository it is operating in, but can
300
300
not resolve host aliases defined in your `ssh` config. If you create host
301
301
aliases they may break some features related to repository identification.
···
327
327
continue `sshd` setup.
328
328
329
329
If you plan to connect to a port other than `22`, you should set this port
330
-
as `diffusion.ssh-port` in your Phabricator config:
330
+
as `diffusion.ssh-port` in your Phorge config:
331
331
332
332
```
333
333
$ ./bin/config set diffusion.ssh-port 2222
···
336
336
This port is not special, and you are free to choose a different port, provided
337
337
you make the appropriate configuration adjustment below.
338
338
339
-
**Configure and Start Phabricator SSHD**: Now, you'll configure and start a
340
-
copy of `sshd` which will serve Phabricator services, including repositories,
339
+
**Configure and Start Phorge SSHD**: Now, you'll configure and start a
340
+
copy of `sshd` which will serve Phorge services, including repositories,
341
341
over SSH.
342
342
343
343
This instance will use a special locked-down configuration that uses
344
-
Phabricator to handle authentication and command execution.
344
+
Phorge to handle authentication and command execution.
345
345
346
346
There are three major steps:
347
347
348
-
- Create a `phabricator-ssh-hook.sh` file.
349
-
- Create a `sshd_phabricator` config file.
348
+
- Create a `phorge-ssh-hook.sh` file.
349
+
- Create a `sshd_phorge config file.
350
350
- Start a copy of `sshd` using the new configuration.
351
351
352
-
**Create `phabricator-ssh-hook.sh`**: Copy the template in
353
-
`phabricator/resources/sshd/phabricator-ssh-hook.sh` to somewhere like
354
-
`/usr/libexec/phabricator-ssh-hook.sh` and edit it to have the correct
352
+
**Create `phorge-ssh-hook.sh`**: Copy the template in
353
+
`phorge/resources/sshd/phorge-ssh-hook.sh` to somewhere like
354
+
`/usr/libexec/phorge-ssh-hook.sh` and edit it to have the correct
355
355
settings.
356
356
357
357
Both the script itself **and** the parent directory the script resides in must
···
359
359
360
360
```
361
361
$ sudo chown root /path/to/somewhere/
362
-
$ sudo chown root /path/to/somewhere/phabricator-ssh-hook.sh
363
-
$ sudo chmod 755 /path/to/somewhere/phabricator-ssh-hook.sh
362
+
$ sudo chown root /path/to/somewhere/phorge-ssh-hook.sh
363
+
$ sudo chmod 755 /path/to/somewhere/phorge-ssh-hook.sh
364
364
```
365
365
366
366
If you don't do this, `sshd` will refuse to execute the hook.
367
367
368
-
**Create `sshd_config` for Phabricator**: Copy the template in
369
-
`phabricator/resources/sshd/sshd_config.phabricator.example` to somewhere like
370
-
`/etc/ssh/sshd_config.phabricator`.
368
+
**Create `sshd_config` for Phorge**: Copy the template in
369
+
`phorge/resources/sshd/sshd_config.phabricator.example` to somewhere like
370
+
`/etc/ssh/sshd_config.phorge`.
371
371
372
372
Open the file and edit the `AuthorizedKeysCommand`,
373
373
`AuthorizedKeysCommandUser`, and `AllowUsers` settings to be correct for your
···
376
376
This configuration file also specifies the `Port` the service should run on.
377
377
If you intend to run on a non-default port, adjust it now.
378
378
379
-
**Start SSHD**: Now, start the Phabricator `sshd`:
379
+
**Start SSHD**: Now, start the Phorge `sshd`:
380
380
381
-
sudo /path/to/sshd -f /path/to/sshd_config.phabricator
381
+
sudo /path/to/sshd -f /path/to/sshd_config.phorge
382
382
383
383
If you did everything correctly, you should be able to run this command:
384
384
385
385
```
386
-
$ echo {} | ssh vcs-user@phabricator.yourcompany.com conduit conduit.ping
386
+
$ echo {} | ssh vcs-user@phorge.yourcompany.com conduit conduit.ping
387
387
```
388
388
389
389
...and get a response like this:
390
390
391
391
```lang=json
392
-
{"result":"phabricator.yourcompany.com","error_code":null,"error_info":null}
392
+
{"result":"phorge.yourcompany.com","error_code":null,"error_info":null}
393
393
```
394
394
395
395
If you get an authentication error, make sure you added your public key in
···
421
421
422
422
Some general tips for troubleshooting problems with HTTP:
423
423
424
-
- Make sure `diffusion.allow-http-auth` is enabled in your Phabricator config.
424
+
- Make sure `diffusion.allow-http-auth` is enabled in your Phorge config.
425
425
- Make sure HTTP serving is enabled for the repository you're trying to
426
426
clone. You can find this in {nav Edit Repository > Hosting}.
427
427
- Make sure you've configured a VCS password. This is separate from your main
···
467
467
You should see an `svn checkout svn+ssh://...`, `git clone ssh://...` or
468
468
`hg clone ssh://...` command. Run that command verbatim to clone the
469
469
repository.
470
-
- Check your `phabricator-ssh-hook.sh` file for proper settings.
471
-
- Check your `sshd_config.phabricator` file for proper settings.
470
+
- Check your `phorge-ssh-hook.sh` file for proper settings.
471
+
- Check your `sshd_config.phorge` file for proper settings.
472
472
473
473
To troubleshoot SSH setup: connect to the server with `ssh`, without running a
474
474
command. You may need to use the `-T` flag, and will need to use `-p` if you
475
475
are running on a nonstandard port. You should see a message like this one:
476
476
477
-
$ ssh -T -p 2222 vcs-user@phabricator.yourcompany.com
478
-
phabricator-ssh-exec: Welcome to Phabricator.
477
+
$ ssh -T -p 2222 vcs-user@phorge.yourcompany.com
478
+
phorge-ssh-exec: Welcome to Phorge.
479
479
480
480
You are logged in as alincoln.
481
481
482
482
You haven't specified a command to run. This means you're requesting an
483
-
interactive shell, but Phabricator does not provide an interactive shell over
483
+
interactive shell, but Phorge does not provide an interactive shell over
484
484
SSH.
485
485
486
486
Usually, you should run a command like `git clone` or `hg push` rather than
···
498
498
- The `vcs-user` has `NP` in `/etc/shadow`.
499
499
- The `vcs-user` has `/bin/sh` or some other valid shell in `/etc/passwd`.
500
500
- Your SSH private key is correct, and you've added the corresponding
501
-
public key to Phabricator in the Settings panel.
501
+
public key to Phorge in the Settings panel.
502
502
503
503
If you can get this far, but can't execute VCS commands like `git clone`, there
504
504
is probably an issue with your `sudoers` configuration. Check:
···
513
513
514
514
It may also be helpful to run `sshd` in debug mode:
515
515
516
-
$ /path/to/sshd -d -d -d -f /path/to/sshd_config.phabricator
516
+
$ /path/to/sshd -d -d -d -f /path/to/sshd_config.phorge
517
517
518
518
This will run it in the foreground and emit a large amount of debugging
519
519
information when you connect to it.
···
525
525
$ sudo -E -n -u daemon-user -- /path/to/some/vcs-binary --help
526
526
527
527
That will try to run the binary via `sudo` in a manner similar to the way that
528
-
Phabricator will run it. This can give you better error messages about issues
528
+
Phorge will run it. This can give you better error messages about issues
529
529
with `sudoers` configuration.
530
530
531
531
···
533
533
=============================
534
534
535
535
- If you're getting an error about `svnlook` not being found, add the path
536
-
where `svnlook` is located to the Phabricator configuration
536
+
where `svnlook` is located to the Phorge configuration
537
537
`environment.append-paths` (even if it already appears in PATH). This issue
538
538
is caused by SVN wiping the environment (including PATH) when invoking
539
539
commit hooks.
···
543
543
====================
544
544
545
545
If you want to move the standard (administrative) `sshd` to a different port to
546
-
make Phabricator repository URIs cleaner, this section has some tips.
546
+
make Phorge repository URIs cleaner, this section has some tips.
547
547
548
548
This is optional, and it is normally easier to do this by putting a load
549
-
balancer in front of Phabricator and having it accept TCP traffic on port 22
549
+
balancer in front of Phorge and having it accept TCP traffic on port 22
550
550
and forward it to some other port.
551
551
552
552
When moving `sshd`, be careful when editing the configuration. If you get it
···
582
582
583
583
ssh -p 222 ...
584
584
585
-
Now you can move the Phabricator `sshd` to port 22, then adjust the value
586
-
for `diffusion.ssh-port` in your Phabricator configuration.
585
+
Now you can move the Phorge `sshd` to port 22, then adjust the value
586
+
for `diffusion.ssh-port` in your Phorge configuration.
587
587
588
588
589
589
No Direct Pushes
···
591
591
592
592
You may get an error about "No Direct Pushes" when trying to push. This means
593
593
you are pushing directly to the repository instead of pushing through
594
-
Phabricator. This is not supported: writes to hosted repositories must go
595
-
through Phabricator so it can perform authentication, enforce permissions,
594
+
Phorge. This is not supported: writes to hosted repositories must go
595
+
through Phorge so it can perform authentication, enforce permissions,
596
596
write logs, proxy requests, apply rewriting, etc.
597
597
598
598
One way to do a direct push by mistake is to use a `file:///` URI to interact
···
616
616
617
617
The technical reason this error occurs is that the `PHABRICATOR_USER` variable
618
618
is not defined in the environment when commit hooks run. This variable is set
619
-
by Phabricator when a request passes through the authentication layer that this
619
+
by Phorge when a request passes through the authentication layer that this
620
620
document provides instructions for configuring. Its absence indicates that the
621
-
request did not pass through Phabricator.
621
+
request did not pass through Phorge.
622
622
623
623
624
624
Next Steps
+17
-17
src/docs/user/userguide/diffusion_managing.diviner
+17
-17
src/docs/user/userguide/diffusion_managing.diviner
···
37
37
=================
38
38
39
39
Each repository can optionally be identified by a "callsign", which is a short
40
-
uppercase string like "P" (for Phabricator) or "ARC" (for Arcanist).
40
+
uppercase string like "P" (for Phorge) or "ARC" (for Arcanist).
41
41
42
42
The primary goal of callsigns is to namespace commits to SVN repositories: if
43
43
you use multiple SVN repositories, each repository has a revision 1, revision 2,
···
55
55
install but do not need to be globally unique, so you are free to use the
56
56
single-letter callsigns for brevity. For example, Facebook uses "E" for the
57
57
Engineering repository, "O" for the Ops repository, "Y" for a Yum package
58
-
repository, and so on, while Phabricator uses "P" and Arcanist uses "ARC".
58
+
repository, and so on, while Phorge uses "P" and Arcanist uses "ARC".
59
59
Keeping callsigns brief will make them easier to use, and the use of
60
60
one-character callsigns is encouraged if they are reasonably evocative.
61
61
62
-
If you configure a callsign like `XYZ`, Phabricator will activate callsign URIs
62
+
If you configure a callsign like `XYZ`, Phorge will activate callsign URIs
63
63
and activate the callsign identifier (like `rXYZ`) for the repository. These
64
64
more human-readable identifiers can make things a little easier to interact
65
65
with.
···
104
104
to adjust this setting.
105
105
106
106
If your repository is primarily written in some other encoding, specify it here
107
-
so Phabricator can convert from it properly when reading content to embed in
107
+
so Phorge can convert from it properly when reading content to embed in
108
108
a webpage or email.
109
109
110
110
···
131
131
This option is only available in Git and Mercurial, because it is impossible
132
132
to make dangerous changes in Subversion.
133
133
134
-
This option has no effect if a repository is not hosted because Phabricator
134
+
This option has no effect if a repository is not hosted because Phorge
135
135
can not prevent dangerous changes in a remote repository it is merely
136
136
observing.
137
137
···
195
195
==============
196
196
197
197
The view policy for a repository controls who can view the repository from
198
-
the web UI and clone, fetch, or check it out from Phabricator.
198
+
the web UI and clone, fetch, or check it out from Phorge.
199
199
200
200
Users who can view a repository can also access the "Manage" interface to
201
201
review information about the repository and examine the edit history, but can
···
220
220
The push policy for a repository controls who can push changes to the
221
221
repository.
222
222
223
-
This policy has no effect if Phabricator is not hosting the repository, because
223
+
This policy has no effect if Phorge is not hosting the repository, because
224
224
it can not control who is allowed to make changes to a remote repository it is
225
225
merely observing.
226
226
···
230
230
231
231
Further restrictions on who can push (and what they can push) can be configured
232
232
for hosted repositories with Herald, which allows you to write more
233
-
sophisticated rules that evaluate when Phabricator receives a push. To get
233
+
sophisticated rules that evaluate when Phorge receives a push. To get
234
234
started with Herald, see @{article:Herald User Guide}.
235
235
236
236
Additionally, Git and Mercurial repositories have a setting which allows
···
241
241
URIs
242
242
====
243
243
244
-
The **URIs** panel allows you to add and manage URIs which Phabricator will
244
+
The **URIs** panel allows you to add and manage URIs which Phorge will
245
245
fetch from, serve from, and push to.
246
246
247
247
These options are covered in detail in @{article:Diffusion User Guide: URIs}.
···
292
292
Branches
293
293
========
294
294
295
-
The **Branches** panel allows you to configure how Phabricator interacts with
295
+
The **Branches** panel allows you to configure how Phorge interacts with
296
296
branches.
297
297
298
298
This panel is not available for Subversion repositories, because Subversion
299
299
does not have formal branches.
300
300
301
301
You can configure a **Default Branch**. This controls which branch is shown by
302
-
default in the UI. If no branch is provided, Phabricator will use `master` in
302
+
default in the UI. If no branch is provided, Phorge will use `master` in
303
303
Git and `default` in Mercurial.
304
304
305
305
**Fetch Refs**: In Git, if you are observing a remote repository, you can
···
324
324
325
325
This may be useful if the remote is on a service like GitHub, GitLab, or
326
326
Gerrit and uses custom refs (like `refs/pull/` or `refs/changes/`) to store
327
-
metadata that you don't want to bring into Phabricator.
327
+
metadata that you don't want to bring into Phorge.
328
328
329
329
**Permanent Refs**: To learn more about permanent refs, see:
330
330
331
331
- @{article:Diffusion User Guide: Permanent Refs}
332
332
333
-
By default, Phabricator considers all branches to be permanent refs. If you
333
+
By default, Phorge considers all branches to be permanent refs. If you
334
334
only want some branches to be treated as permanent refs, specify them here.
335
335
336
336
When specifying branches, you should enter one branch name per line. You can
···
356
356
Automation
357
357
==========
358
358
359
-
The **Automation** panel configures support for allowing Phabricator to make
359
+
The **Automation** panel configures support for allowing Phorge to make
360
360
writes directly to the repository, so that it can perform operations like
361
361
automatically landing revisions from the web UI.
362
362
···
400
400
the intent is unambiguous, but only the first two forms work in ambiguous
401
401
contexts.
402
402
403
-
For example, if you type `R123` or `rXY` into a comment, Phabricator will
403
+
For example, if you type `R123` or `rXY` into a comment, Phorge will
404
404
recognize them as references to the repository. If you type `xylophone`, it
405
405
assumes you mean the word "xylophone".
406
406
···
421
421
works if a repository has a callsign.
422
422
- Any unique prefix of the commit hash.
423
423
424
-
Git and Mercurial use commit hashes to identify commits, and Phabricator will
424
+
Git and Mercurial use commit hashes to identify commits, and Phorge will
425
425
recognize a commit if the hash prefix is unique and sufficiently long. Commit
426
426
hashes qualified with a repository identifier must be at least 5 characters
427
427
long; unqualified commit hashes must be at least 7 characters long.
···
429
429
In Subversion, commit identifiers are sequential integers and prefixes can not
430
430
be used to identify them.
431
431
432
-
When rendering the name of a Git or Mercurial commit hash, Phabricator tends to
432
+
When rendering the name of a Git or Mercurial commit hash, Phorge tends to
433
433
shorten it to 12 characters. This "short length" is relatively long compared to
434
434
Git itself (which often uses 7 characters). See this post on the LKML for a
435
435
historical explanation of Git's occasional internal use of 7-character hashes:
+5
-5
src/docs/user/userguide/diffusion_permanent.diviner
+5
-5
src/docs/user/userguide/diffusion_permanent.diviner
···
7
7
========
8
8
9
9
Diffusion can close tasks and revisions and take other actions when commits
10
-
appear in a repository (either because they were pushed to Phabricator, or
11
-
because they were pushed to some remote which Phabricator is observing).
10
+
appear in a repository (either because they were pushed to Phorge, or
11
+
because they were pushed to some remote which Phorge is observing).
12
12
13
13
This document explains when Diffusion acts on commits and how to configure this
14
14
behavior.
···
24
24
`refs/pull/123`, `refs/notes/*`, or `refs/changes/12/345678/1`.
25
25
26
26
Sometimes, human users intentionally push changes to branches like
27
-
"tmp-hack-ignore-123". This is formally discouraged by Phabricator, but the
27
+
"tmp-hack-ignore-123". This is formally discouraged by Phorge, but the
28
28
practice is so widespread that we've given up trying to stop anyone from doing
29
29
it.
30
30
31
-
Phabricator will import these commits and create pages for them so you can view
31
+
Phorge will import these commits and create pages for them so you can view
32
32
them in the web UI and link to them, but does not take any other actions until
33
33
they are "published".
34
34
···
40
40
Usually, commits are published by pushing them directly to a permanent branch
41
41
like "master", or by merging a temporary branch into a permanent branch.
42
42
43
-
When a commit is published, Phabricator acts on it and:
43
+
When a commit is published, Phorge acts on it and:
44
44
45
45
- sends email;
46
46
- delivers notifications;
+6
-6
src/docs/user/userguide/diffusion_symbols.diviner
+6
-6
src/docs/user/userguide/diffusion_symbols.diviner
···
5
5
6
6
= Overview =
7
7
8
-
Phabricator can maintain a symbol index, which keeps track of where classes
8
+
Phorge can maintain a symbol index, which keeps track of where classes
9
9
and functions are defined in the codebase. Once you set up indexing, you can
10
10
use the index to do things like:
11
11
···
25
25
26
26
./scripts/symbols/import_repository_symbols.php
27
27
28
-
Phabricator includes a script which can identify symbols in PHP projects:
28
+
Phorge includes a script which can identify symbols in PHP projects:
29
29
30
30
./scripts/symbols/generate_php_symbols.php
31
31
32
-
Phabricator also includes a script which can identify symbols in any
32
+
Phorge also includes a script which can identify symbols in any
33
33
programming language that has classes and/or functions, and is supported by
34
34
Exuberant Ctags (http://ctags.sourceforge.net):
35
35
···
59
59
You can look at `generate_php_symbols.php` for an example of how you might
60
60
write such a script, and run this command to see its output:
61
61
62
-
$ cd phabricator/
62
+
$ cd phorge/
63
63
$ find . -type f -name '*.php' | ./scripts/symbols/generate_php_symbols.php
64
64
65
65
To actually build the symbol index, pipe this data to the
···
83
83
You can leave this blank for "All languages".
84
84
- **Uses Symbols From**: If this project depends on other repositories, add
85
85
the other repositories which symbols should be looked for here. For example,
86
-
Phabricator lists "Arcanist" because it uses classes and functions defined
86
+
Phorge lists "Arcanist" because it uses classes and functions defined
87
87
in `arcanist/`.
88
88
89
89
== External Symbols ==
90
90
91
-
By @{article@phabcontrib:Adding New Classes}, you can teach Phabricator
91
+
By @{article@contrib:Adding New Classes}, you can teach Phorge
92
92
about symbols from the outside world.
93
93
Extend @{class:DiffusionExternalSymbolsSource}; Once loaded, your new
94
94
implementation will be used any time a symbol is queried.
+9
-9
src/docs/user/userguide/diffusion_updates.diviner
+9
-9
src/docs/user/userguide/diffusion_updates.diviner
···
6
6
Overview
7
7
========
8
8
9
-
When Phabricator is configured to import repositories which are hosted
9
+
When Phorge is configured to import repositories which are hosted
10
10
elsewhere, it needs to poll those repositories for changes. If it polls too
11
11
frequently, it can create too much load locally and on remote services. If it
12
12
polls too rarely, it may take a long time for commits to show up in the web
···
15
15
This document describes the rules around polling and how to understand and
16
16
adjust the behavior. In general:
17
17
18
-
- Phabricator chooses a default poll interval based on repository
18
+
- Phorge chooses a default poll interval based on repository
19
19
activity. These intervals range from every 15 seconds (for active
20
20
repositories) to every 6 hours (for repositories with no commits in two
21
21
months).
22
-
- If you use `arc` to push commits, or you host repositories on Phabricator,
22
+
- If you use `arc` to push commits, or you host repositories on Phorge,
23
23
repositories automatically update after changes are pushed.
24
24
- If you don't use `arc` and your repository is hosted elsewhere, this
25
25
document describes ways you can make polling more responsive.
···
28
28
Default Behavior
29
29
================
30
30
31
-
By default, Phabricator determines how frequently to poll repositories by
31
+
By default, Phorge determines how frequently to poll repositories by
32
32
examining how long it has been since the last commit. In most cases this is
33
33
fairly accurate and produces good behavior. In particular, it automatically
34
34
reduces the polling frequency for rarely-used repositories. This dramatically
···
77
77
Triggering Repository Updates
78
78
=============================
79
79
80
-
If you want Phabricator to update a repository more quickly than the default
80
+
If you want Phorge to update a repository more quickly than the default
81
81
update frequency (for example, because you just pushed a commit to it), you can
82
-
tell Phabricator that it should schedule an update as soon as possible.
82
+
tell Phorge that it should schedule an update as soon as possible.
83
83
84
84
There are several ways to do this:
85
85
86
86
- If you push changes with `arc land` or `arc commit`, this will be done
87
87
for you automatically. These commits should normally be recognized within
88
88
a few seconds.
89
-
- If your repository is hosted on Phabricator, this will also be done for you
89
+
- If your repository is hosted on Phorge, this will also be done for you
90
90
automatically.
91
91
- You can schedule an update from the web interface, in Diffusion >
92
92
(Choose a Repository) > Manage Repository > Status > Update Now.
93
93
- You can make a call to the Conduit API method `diffusion.looksoon`. This
94
-
hints to Phabricator that it should poll a repository as soon as it can.
94
+
hints to Phorge that it should poll a repository as soon as it can.
95
95
All of the other mechanisms do this under the hood.
96
96
97
97
In particular, you may be able to add a commit hook to your external repository
···
109
109
You can manually run a repository update from the command line to troubleshoot
110
110
issues, using the `--trace` flag to get full details:
111
111
112
-
phabricator/ $ ./bin/repository update --trace <repository>
112
+
phorge/ $ ./bin/repository update --trace <repository>
113
113
114
114
To catch potential issues with permissions, run this command as the same user
115
115
that the daemons run as.
+47
-47
src/docs/user/userguide/diffusion_uris.diviner
+47
-47
src/docs/user/userguide/diffusion_uris.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator can create, host, observe, mirror, proxy, and import repositories.
9
+
Phorge can create, host, observe, mirror, proxy, and import repositories.
10
10
For example, you can:
11
11
12
-
**Host Repositories**: Phabricator can host repositories locally. Phabricator
12
+
**Host Repositories**: Phorge can host repositories locally. Phorge
13
13
maintains the writable master version of the repository, and you can push and
14
14
pull the repository. This is the most straightforward kind of repository
15
15
configuration, and similar to repositories on other services like GitHub or
16
16
Bitbucket.
17
17
18
-
**Observe Repositories**: Phabricator can create a copy of an repository which
18
+
**Observe Repositories**: Phorge can create a copy of an repository which
19
19
is hosted elsewhere (like GitHub or Bitbucket) and track updates to the remote
20
-
repository. This will create a read-only copy of the repository in Phabricator.
20
+
repository. This will create a read-only copy of the repository in Phorge.
21
21
22
-
**Mirror Repositories**: Phabricator can publish any repository to mirrors,
22
+
**Mirror Repositories**: Phorge can publish any repository to mirrors,
23
23
overwriting them with an exact copy of the repository that stays up to date as
24
-
the source changes. This works with both local repositories that Phabricator is
25
-
hosting and remote repositories that Phabricator is observing.
24
+
the source changes. This works with both local repositories that Phorge is
25
+
hosting and remote repositories that Phorge is observing.
26
26
27
27
**Proxy Repositories**: If you are observing a repository, you can allow users
28
-
to read Phabricator's copy of the repository. Phabricator supports granular
28
+
to read Phorge's copy of the repository. Phorge supports granular
29
29
read permissions, so this can let you open a private repository up a little
30
30
bit in a flexible way.
31
31
32
32
**Import Repositories**: If you have a repository elsewhere that you want to
33
-
host on Phabricator, you can observe the remote repository first, then turn
33
+
host on Phorge, you can observe the remote repository first, then turn
34
34
the tracking off once the repository fully synchronizes. This allows you to
35
-
copy an existing repository and begin hosting it in Phabricator.
35
+
copy an existing repository and begin hosting it in Phorge.
36
36
37
37
You can also import repositories by creating an empty hosted repository and
38
38
then pushing everything to the repository directly.
39
39
40
-
You configure the behavior of a Phabricator repository by adding and
40
+
You configure the behavior of a Phorge repository by adding and
41
41
configuring URIs and marking them to be fetched from, mirrored to, clonable,
42
42
and so on. By configuring all the URIs that a repository should interact with
43
43
and expose to users, you configure the read, write, and mirroring behavior
···
50
50
Host a Repository
51
51
=================
52
52
53
-
You can create new repositories that Phabricator will host, like you would
54
-
create repositories on services like GitHub or Bitbucket. Phabricator will
55
-
serve a read-write copy of the repository and you can clone it from Phabricator
56
-
and push changes to Phabricator.
53
+
You can create new repositories that Phorge will host, like you would
54
+
create repositories on services like GitHub or Bitbucket. Phorge will
55
+
serve a read-write copy of the repository and you can clone it from Phorge
56
+
and push changes to Phorge.
57
57
58
-
If you haven't already, you may need to configure Phabricator for hosting
58
+
If you haven't already, you may need to configure Phorge for hosting
59
59
before you can create your first hosted repository. For a detailed guide,
60
60
see @{article:Diffusion User Guide: Repository Hosting}.
61
61
···
64
64
- Create a new repository.
65
65
- Activate it.
66
66
67
-
Phabricator will create an empty repository and allow you to fetch from it and
67
+
Phorge will create an empty repository and allow you to fetch from it and
68
68
push to it.
69
69
70
70
···
72
72
====================
73
73
74
74
If you have an existing repository hosted on another service (like GitHub,
75
-
Bitbucket, or a private server) that you want to work with in Phabricator,
76
-
you can configure Phabricator to observe it.
75
+
Bitbucket, or a private server) that you want to work with in Phorge,
76
+
you can configure Phorge to observe it.
77
77
78
-
When observing a repository, Phabricator will keep track of changes in the
78
+
When observing a repository, Phorge will keep track of changes in the
79
79
remote repository and allow you to browse and interact with the repository from
80
80
the web UI in Diffusion and other applications, but you can continue hosting it
81
81
elsewhere.
···
88
88
- If necessary, configure a credential.
89
89
- Activate the repository.
90
90
91
-
Phabricator will perform an initial import of the repository, creating a local
91
+
Phorge will perform an initial import of the repository, creating a local
92
92
read-only copy. Once this process completes, it will continue keeping track of
93
93
changes in the remote, fetching them, and reflecting them in the UI.
94
94
···
98
98
99
99
NOTE: Mirroring is not supported in Subversion.
100
100
101
-
You can create a read-only mirror of an existing repository. Phabricator will
101
+
You can create a read-only mirror of an existing repository. Phorge will
102
102
continuously publish the state of the source repository to the mirror, creating
103
103
an exact copy.
104
104
105
-
For example, if you have a repository hosted in Phabricator that you want to
106
-
mirror to GitHub, you can configure Phabricator to automatically maintain the
105
+
For example, if you have a repository hosted in Phorge that you want to
106
+
mirror to GitHub, you can configure Phorge to automatically maintain the
107
107
mirror. This is how the upstream repositories are set up.
108
108
109
109
The mirror copy must be read-only for users because any writes made to the
110
-
mirror will be undone when Phabricator updates it. The mirroring process copies
110
+
mirror will be undone when Phorge updates it. The mirroring process copies
111
111
the entire repository state exactly, so the remote state will be completely
112
112
replaced with an exact copy of the source repository. This may remove or
113
113
destroy information. Normally, you should only mirror to an empty repository.
114
114
115
-
You can mirror any repository, even if Phabricator is only observing it and not
115
+
You can mirror any repository, even if Phorge is only observing it and not
116
116
hosting it directly.
117
117
118
118
To begin mirroring a repository:
···
133
133
===================
134
134
135
135
If you have an existing repository that you want to move so it is hosted on
136
-
Phabricator, there are three ways to do it:
136
+
Phorge, there are three ways to do it:
137
137
138
138
**Observe First**: //(Git, Mercurial)// Observe the existing repository first,
139
-
according to the instructions above. Once Phabricator's copy of the repository
139
+
according to the instructions above. Once Phorge's copy of the repository
140
140
is fully synchronized, change the **I/O Type** for the **Observe** URI to
141
141
**None** to stop fetching changes from the remote.
142
142
143
-
By default, this will automatically make Phabricator's copy of the repository
143
+
By default, this will automatically make Phorge's copy of the repository
144
144
writable, and you can begin pushing to it. If you've adjusted URI
145
145
configuration away from the defaults, you may need to set at least one URI
146
146
to **Read/Write** mode so you can push to it.
···
169
169
Builtin Clone URIs
170
170
==================
171
171
172
-
By default, Phabricator automatically exposes and activates HTTP, HTTPS and
172
+
By default, Phorge automatically exposes and activates HTTP, HTTPS and
173
173
SSH clone URIs by examining configuration.
174
174
175
175
**HTTP**: The `http://` clone URI will be available if these conditions are
···
198
198
================================
199
199
200
200
If you have an unusual configuration and want the UI to offers users specific
201
-
clone URIs other than the URIs that Phabricator serves or interacts with, you
201
+
clone URIs other than the URIs that Phorge serves or interacts with, you
202
202
can add those URIs with the **I/O Type** set to **None** and then set their
203
203
**Display Type** to **Always**.
204
204
···
214
214
215
215
This section details the available **I/O Type** options for URIs.
216
216
217
-
Each repository has some **builtin** URIs. These are URIs hosted by Phabricator
217
+
Each repository has some **builtin** URIs. These are URIs hosted by Phorge
218
218
itself. The modes available for each URI depend primarily on whether it is a
219
219
builtin URI or not.
220
220
221
-
**Default**: This setting has Phabricator guess the correct option for the
221
+
**Default**: This setting has Phorge guess the correct option for the
222
222
URI.
223
223
224
224
For **builtin** URIs, the default behavior is //Read/Write// if the repository
···
228
228
guess if you want to ignore, observe, or mirror a URI and //None// is the
229
229
safest default.
230
230
231
-
**Observe**: Phabricator will observe this repository and regularly fetch any
231
+
**Observe**: Phorge will observe this repository and regularly fetch any
232
232
changes made to it to a local read-only copy.
233
233
234
234
You can not observe builtin URIs because reading a repository from itself
···
240
240
other URI out of //Read/Write// mode first.
241
241
242
242
WARNING: If you observe a remote repository, the entire state of the working
243
-
copy that Phabricator maintains will be deleted and replaced with the state of
244
-
the remote. If some changes are present only in Phabricator's working copy,
243
+
copy that Phorge maintains will be deleted and replaced with the state of
244
+
the remote. If some changes are present only in Phorge's working copy,
245
245
they will be unrecoverably destroyed.
246
246
247
-
**Mirror**: Phabricator will push any changes made to this repository to the
247
+
**Mirror**: Phorge will push any changes made to this repository to the
248
248
remote URI, keeping a read-only mirror hosted at that URI up to date.
249
249
250
250
This works for both observed and hosted repositories.
···
253
253
to mirror a repository to itself.
254
254
255
255
It is possible to mirror a repository to another repository that is also
256
-
hosted by Phabricator by adding that other repository's URI, although this is
256
+
hosted by Phorge by adding that other repository's URI, although this is
257
257
silly and probably very rarely of any use.
258
258
259
259
WARNING: If you mirror to a remote repository, the entire state of that remote
260
-
will be replaced with the state of the working copy Phabricator maintains. If
260
+
will be replaced with the state of the working copy Phorge maintains. If
261
261
some changes are present only in the remote, they will be unrecoverably
262
262
destroyed.
263
263
264
-
**None**: Phabricator will not fetch changes from or push changes to this URI.
264
+
**None**: Phorge will not fetch changes from or push changes to this URI.
265
265
For builtin URIs, it will not let users fetch changes from or push changes to
266
266
this URI.
267
267
268
268
You can use this mode to turn off an Observe URI after an import, stop a Mirror
269
269
URI from updating, or to add URIs that you're only using to customize which
270
-
clone URIs are displayed to the user but don't want Phabricator to interact
270
+
clone URIs are displayed to the user but don't want Phorge to interact
271
271
with directly.
272
272
273
-
**Read Only**: Phabricator will serve the repository from this URI in read-only
273
+
**Read Only**: Phorge will serve the repository from this URI in read-only
274
274
mode. Users will be able to fetch from it but will not be able to push to it.
275
275
276
-
Because Phabricator must be able to serve the repository from URIs configured
276
+
Because Phorge must be able to serve the repository from URIs configured
277
277
in this mode, this option is only available for builtin URIs.
278
278
279
-
**Read/Write**: Phabricator will serve the repository from this URI in
279
+
**Read/Write**: Phorge will serve the repository from this URI in
280
280
read/write mode. Users will be able to fetch from it and push to it.
281
281
282
282
URIs can not be set into this mode if another URI is set to //Observe// mode,
···
284
284
observed remote copy and the hosted local copy. Take the other URI out of
285
285
//Observe// mode first.
286
286
287
-
Because Phabricator must be able to serve the repository from URIs configured
287
+
Because Phorge must be able to serve the repository from URIs configured
288
288
in this mode, this option is only available for builtin URIs.
289
289
290
290
···
293
293
294
294
This section details the available **Display Type** options for URIs.
295
295
296
-
**Default**: Phabricator will guess the correct option for the URI. It
296
+
**Default**: Phorge will guess the correct option for the URI. It
297
297
guesses based on the configured **I/O Type** and whether the URI is
298
298
**builtin** or not.
299
299
···
315
315
316
316
Continue by:
317
317
318
-
- configuring Phabricator to host repositories with
318
+
- configuring Phorge to host repositories with
319
319
@{article:Diffusion User Guide: Repository Hosting}.
+2
-2
src/docs/user/userguide/diviner.diviner
+2
-2
src/docs/user/userguide/diviner.diviner
···
8
8
9
9
Diviner is an application for creating technical documentation.
10
10
11
-
This article is maintained in a text file in the Phabricator repository and
11
+
This article is maintained in a text file in the Phorge repository and
12
12
generated into the display document you are currently reading using Diviner.
13
13
14
14
Beyond generating articles, Diviner can also analyze source code and generate
···
20
20
21
21
To generate documentation, run:
22
22
23
-
phabricator/ $ ./bin/diviner generate --book <book>
23
+
phorge/ $ ./bin/diviner generate --book <book>
24
24
25
25
26
26
Diviner ".book" Files
+1
-1
src/docs/user/userguide/drydock.diviner
+1
-1
src/docs/user/userguide/drydock.diviner
···
256
256
- understanding Drydock security concerns with
257
257
@{article:Drydock User Guide: Security}; or
258
258
- learning about blueprints in @{article:Drydock Blueprints}; or
259
-
- allowing Phabricator to write to repositories with
259
+
- allowing Phorge to write to repositories with
260
260
@{article:Drydock User Guide: Repository Automation}.
+4
-4
src/docs/user/userguide/drydock_hosts.diviner
+4
-4
src/docs/user/userguide/drydock_hosts.diviner
···
41
41
properly with any software you need, and have tools like `git`, `hg` or `svn`
42
42
that may be required to interact with working copies.
43
43
44
-
You do **not** need to install PHP, arcanist, or Phabricator on the
44
+
You do **not** need to install PHP, arcanist, or Phorge on the
45
45
hosts unless you are specifically running `arc` commands.
46
46
47
47
**You must configure authentication.** Drydock also does not handle credentials
48
48
for VCS operations. If you're interacting with repositories hosted on
49
-
Phabricator, the simplest way to set this up is something like this:
49
+
Phorge, the simplest way to set this up is something like this:
50
50
51
-
- Create a new bot user in Phabricator.
51
+
- Create a new bot user in Phorge.
52
52
- In {nav Settings > SSH Public Keys}, add a public key or generate a
53
53
keypair.
54
54
- Put the private key on your build hosts as `~/.ssh/id_rsa` for whatever
55
55
user you're connecting with.
56
56
57
-
This will let processes on the host access Phabricator as the bot user, and
57
+
This will let processes on the host access Phorge as the bot user, and
58
58
use the bot user's permissions to pull and push changes.
59
59
60
60
If you're using hosted repositories from an external service, you can follow
+1
-1
src/docs/user/userguide/drydock_quick_start.diviner
+1
-1
src/docs/user/userguide/drydock_quick_start.diviner
···
30
30
for `builder` so it can pull and push any repositories you want to operate
31
31
on.
32
32
33
-
If your repository and/or staging area are hosted in Phabricator, you may want
33
+
If your repository and/or staging area are hosted in Phorge, you may want
34
34
to create a corresponding bot account so you can add keys and give it
35
35
permissions.
36
36
+3
-3
src/docs/user/userguide/drydock_repository_automation.diviner
+3
-3
src/docs/user/userguide/drydock_repository_automation.diviner
···
1
1
@title Drydock User Guide: Repository Automation
2
2
@group userguide
3
3
4
-
Configuring repository automation so Phabricator can push commits.
4
+
Configuring repository automation so Phorge can push commits.
5
5
6
6
7
7
Overview
···
11
11
in this document are not yet available. This feature as a whole is a prototype.
12
12
13
13
By configuring Drydock and Diffusion appropriately, you can enable **Repository
14
-
Automation** for a repository. This will allow Phabricator to make changes
14
+
Automation** for a repository. This will allow Phorge to make changes
15
15
to the repository.
16
16
17
17
···
25
25
Security
26
26
========
27
27
28
-
Configuring repository automation amounts to telling Phabricator where it
28
+
Configuring repository automation amounts to telling Phorge where it
29
29
should perform working copy operations (like merges, cherry-picks and pushes)
30
30
when doing writes.
31
31
+13
-13
src/docs/user/userguide/drydock_security.diviner
+13
-13
src/docs/user/userguide/drydock_security.diviner
···
14
14
For example, running unit tests on Drydock normally involves running relatively
15
15
untrusted code (it often has a single author and has not yet been reviewed)
16
16
that needs very few capabilities (generally, it only needs to be able to report
17
-
results back to Phabricator). In contrast, automating merge requests on Drydock
17
+
results back to Phorge). In contrast, automating merge requests on Drydock
18
18
involves running trusted code that needs more access (it must be able to write
19
19
to repositories).
20
20
···
61
61
| Custom | Special Requirements | Use multiple pools.
62
62
| Absolute | Special Requirements | Completely isolate all resources.
63
63
64
-
**Zero Isolation**: Run Drydock operations on the same host that Phabricator
65
-
runs on. This is only suitable for developing or testing Phabricator. Any
66
-
Drydock operation can potentially compromise Phabricator. It is intentionally
64
+
**Zero Isolation**: Run Drydock operations on the same host that Phorge
65
+
runs on. This is only suitable for developing or testing Phorge. Any
66
+
Drydock operation can potentially compromise Phorge. It is intentionally
67
67
difficult to configure Drydock to operate in this mode. Running Drydock
68
-
operations on the Phabricator host is strongly discouraged.
68
+
operations on the Phorge host is strongly discouraged.
69
69
70
70
**Low Isolation**: Designate a separate Drydock host and run Drydock
71
71
operations on it. This is suitable for small installs and provides a reasonable
···
105
105
Attackers have three primary targets:
106
106
107
107
- capturing hosts;
108
-
- compromising Phabricator; and
108
+
- compromising Phorge; and
109
109
- compromising the integrity of other Drydock processes.
110
110
111
111
**Attacks against hosts** are the least sophisticated. In this scenario, an
112
112
attacker wants to run a program like a Bitcoin miner or botnet client on
113
113
hardware that they aren't paying for or which can't be traced to them. They
114
114
write a "unit test" or which launches this software, then send a revision
115
-
containing this "unit test" for review. If Phabricator is configured to
115
+
containing this "unit test" for review. If Phorge is configured to
116
116
automatically run tests on new revisions, it may execute automatically and give
117
117
the attacker access to computing resources they did not previously control and
118
118
which can not easily be traced back to them.
···
125
125
create a "Trusted Contributors" project and only run tests if a revision author
126
126
is a member of the project.
127
127
128
-
**Attacks against Phabricator** are more sophisticated. In this scenario, an
129
-
attacker tries to compromise Phabricator itself (for example, to make themselves
128
+
**Attacks against Phorge** are more sophisticated. In this scenario, an
129
+
attacker tries to compromise Phorge itself (for example, to make themselves
130
130
an administrator or gain access to an administrator account).
131
131
132
-
This is made possible if Drydock is running on the same host as Phabricator or
133
-
runs on a privileged subnet with access to resources like Phabricator database
132
+
This is made possible if Drydock is running on the same host as Phorge or
133
+
runs on a privileged subnet with access to resources like Phorge database
134
134
hosts. Most installs should be concerned about this attack.
135
135
136
136
The best way to defuse this attack is to run Drydock processes on a separate
137
137
host which is not on a privileged subnet. For example, use a
138
138
`build.mycompany.com` host or pool for Drydock processes, separate from your
139
-
`phabricator.mycompany.com` host or pool.
139
+
`phorge.mycompany.com` host or pool.
140
140
141
141
Even if the host is not privileged, many Drydock processes have some level of
142
142
privilege (enabling them to clone repositories, or report test results back to
143
-
Phabricator). Be aware that tests can hijack credentials they are run with,
143
+
Phorge). Be aware that tests can hijack credentials they are run with,
144
144
and potentially hijack credentials given to other processes on the same hosts.
145
145
You should use credentials with a minimum set of privileges and assume all
146
146
processes on a host have the highest level of access that any process on the
+17
-17
src/docs/user/userguide/events.diviner
+17
-17
src/docs/user/userguide/events.diviner
···
1
1
@title Events User Guide: Installing Event Listeners
2
2
@group userguide
3
3
4
-
Using Phabricator event listeners to customize behavior.
4
+
Using Phorge event listeners to customize behavior.
5
5
6
6
= Overview =
7
7
···
9
9
system is strongly discouraged. We have been removing events since 2013 and
10
10
will continue to remove events in the future.
11
11
12
-
Phabricator and Arcanist allow you to install custom runtime event listeners
12
+
Phorge and Arcanist allow you to install custom runtime event listeners
13
13
which can react to certain things happening (like a Maniphest Task being edited
14
14
or a user creating a new Differential Revision) and run custom code to perform
15
15
logging, synchronize with other systems, or modify workflows.
16
16
17
-
These listeners are PHP classes which you install beside Phabricator or
18
-
Arcanist, and which Phabricator loads at runtime and runs in-process. They
17
+
These listeners are PHP classes which you install beside Phorge or
18
+
Arcanist, and which Phorge loads at runtime and runs in-process. They
19
19
require somewhat more effort upfront than simple configuration switches, but are
20
20
the most direct and powerful way to respond to events.
21
21
22
-
= Installing Event Listeners (Phabricator) =
22
+
= Installing Event Listeners (Phorge) =
23
23
24
-
To install event listeners in Phabricator, follow these steps:
24
+
To install event listeners in Phorge, follow these steps:
25
25
26
26
- Write a listener class which extends @{class@arcanist:PhutilEventListener}.
27
27
- Add it to a libphutil library, or create a new library (for instructions,
28
-
see @{article@phabcontrib:Adding New Classes}.
29
-
- Configure Phabricator to load the library by adding it to `load-libraries`
30
-
in the Phabricator config.
31
-
- Configure Phabricator to install the event listener by adding the class
32
-
name to `events.listeners` in the Phabricator config.
28
+
see @{article@contrib:Adding New Classes}.
29
+
- Configure Phorge to load the library by adding it to `load-libraries`
30
+
in the Phorge config.
31
+
- Configure Phorge to install the event listener by adding the class
32
+
name to `events.listeners` in the Phorge config.
33
33
34
34
You can verify your listener is registered in the "Events" tab of DarkConsole.
35
35
It should appear at the top under "Registered Event Listeners". You can also
···
42
42
43
43
- Write a listener class which extends @{class@arcanist:PhutilEventListener}.
44
44
- Add it to a libphutil library, or create a new library (for instructions,
45
-
see @{article@phabcontrib:Adding New Classes}.
46
-
- Configure Phabricator to load the library by adding it to `load`
45
+
see @{article@contrib:Adding New Classes}.
46
+
- Configure Phorge to load the library by adding it to `load`
47
47
in the Arcanist config (e.g., `.arcconfig`, or user/global config).
48
48
- Configure Arcanist to install the event listener by adding the class
49
49
name to `events.listeners` in the Arcanist config.
···
54
54
55
55
= Example Listener =
56
56
57
-
Phabricator includes an example event listener,
57
+
Phorge includes an example event listener,
58
58
@{class:PhabricatorExampleEventListener}, which may be useful as a starting
59
59
point in developing your own listeners. This listener listens for a test
60
60
event that is emitted by the script `scripts/util/emit_test_event.php`.
···
80
80
81
81
= Available Events =
82
82
83
-
You can find a list of all Phabricator events in @{class:PhabricatorEventType}.
83
+
You can find a list of all Phorge events in @{class:PhabricatorEventType}.
84
84
85
85
== All Events ==
86
86
···
184
184
185
185
If you're having problems with your listener, try these steps:
186
186
187
-
- If you're getting an error about Phabricator being unable to find the
187
+
- If you're getting an error about Phorge being unable to find the
188
188
listener class, make sure you've added it to a libphutil library and
189
-
configured Phabricator to load the library with `load-libraries`.
189
+
configured Phorge to load the library with `load-libraries`.
190
190
- Make sure the listener is registered. It should appear in the "Events" tab
191
191
of DarkConsole. If it's not there, you may have forgotten to add it to
192
192
`events.listeners`.
+1
-1
src/docs/user/userguide/external_editor.diviner
+1
-1
src/docs/user/userguide/external_editor.diviner
···
30
30
Mapping Repositories
31
31
====================
32
32
33
-
When you open a file in an external editor, Phabricator needs to be able to
33
+
When you open a file in an external editor, Phorge needs to be able to
34
34
build a URI which includes the correct absolute path on disk to the local
35
35
version of the file, including the repository directory.
36
36
+6
-6
src/docs/user/userguide/forms.diviner
+6
-6
src/docs/user/userguide/forms.diviner
···
1
1
@title User Guide: Customizing Forms
2
2
@group userguide
3
3
4
-
Guide to prefilling and customizing forms in Phabricator applications.
4
+
Guide to prefilling and customizing forms in Phorge applications.
5
5
6
6
Overview
7
7
========
···
194
194
Using {nav Mark as "Create" Form} from the detail page for a form
195
195
configuration, you can mark a form to appear in the create menu.
196
196
197
-
When a user visits the application, Phabricator finds all the form
197
+
When a user visits the application, Phorge finds all the form
198
198
configurations that are:
199
199
200
200
- marked as "create" forms; and
201
201
- visible to the user based on policy configuration; and
202
202
- enabled.
203
203
204
-
If there is only one such form, Phabricator renders a single "Create" button.
204
+
If there is only one such form, Phorge renders a single "Create" button.
205
205
(If there are zero forms, it renders the button but disables it.)
206
206
207
-
If there are several such forms, Phabricator renders a dropdown which allows
207
+
If there are several such forms, Phorge renders a dropdown which allows
208
208
the user to choose between them.
209
209
210
210
You can reorder these forms by returning to the configuration list and using
···
446
446
//after// creating it and open the policies; or
447
447
- regardless of their edit form access, they can use the Conduit API to
448
448
change the task policy; or
449
-
- regardless of any policy controls in Phabricator, they can screenshot,
449
+
- regardless of any policy controls in Phorge, they can screenshot,
450
450
print, or forward email about the task to anyone; or
451
451
- regardless of any technical controls in any software, they can decline to
452
452
report the issue to you in the first place and sell it on the black market
···
473
473
474
474
We run an open source project with a small core team, a moderate number
475
475
of regular contributors, and a large public userbase. Access to the upstream
476
-
Phabricator instance is open to the public.
476
+
Phorge instance is open to the public.
477
477
478
478
Although our product is fairly technical, we receive many bug reports and
479
479
feature requests which are of very poor quality. Some users also ignore all the
+5
-5
src/docs/user/userguide/harbormaster.diviner
+5
-5
src/docs/user/userguide/harbormaster.diviner
···
10
10
understand what it can and can not do and what to expect in the future.
11
11
12
12
The Harbormaster application provides build and continuous integration support
13
-
for Phabricator.
13
+
for Phorge.
14
14
15
15
Harbormaster is not a mature application. You should expect it to have major
16
16
missing capabilities and to change substantially over time. The current version
···
95
95
- Have the build step "Wait for Message" after the external system is
96
96
notified.
97
97
- Write custom code on the build server to respond to the request, run a
98
-
build, then report the results back to Phabricator by calling the
98
+
build, then report the results back to Phorge by calling the
99
99
`harbormaster.sendmessage` Conduit API.
100
100
101
101
You'll need to write a nontrivial amount of code to get this working today.
···
149
149
The build system can then interact with this copy using normal VCS commands.
150
150
This is simpler to configure, use, troubleshoot and work with than `arc patch`.
151
151
152
-
With `arc patch`, the build system downloads patches from Phabricator and
152
+
With `arc patch`, the build system downloads patches from Phorge and
153
153
applies them to a local working copy. This is more complex and more error-prone
154
154
than staging areas.
155
155
···
201
201
build.
202
202
203
203
**`arc patch`**: You can also have the build system pull changes out of
204
-
Phabricator as patches and apply them with `arc patch`. This mechanism is the
204
+
Phorge as patches and apply them with `arc patch`. This mechanism is the
205
205
most complex to configure and debug, and is much less reliable than using
206
206
staging areas. It is not recommended.
207
207
···
225
225
In particular, you can run manual builds in the foreground from the CLI to see
226
226
more details about what they're doing:
227
227
228
-
phabricator/ $ ./bin/harbormaster build D123 --plan 456 --trace
228
+
phorge/ $ ./bin/harbormaster build D123 --plan 456 --trace
229
229
230
230
This may help you understand or debug issues with a build plan.
+1
-1
src/docs/user/userguide/herald.diviner
+1
-1
src/docs/user/userguide/herald.diviner
···
13
13
14
14
One way to think about Herald is that it is a lot like the mail rules you can
15
15
set up in most email clients to organize mail based on "To", "Subject", etc.
16
-
Herald works very similarly, but operates on Phabricator objects (like revisions
16
+
Herald works very similarly, but operates on Phorge objects (like revisions
17
17
and commits) instead of emails.
18
18
19
19
For example, you can write a personal rule like this which triggers on tasks:
+1
-1
src/docs/user/userguide/jump.diviner
+1
-1
src/docs/user/userguide/jump.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator's global search bar automatically interprets certain commands as
9
+
Phorge's global search bar automatically interprets certain commands as
10
10
shortcuts to make it easy to navigate to specific places.
11
11
12
12
To use these shortcuts, just type them into the global search bar in the main
+2
-12
src/docs/user/userguide/legalpad.diviner
+2
-12
src/docs/user/userguide/legalpad.diviner
···
36
36
policy documents or other documents which do not require a signature).
37
37
38
38
**Require Signature** This field allows you to create a document which all of
39
-
your users must sign before they can use Phabricator, like a terms of service
39
+
your users must sign before they can use Phorge, like a terms of service
40
40
document. See "Use Case: Terms of Service" below for details. These documents
41
41
must be signable by individuals.
42
42
···
84
84
as you save your changes, so that will give you a sense of the workflow).
85
85
86
86
Note that although users who have not signed all of the required documents can
87
-
not use most Phabricator functions, they can browse other Legalpad documents
87
+
not use most Phorge functions, they can browse other Legalpad documents
88
88
that they have permission to see. This allows a terms document to be
89
89
supplemented with additional policy or guideline documents that users are free
90
90
to review before agreeing to the terms.
···
123
123
You can optionally add notes about why a user is exempt from signing a document.
124
124
To review the notes later (and see who added the exemption), click the colored
125
125
asterisk in the list view.
126
-
127
-
128
-
Roadmap
129
-
========
130
-
131
-
You can find discussion about the Legalpad roadmap here:
132
-
133
-
https://secure.phabricator.com/T5505
134
-
135
-
If there are features you'd like to see, let us know.
+5
-5
src/docs/user/userguide/mail_rules.diviner
+5
-5
src/docs/user/userguide/mail_rules.diviner
···
1
-
@title User Guide: Managing Phabricator Email
1
+
@title User Guide: Managing Phorge Email
2
2
@group userguide
3
3
4
-
How to effectively manage Phabricator email notifications.
4
+
How to effectively manage Phorge email notifications.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator uses email as a major notification channel, but the amount of email
9
+
Phorge uses email as a major notification channel, but the amount of email
10
10
it sends can seem overwhelming if you're working on an active team. This
11
11
document discusses some strategies for managing email.
12
12
···
29
29
to move mail from Differential, Maniphest and Herald to separate folders will
30
30
vastly simplify mail management.
31
31
32
-
Phabricator also adds mail headers (see below) which can allow you to write
32
+
Phorge also adds mail headers (see below) which can allow you to write
33
33
more sophisticated mail rules.
34
34
35
35
Mail Headers
36
36
============
37
37
38
-
Phabricator sends various information in mail headers that can be useful in
38
+
Phorge sends various information in mail headers that can be useful in
39
39
crafting rules to route and manage mail. To see a full list of headers, use
40
40
the "View Raw Message" feature in your mail client.
41
41
+14
-14
src/docs/user/userguide/multi_factor_auth.diviner
+14
-14
src/docs/user/userguide/multi_factor_auth.diviner
···
1
1
@title User Guide: Multi-Factor Authentication
2
2
@group userguide
3
3
4
-
Explains how multi-factor authentication works in Phabricator.
4
+
Explains how multi-factor authentication works in Phorge.
5
5
6
6
Overview
7
7
========
···
30
30
Usually, this means you'll receive an SMS with a authorization code on your
31
31
phone, or you'll open an app on your phone which will show you a authorization
32
32
code or ask you to confirm the action. If you're given a authorization code,
33
-
you'll enter it into Phabricator.
33
+
you'll enter it into Phorge.
34
34
35
-
If you're logging in, Phabricator will log you in after you enter the code.
35
+
If you're logging in, Phorge will log you in after you enter the code.
36
36
37
-
If you're taking a sensitive action, Phabricator will sometimes put your
37
+
If you're taking a sensitive action, Phorge will sometimes put your
38
38
account in "high security" mode for a few minutes. In this mode, you can take
39
39
sensitive actions like changing passwords or SSH keys freely, without
40
40
entering any more credentials.
···
64
64
===============================
65
65
66
66
TOTP stands for "Time-based One-Time Password". This factor operates by having
67
-
you enter authorization codes from your mobile phone into Phabricator. The codes
67
+
you enter authorization codes from your mobile phone into Phorge. The codes
68
68
change every 30 seconds, so you will need to have your phone with you in order
69
69
to enter them.
70
70
···
77
77
application, so check any in-house documentation for details. In general, any
78
78
TOTP application should work properly.
79
79
80
-
After you've downloaded the application onto your phone, use the Phabricator
80
+
After you've downloaded the application onto your phone, use the Phorge
81
81
settings panel to add a factor to your account. You'll be prompted to scan a
82
82
QR code, and then read an authorization code from your phone and type it into
83
-
Phabricator.
83
+
Phorge.
84
84
85
85
Later, when you need to authenticate, you'll follow this same process: launch
86
-
the application, read the authorization code, and type it into Phabricator.
86
+
the application, read the authorization code, and type it into Phorge.
87
87
This will prove you have your phone.
88
88
89
-
Don't lose your phone! You'll need it to log into Phabricator in the future.
89
+
Don't lose your phone! You'll need it to log into Phorge in the future.
90
90
91
91
92
92
Factor: SMS
···
123
123
Administration: Configuration
124
124
=============================
125
125
126
-
New Phabricator installs start without any multi-factor providers enabled.
126
+
New Phorge installs start without any multi-factor providers enabled.
127
127
Users won't be able to add new factors until you set up multi-factor
128
128
authentication by configuring at least one provider.
129
129
···
187
187
188
188
```lang=console
189
189
# Strip all factors from a given user account.
190
-
phabricator/ $ ./bin/auth strip --user <username> --all-types
190
+
phorge/ $ ./bin/auth strip --user <username> --all-types
191
191
```
192
192
193
193
You can run `bin/auth help strip` for more detail and all available flags and
···
198
198
199
199
```lang=console
200
200
# Show supported factor types.
201
-
phabricator/ $ ./bin/auth list-factors
201
+
phorge/ $ ./bin/auth list-factors
202
202
```
203
203
204
204
Once you've identified the factor types you want to strip, you can strip
···
207
207
208
208
```lang=console
209
209
# Strip all SMS and TOTP factors for a user.
210
-
phabricator/ $ ./bin/auth strip --user <username> --type sms --type totp
210
+
phorge/ $ ./bin/auth strip --user <username> --type sms --type totp
211
211
```
212
212
213
213
The `bin/auth strip` command can also selectively strip factors for certain
···
218
218
219
219
```lang=console
220
220
# Strip all factors for a particular provider.
221
-
phabricator/ $ ./bin/auth strip --user <username> --provider <providerPHID>
221
+
phorge/ $ ./bin/auth strip --user <username> --provider <providerPHID>
222
222
```
+3
-3
src/docs/user/userguide/multimeter.diviner
+3
-3
src/docs/user/userguide/multimeter.diviner
···
9
9
IMPORTANT: This document describes a prototype application.
10
10
11
11
Multimeter is a sampling profiler that can give you coarse information about
12
-
Phabricator resource usage. In particular, it can help quickly identify sources
12
+
Phorge resource usage. In particular, it can help quickly identify sources
13
13
of load, like bots or scripts which are making a very large number of requests.
14
14
15
15
Configuring and Using Multimeter
···
26
26
Using Multimeter
27
27
================
28
28
29
-
Multimeter shows you what Phabricator has spent time doing recently. By
29
+
Multimeter shows you what Phorge has spent time doing recently. By
30
30
looking at the samples it collects, you can identify major sources of load
31
31
or resource use, whether they are specific users, pages, subprocesses, or
32
32
other types of activity.
···
36
36
that are making too many calls), or report specific, actionable issues to the
37
37
upstream for resolution.
38
38
39
-
The main screen of Multimeter shows you everything Phabricator has spent
39
+
The main screen of Multimeter shows you everything Phorge has spent
40
40
resources on recently, broken down by action type. Categories are folded up
41
41
by default, with "(All)" labels.
42
42
+6
-6
src/docs/user/userguide/phame.diviner
+6
-6
src/docs/user/userguide/phame.diviner
···
7
7
========
8
8
9
9
Phame is a simple platform for writing blogs and blog posts. Content published
10
-
through Phame is integrated with other Phabricator applications (like Feed,
10
+
through Phame is integrated with other Phorge applications (like Feed,
11
11
Herald and Dashboards).
12
12
13
13
You can use Phame to write and publish posts on any topic. You might use it to
14
14
make announcements, hold discussions, or provide progress updates about a
15
15
project.
16
16
17
-
In the upstream, we use several Phame blogs to discuss changes to Phabricator,
17
+
In the upstream, we use several Phame blogs to discuss changes to Phorge,
18
18
make company announcements, photograph food, and provide visionary thought
19
19
leadership.
20
20
···
61
61
Using Phame With Other Applications
62
62
===================================
63
63
64
-
Phame integrates with other Phabricator applications, so you can do a few
64
+
Phame integrates with other Phorge applications, so you can do a few
65
65
interesting things:
66
66
67
67
**Dashboards**: You can create a dashboard panel which shows posts on a
···
90
90
> https://blog.phacility.com/
91
91
92
92
External blogs are public (they do not require login) and are only supported if
93
-
your Phabricator install is also public. You can make an install public by
93
+
your Phorge install is also public. You can make an install public by
94
94
adjusting `policy.allow-public` in Config, but make sure you understand the
95
95
effects of adjusting this setting before touching it.
96
96
···
100
100
- **View Policy**: Set the "View Policy" for the blog to "Public". Blogs must
101
101
have a public view policy to be served from an external domain.
102
102
- **Full Domain URI**: Set this to the full URI of your external domain,
103
-
like `https://blog.mycompany.com/`. When users visit this URI, Phabricator
103
+
like `https://blog.mycompany.com/`. When users visit this URI, Phorge
104
104
will serve the blog to them.
105
105
106
106
To configure the blog's navigation breadcrumbs so that it links back to the
···
115
115
116
116
- {nav My Company > Blog Name}
117
117
118
-
Finally, configure DNS for `blog.mycompany.com` to point at Phabricator.
118
+
Finally, configure DNS for `blog.mycompany.com` to point at Phorge.
119
119
120
120
If everything is set up properly, visiting `blog.mycompany.com` should now
121
121
serve your blog.
+5
-5
src/docs/user/userguide/projects.diviner
+5
-5
src/docs/user/userguide/projects.diviner
···
8
8
9
9
NOTE: This document is only partially complete.
10
10
11
-
Phabricator projects are flexible, general-purpose groups of objects that you
11
+
Phorge projects are flexible, general-purpose groups of objects that you
12
12
can use to organize information. Projects have some basic information like
13
13
a name and an icon, and may optionally have members.
14
14
···
37
37
otherwise could not. Likewise, removing projects does not affect visibility.
38
38
39
39
If you're familiar with other software that works differently, this may be
40
-
unexpected, but the rule in Phabricator is simple: **adding and removing
40
+
unexpected, but the rule in Phorge is simple: **adding and removing
41
41
projects never affects policies.**
42
42
43
43
Note that you //can// write policy rules which restrict capabilities to members
···
124
124
link to a Conpherence if you have a chatroom for a project.
125
125
126
126
**Link to External Resources**: You can link to external resources outside
127
-
of Phabricator if you have other pages which are relevant to a project.
127
+
of Phorge if you have other pages which are relevant to a project.
128
128
129
129
**Set Workboard as Default**: For projects that are mostly used to organize
130
130
tasks, change the default item to the workboard instead of the profile to get
···
278
278
object. This is an explicit product design choice aimed at reducing the
279
279
complexity of policy management.
280
280
281
-
Phabricator projects are a flexible, general-purpose, freeform tool. This is a
281
+
Phorge projects are a flexible, general-purpose, freeform tool. This is a
282
282
good match for many organizational use cases, but a very poor match for
283
283
policies. It is important that policies be predictable and rigid, because the
284
284
cost of making a mistake with policies is high (inadvertent disclosure of
285
285
private information).
286
286
287
-
In Phabricator, each object (like a task) can be tagged with multiple projects.
287
+
In Phorge, each object (like a task) can be tagged with multiple projects.
288
288
This is important in a flexible organizational tool, but is a liability in a
289
289
policy tool.
290
290
+1
-1
src/docs/user/userguide/prototypes.diviner
+1
-1
src/docs/user/userguide/prototypes.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator includes //prototype applications//, which are applications in an
9
+
Phorge includes //prototype applications//, which are applications in an
10
10
early stage of development.
11
11
12
12
When we begin working on a new application, we usually implement it as a
+6
-6
src/docs/user/userguide/remarkup.diviner
+6
-6
src/docs/user/userguide/remarkup.diviner
···
6
6
7
7
= Overview =
8
8
9
-
Phabricator uses a lightweight markup language called "Remarkup", similar to
9
+
Phorge uses a lightweight markup language called "Remarkup", similar to
10
10
other lightweight markup languages like Markdown and Wiki markup.
11
11
12
12
This document describes how to format text using Remarkup.
···
331
331
332
332
= Linking URIs =
333
333
334
-
URIs are automatically linked: http://phabricator.org/
334
+
URIs are automatically linked: http://phorge.it/
335
335
336
336
If you have a URI with problematic characters in it, like
337
337
"`http://comma.org/,`", you can surround it with angle brackets:
···
341
341
This will force the parser to consume the whole URI: <http://comma.org/,>
342
342
343
343
You can also use create named links, where you choose the displayed text. These
344
-
work within Phabricator or on the internet at large:
344
+
work within Phorge or on the internet at large:
345
345
346
346
[[/herald/transcript/ | Herald Transcripts]]
347
347
[[http://www.boring-legal-documents.com/ | exciting legal documents]]
···
352
352
353
353
= Linking to Objects =
354
354
355
-
You can link to Phabricator objects, such as Differential revisions, Diffusion
355
+
You can link to Phorge objects, such as Differential revisions, Diffusion
356
356
commits and Maniphest tasks, by mentioning the name of an object:
357
357
358
358
D123 # Link to Differential revision D123
···
366
366
367
367
T123#412 # Link to comment id #412 of task T123
368
368
369
-
See the Phabricator configuration setting `remarkup.ignored-object-names` to
369
+
See the Phorge configuration setting `remarkup.ignored-object-names` to
370
370
modify this behavior.
371
371
372
372
= Embedding Objects
···
501
501
502
502
By default, the font used to create the text for the meme is `tuffy.ttf`. For
503
503
the more authentic feel of `impact.ttf`, you simply have to place the Impact
504
-
TrueType font in the Phabricator subfolder `/resources/font/`. If Remarkup
504
+
TrueType font in the Phorge subfolder `/resources/font/`. If Remarkup
505
505
detects the presence of `impact.ttf`, it will automatically use it.
506
506
507
507
= Mentioning Users =
+2
-2
src/docs/user/userguide/reviews_vs_audit.diviner
+2
-2
src/docs/user/userguide/reviews_vs_audit.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator supports two similar but separate code review workflows: "review"
9
+
Phorge supports two similar but separate code review workflows: "review"
10
10
and "audit".
11
11
12
12
Review occurs in **Differential**, before changes are published. You can learn
···
111
111
by the arguments above (or work on a team that is unswayed), audits provide
112
112
some of the benefits of review with less friction:
113
113
114
-
- Audits are driven entirely by Phabricator: users do not need to install
114
+
- Audits are driven entirely by Phorge: users do not need to install
115
115
`arc`.
116
116
- Audits require little adjustment to existing workflows and little training.
117
117
- Audits are completely nonblocking, and send fewer notifications than review.
+5
-5
src/docs/user/userguide/search.diviner
+5
-5
src/docs/user/userguide/search.diviner
···
1
1
@title Search User Guide
2
2
@group userguide
3
3
4
-
Introduction to searching for documents in Phabricator.
4
+
Introduction to searching for documents in Phorge.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator has two major ways to search for documents and objects (like tasks,
9
+
Phorge has two major ways to search for documents and objects (like tasks,
10
10
code reviews, users, wiki documents, and so on): **global search** and
11
11
**application search**.
12
12
···
34
34
will find matching tasks, commits, wiki documents, users, etc. You can use the
35
35
dropdown to the left of the search box to select a different search scope.
36
36
37
-
If you choose the **Current Application** scope, Phabricator will search for
37
+
If you choose the **Current Application** scope, Phorge will search for
38
38
open documents in the current application. For example, if you're in Maniphest
39
39
and run a search, you'll get matching tasks. If you're in Phriction and run a
40
40
search, you'll get matching wiki documents.
41
41
42
42
Some pages (like the 404 page) don't belong to an application, or belong to an
43
43
application which doesn't have any searchable documents. In these cases,
44
-
Phabricator will search all documents.
44
+
Phorge will search all documents.
45
45
46
46
To quickly **jump to an object** like a task, enter the object's ID in the
47
47
global search box and search for it. For example, you can enter `T123` or
···
53
53
set. You can also select **Advanced Search** from the dropdown menu to jump
54
54
here immediately, or press return in the search box without entering a query.
55
55
56
-
This interface supports standard Phabricator search and filtering features,
56
+
This interface supports standard Phorge search and filtering features,
57
57
like **saved queries** and **typeaheads**. See below for more details on using
58
58
these features.
59
59
+2
-2
src/docs/user/userguide/spaces.diviner
+2
-2
src/docs/user/userguide/spaces.diviner
···
21
21
enemies at the company, that she might use the element of surprise to later
22
22
expand her domain.
23
23
24
-
Phabricator's access control policies are generally powerful enough to handle
24
+
Phorge's access control policies are generally powerful enough to handle
25
25
these use cases on their own, but applying the same policy to a large group
26
26
of objects requires a lot of effort and is error-prone.
27
27
···
138
138
Some information is shared between spaces, so they do not completely isolate
139
139
users from other activity on the install. This section discusses limitations
140
140
of the isolation model. Most of these limitations are intrinsic to the policy
141
-
model Phabricator uses.
141
+
model Phorge uses.
142
142
143
143
**Shared IDs**: Spaces do not have unique object IDs: there is only one `T1`,
144
144
not a separate one in each space. It can be moved between spaces, but `T1`
+3
-3
src/docs/user/userguide/tone.diviner
+3
-3
src/docs/user/userguide/tone.diviner
···
1
1
@title User Guide: Project Tone
2
2
@group userguide
3
3
4
-
Explains why Phabricator uses a lighthearted tone.
4
+
Explains why Phorge uses a lighthearted tone.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator uses a lighthearted tone in documentation and some interfaces, and
9
+
Phorge uses a lighthearted tone in documentation and some interfaces, and
10
10
includes some features which primarily exist to add flavor or make things
11
11
sillier.
12
12
···
28
28
documentation.)
29
29
30
30
If you don't like a piece of flavor because it creates legitimate difficulty or
31
-
confusion for you or your users and makes it harder to use Phabricator, let us
31
+
confusion for you or your users and makes it harder to use Phorge, let us
32
32
know. We don't intend flavor or tone to get in the way of usability, and can
33
33
sometimes take a joke too far (particularly for users who don't speak English
34
34
natively).
+1
-1
src/docs/user/userguide/unlocking.diviner
+1
-1
src/docs/user/userguide/unlocking.diviner
···
6
6
Overview
7
7
========
8
8
9
-
Phabricator tries to make it difficult for users to lock themselves out of
9
+
Phorge tries to make it difficult for users to lock themselves out of
10
10
things, but you can occasionally end up in situations where no one has access
11
11
to an object that you need access to.
12
12
+1
-1
src/docs/user/userguide/users.diviner
+1
-1
src/docs/user/userguide/users.diviner
···
18
18
19
19
**Administrators** are normal users with a few extra capabilities. Their
20
20
primary role is to keep things running smoothly, and they are not all-powerful.
21
-
In Phabricator, administrators are more like //janitors//.
21
+
In Phorge, administrators are more like //janitors//.
22
22
23
23
Administrators can create, delete, enable, disable, and approve user accounts.
24
24
Various applications have a few other capabilities which are reserved for
+4
-4
src/docs/user/userguide/utf8.diviner
+4
-4
src/docs/user/userguide/utf8.diviner
···
1
1
@title User Guide: UTF-8 and Character Encoding
2
2
@group userguide
3
3
4
-
How Phabricator handles character encodings.
4
+
How Phorge handles character encodings.
5
5
6
6
= Overview =
7
7
8
-
Phabricator stores all internal text data as UTF-8, processes all text data
8
+
Phorge stores all internal text data as UTF-8, processes all text data
9
9
as UTF-8, outputs in UTF-8, and expects all inputs to be UTF-8. Principally,
10
10
this means that you should write your source code in UTF-8. In most cases this
11
11
does not require you to change anything, because ASCII text is a subset of
···
17
17
- Convert all files in the repository to ASCII or UTF-8 (see "Detecting and
18
18
Repairing Files" below). This is recommended, especially if the encoding
19
19
problems are accidental.
20
-
- Configure Phabricator to convert files into UTF-8 from whatever encoding
20
+
- Configure Phorge to convert files into UTF-8 from whatever encoding
21
21
your repository is in when it needs to (see "Support for Alternate
22
22
Encodings" below). This is not completely supported, and repositories with
23
23
files that have multiple encodings are not supported.
24
24
25
25
= Support for Alternate Encodings =
26
26
27
-
Phabricator has some support for encodings other than UTF-8.
27
+
Phorge has some support for encodings other than UTF-8.
28
28
29
29
NOTE: Alternate encodings are not completely supported, and a few features will
30
30
not work correctly. Codebases with files that have multiple different encodings
+6
-6
src/docs/user/userguide/webhooks.diviner
+6
-6
src/docs/user/userguide/webhooks.diviner
···
7
7
Overview
8
8
========
9
9
10
-
If you'd like to react to events in Phabricator or publish them into external
10
+
If you'd like to react to events in Phorge or publish them into external
11
11
systems, you can configure webhooks.
12
12
13
13
Configure webhooks in {nav Herald > Webhooks}. Users must have the
···
35
35
options:
36
36
37
37
```
38
-
phabricator/ $ ./bin/webhook call --id 42 --object D123
38
+
phorge/ $ ./bin/webhook call --id 42 --object D123
39
39
```
40
40
41
41
···
43
43
==================
44
44
45
45
When your webhook callback URI receives a request, it didn't necessarily come
46
-
from Phabricator. An attacker or mischievous user can normally call your hook
46
+
from Phorge. An attacker or mischievous user can normally call your hook
47
47
directly and pretend to be notifying you of an event.
48
48
49
49
To verify that the request is authentic, first retrieve the webhook key from
50
50
the web UI with {nav View HMAC Key}. This is a shared secret which will let you
51
-
verify that Phabricator originated a request.
51
+
verify that Phorge originated a request.
52
52
53
53
When you receive a request, compute the SHA256 HMAC value of the request body
54
54
using the HMAC key as the key. The value should match the value in the
···
124
124
125
125
- `test` This was a test call from the web UI or console.
126
126
- `silent` This is a silent edit which won't send mail or notifications in
127
-
Phabricator. If your hook is doing something like copying events into
127
+
Phorge. If your hook is doing something like copying events into
128
128
a chatroom, it may want to respect this flag.
129
129
- `secure` Details about this object should only be transmitted over
130
130
secure channels. Your hook may want to respect this flag.
···
198
198
seconds to respond to requests.
199
199
200
200
Hook callbacks are single-threaded: you will never receive more than one
201
-
simultaneous call to the same webhook from Phabricator. If you have a firehose
201
+
simultaneous call to the same webhook from Phorge. If you have a firehose
202
202
hook on an active install, it may be important to respond to requests quickly
203
203
to avoid accumulating a backlog.
204
204