revi-archive/phorge-phorge
1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-25 16:22:43 +01:00
Code Issues Releases Wiki Activity

Update Diviner documentation to reference Phorge instead of Phabricator.

Browse source 
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
This commit is contained in:
Matthew Bowker 2021-06-19 17:19:56 -06:00
parent 7157dd96b3
commit 1ddb953b9f
138 changed files with 1712 additions and 1399 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
src/docs/book/contributor.book
View file

@ -1,11 +1,11 @@
{
"name": "phabcontrib",
"title": "Phabricator Contributor Documentation",
"short": "Phabricator Contributor Docs",
"preface": "Information for Phabricator contributors and developers.",
"name": "contrib",
"title": "Phorge Contributor Documentation",
"short": "Contributor Docs",
"preface": "Information for Phorge contributors and developers.",
"root": "../../../",
"uri.source":
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
"rules": {
"(\\.diviner$)": "DivinerArticleAtomizer"
},

13
src/docs/book/flavor.book
View file

@ -1,11 +1,11 @@
{
"name": "phabflavor",
"title": "Phabricator Flavor Text",
"name": "flavor",
"title": "Phorge Flavor Text",
"short": "Flavor Text",
"preface": "Recommendations, lore, and dark rituals.",
"preface": "A collection of short articles which pertain to software development in general, not necessarily to Phorge specifically.",
"root": "../../../",
"uri.source":
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
"rules": {
"(\\.diviner$)": "DivinerArticleAtomizer"
},
@ -20,14 +20,11 @@
"(^webroot/rsrc/externals/)"
],
"groups": {
"overview": {
"name": "Overview"
},
"javascript": {
"name": "Javascript"
},
"lore": {
"name": "Phabricator Lore"
"name": "Phorge Lore"
},
"php": {
"name": "PHP"

10
src/docs/book/phabricator.book → src/docs/book/phorge.book
View file

@ -1,11 +1,11 @@
{
"name": "phabdev",
"title": "Phabricator Technical Documentation",
"short": "Phabricator Tech Docs",
"preface": "Technical reference material for Phabricator developers.",
"name": "dev",
"title": "Phorge Technical Documentation",
"short": "Tech Docs",
"preface": "Technical reference material for Phorge developers.",
"root": "../../../",
"uri.source":
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
"rules": {
"(\\.diviner$)": "DivinerArticleAtomizer",
"(\\.php$)": "DivinerPHPAtomizer"

13
src/docs/book/user.book
View file

@ -1,11 +1,11 @@
{
"name": "phabricator",
"title": "Phabricator User Documentation",
"short": "Phabricator User Docs",
"preface": "Instructions for installing, configuring, and using Phabricator.",
"name": "phorge",
"title": "Phorge User Documentation",
"short": "User Docs",
"preface": "Instructions for installing, configuring, and using Phorge.",
"root": "../../../",
"uri.source":
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
"rules": {
"(\\.diviner$)": "DivinerArticleAtomizer"
},
@ -37,9 +37,6 @@
},
"fieldmanual": {
"name": "Field Manuals"
},
"cellar": {
"name": "Musty Cellar"
}
}
}

77
src/docs/contributor/adding_new_classes.diviner
View file

@ -1,22 +1,22 @@
@title Adding New Classes
@group developer
Guide to adding new classes to extend Phabricator.
Guide to adding new classes to extend Phorge.
Overview
========
Phabricator is highly modular, and many parts of it can be extended by adding
Phorge is highly modular, and many parts of it can be extended by adding
new classes. This document explains how to write new classes to change or
expand the behavior of Phabricator.
expand the behavior of Phorge.
IMPORTANT: The upstream does not offer support with extension development.
NOTE: The upstream offers limited support with extension development.
Fundamentals
============
Phabricator primarily discovers functionality by looking at concrete subclasses
of some base class. For example, Phabricator determines which applications are
Phorge primarily discovers functionality by looking at concrete subclasses
of some base class. For example, Phorge determines which applications are
available by looking at all of the subclasses of
@{class@phabricator:PhabricatorApplication}. It
discovers available workflows in `arc` by looking at all of the subclasses of
@ -24,7 +24,7 @@ discovers available workflows in `arc` by looking at all of the subclasses of
by looking at all of the subclasses of @{class@arcanist:PhutilLocale}.
This pattern holds in many cases, so you can often add functionality by adding
new classes with no other work. Phabricator will automatically discover and
new classes with no other work. Phorge will automatically discover and
integrate the new capabilities or features at runtime.
There are two main ways to add classes:
@ -42,20 +42,20 @@ The next sections walk through these approaches in greater detail.
Extensions Directory
====================
The easiest way to extend Phabricator by adding new classes is to drop them
into the extensions directory, at `phabricator/src/extensions/`.
The easiest way to extend Phorge by adding new classes is to drop them
into the extensions directory, at `pohrge/src/extensions/`.
This is intended as a quick way to add small pieces of functionality, test new
features, or get started on a larger project. Extending Phabricator like this
features, or get started on a larger project. Extending Phorge like this
imposes a small performance penalty compared to using a library.
This directory exists in all libphutil libraries, so you can find a similar
This directory also exists for Arcanist, so you can find a similar
directory in `arcanist/src/extensions/`.
For example, to add a new application, create a file like this one and add it
to `phabricator/src/extensions/`.
to `phorge/src/extensions/`.
```name=phabricator/src/extensions/ExampleApplication.php, lang=php
```name=phorge/src/extensions/ExampleApplication.php, lang=php
<?php
final class ExampleApplication extends PhabricatorApplication {
@ -69,15 +69,15 @@ final class ExampleApplication extends PhabricatorApplication {
If you load {nav Applications} in the web UI, you should now see your new
application in the list. It won't do anything yet since you haven't defined
any interesting behavior, but this is the basic building block of Phabricator
any interesting behavior, but this is the basic building block of Phorge
extensions.
Creating Libraries
==================
A more powerful (but more complicated) way to extend Phabricator is to create
a libphutil library. Libraries can organize a larger amount of code, are easier
A more powerful (but more complicated) way to extend Phorge is to create
a library. Libraries can organize a larger amount of code, are easier
to work with and distribute, and have slightly better performance than loose
source files in the extensions directory.
@ -85,7 +85,7 @@ In general, you'll perform these one-time setup steps to create a library:
- Create a new directory.
- Use `arc liberate` to initialize and name the library.
- Configure Phabricator or Arcanist to load the library.
- Configure Phorge or Arcanist to load the library.
Then, to add new code, you do this:
@ -95,7 +95,7 @@ Then, to add new code, you do this:
Initializing a Library
======================
To create a new libphutil library, create a directory for it and run
To create a new library, create a directory for it and run
`arc liberate` on the directory. This documentation will use a conventional
directory layout, which is recommended, but you are free to deviate from this.
@ -143,38 +143,38 @@ This will write three files:
(functions and classes) in the library, which allows them to be autoloaded
at runtime and dependencies to be statically managed by `arc liberate`.
Linking with Phabricator
========================
Linking with Phorge
===================
If you aren't using this library with Phabricator (e.g., you are only using it
with Arcanist or are building something else on libphutil) you can skip this
(NOTE) If you aren't using this library with Phorge (e.g., you are only using it
with Arcanist or are building something else) you can skip this
step.
But, if you intend to use this library with Phabricator, you need to define its
dependency on Phabricator by creating a `.arcconfig` file which points at
Phabricator. For example, you might write this file to
But, if you intend to use this library with Phorge, you need to define its
dependency on Phorge by creating a `.arcconfig` file which points at
Phorge. For example, you might write this file to
`libcustom/.arcconfig`:
```lang=json
{
"load": [
"phabricator/src/"
"phorge/src/"
]
}
```
For details on creating a `.arcconfig`, see
@{article:Arcanist User Guide: Configuring a New Project}. In general, this
tells `arc liberate` that it should look for symbols in Phabricator when
tells `arc liberate` that it should look for symbols in Phorge when
performing static analysis.
NOTE: If Phabricator isn't located next to your custom library, specify a
path which actually points to the `phabricator/` directory.
NOTE: If Phorge isn't located next to your custom library, specify a
path which actually points to the `phorge/` directory.
You do not need to declare dependencies on `arcanist`, since `arc liberate`
automatically loads them.
Finally, edit your Phabricator config to tell it to load your library at
Finally, edit your Phorge config to tell it to load your library at
runtime, by adding it to `load-libraries`:
```lang=json
@ -185,7 +185,7 @@ runtime, by adding it to `load-libraries`:
...
```
Now, Phabricator will be able to load classes from your custom library.
Now, Phorge will be able to load classes from your custom library.
Writing Classes
@ -206,20 +206,20 @@ This will automatically regenerate the static map of the library.
What You Can Extend And Invoke
==============================
Arcanist and Phabricator are strict about extensibility of classes and
Arcanist and Pohrge are strict about extensibility of classes and
visibility of methods and properties. Most classes are marked `final`, and
methods have the minimum required visibility (protected or private). The goal
of this strictness is to make it clear what you can safely extend, access, and
invoke, so your code will keep working as the upstream changes.
IMPORTANT: We'll still break APIs frequently. The upstream does not support
extension development, and none of these APIs are stable.
IMPORTANT: We'll still break APIs frequently. The upstream offers limited
support for extension development, and none of these APIs are stable.
When developing libraries to work with Arcanist and Phabricator, you should
When developing libraries to work with Arcanist and Phorge, you should
respect method and property visibility.
If you want to add features but can't figure out how to do it without changing
Phabricator code, here are some approaches you may be able to take:
Phorge code, here are some approaches you may be able to take:
- {icon check, color=green} **Use Composition**: If possible, use composition
rather than extension to build your feature.
@ -228,8 +228,7 @@ Phabricator code, here are some approaches you may be able to take:
- {icon check, color=green} **File a Feature Request**: Let us know what your
use case is so we can make the class tree more flexible or configurable, or
point you at the right way to do whatever you're trying to do, or explain
why we don't let you do it. Note that we **do not support** extension
development so you may have mixed luck with this one.
why we don't let you do it.
These approaches are **discouraged**, but also possible:
@ -252,5 +251,5 @@ Next Steps
Continue by:
- visiting the [[ https://secure.phabricator.com/w/community_resources/ |
- visiting the [[ https://we.phorge.it/w/community_resources/ |
Community Resources ]] page to find or share extensions and libraries.

14
src/docs/contributor/adding_new_css_and_js.diviner
View file

@ -1,21 +1,19 @@
@title Adding New CSS and JS
@group developer
Explains how to add new CSS and JS files to Phabricator.
Explains how to add new CSS and JS files to Phorge.
= Overview =
Phabricator uses a system called **Celerity** to manage static resources. If you
are a current or former Facebook employee, Celerity is based on the Haste system
used at Facebook and generally behaves similarly.
Phorge uses a system called **Celerity** to manage static resources.
This document is intended for Phabricator developers and contributors. This
(NOTE) This document is intended for Phorge developers and contributors. This
process will not work correctly for third-party code, plugins, or extensions.
= Adding a New File =
To add a new CSS or JS file, create it in an appropriate location in
`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phabricator/`
`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phorge/`
directory.
Each file must `@provides` itself as a component, declared in a header comment:
@ -54,7 +52,7 @@ Then rebuild the Celerity map (see the next section).
When you add, move or remove a file, or change the contents of existing JS or
CSS file, you should rebuild the Celerity map:
phabricator/ $ ./bin/celerity map
phorge/ $ ./bin/celerity map
If you've only changed file content things will generally work even if you
don't, but they might start not working as well in the future if you skip this
@ -64,7 +62,7 @@ The generated file `resources/celerity/map.php` causes merge conflicts
quite often. They can be resolved by running the Celerity mapper. You can
automate this process by running:
phabricator/ $ ./scripts/celerity/install_merge.sh
phorge/ $ ./scripts/celerity/install_merge.sh
This will install Git merge driver which will run when a conflict in this file
occurs.

8
src/docs/contributor/assistive_technologies.diviner
View file

@ -1,7 +1,7 @@
@title Assistive Technologies
@group developer
Information about making Phabricator accessible to assistive technologies.
Information about making Phorge accessible to assistive technologies.
Overview
========
@ -10,9 +10,9 @@ Assistive technologies help people with disabilities use the web. For example,
screen readers can assist people with limited or no eyesight by reading the
contents of pages aloud.
Phabricator has some support for assistive technologies, and we'd like to have
Phorge has some support for assistive technologies, and we'd like to have
more support. This document describes how to use the currently available
features to improve the accessibility of Phabricator.
features to improve the accessibility of Phorge.
Aural-Only Elements
@ -72,5 +72,5 @@ Previewing Aural Pages
======================
To verify aural markup, you can add `?__aural__=1` to any page URI. This will
make Phabricator render the page with styles that reveal aural-only elements and
make Phorge render the page with styles that reveal aural-only elements and
mute visual-only elements.

153
src/docs/contributor/bug_reports.diviner
View file

@ -1,5 +1,156 @@
@title Contributing Bug Reports
@group detail
Effective June 1, 2021: Phabricator is no longer actively maintained and no longer accepts bug reports.
Describes how to file an effective Phorge bug report.
Overview
========
This article describes how to file an effective Phorge bug report.
The most important things to do are:
- check the list of common fixes below;
- make sure Phorge is up to date;
- make sure we support your setup;
- gather debugging information; and
- explain how to reproduce the issue.
The rest of this article walks through these points in detail.
For general information on contributing to Phorge, see
@{article:Contributor Introduction}.
Common Fixes
============
Before you file a report, here are some common solutions to problems:
- **Update Phorge**: We receive a lot of bug reports about issues we have
already fixed in HEAD. Updating often resolves issues. It is common for
issues to be fixed in less than 24 hours, so even if you've updated recently
you should update again. If you aren't sure how to update, see the next
section.
- **Update Libraries**: Make sure `arcanist/` and `phorge/` are all up
to date. Users often update `phorge/` but forget to update `arcanist/`.
When you update, make sure you update both libraries.
- **Restart Apache or PHP-FPM**: Phorge uses caches which don't get
reset until you restart Apache or PHP-FPM. After updating, make sure you
restart.
Update Phorge
=============
Before filing a bug, make sure you are up to date. We receive many bug reports
for issues we have already fixed, and even if we haven't fixed an issue we'll
be able to resolve it more easily if you file a report based on HEAD. (For
example, an old stack trace may not have the right line numbers, which will
make it more difficult for us to figure out what's going wrong.)
To update Phorge, use a script like the one described in
@{article:Upgrading Phorge}.
**If you can not update** for some reason, please include the version of
Phorge and Arcanist you are running when you file a report.
For help, see @{article:Providing Version Information}.
Supported Issues
================
Before filing a bug, make sure you're filing an issue against something we
support.
**We can NOT help you with issues we can not reproduce.** It is critical that
you explain how to reproduce the issue when filing a report.
For help, see @{article:Providing Reproduction Steps}.
**We do NOT support prototype applications.** If you're running into an issue
with a prototype application, you're on your own. For more information about
prototype applications, see @{article:User Guide: Prototype Applications}.
**We do NOT support third-party packages or instructions.** If you installed
Phorge (or configured some aspect of it) using a third-party package or by
following a third-party guide (like a blog post), we can not help you.
Phorge changes quickly and third-party information is unreliable and often
falls out of date. Contact the maintainer of the package or guide you used,
or reinstall following the upstream instructions.
**We do NOT support custom code development or third-party libraries.** If
you're writing an extension, you're on your own. We provide some documentation,
but can not help you with extension or library development. If you downloaded a
library from somewhere, contact the library maintainer.
**We do NOT support bizarre environments.** If your issue is specific to an
unusual installation environment, we generally will not help you find a
workaround. Install Phorge in a normal environment instead. Examples of
unusual environments are shared hosts, nontraditional hosts (gaming consoles,
storage appliances), and hosts with unusually tight resource constraints. The
vast majority of users run Phorge in normal environments (modern computers
with root access) and these are the only environments we support.
Otherwise, if you're having an issue with a supported first-party application
and followed the upstream install instructions on a normal computer, we're happy
to try to help.
Getting More Information
========================
For some issues, there are places you can check for more information. This may
help you resolve the issue yourself. Even if it doesn't, this information can
help us figure out and resolve an issue.
- For issues with `arc` or any other command-line script, you can get more
details about what the script is doing by adding the `--trace` flag.
- For issues with Phorge, check your webserver error logs.
- For Apache, this is often `/var/log/httpd/error.log`, or
`/var/log/apache2/error.log` or similar.
- For nginx, check both the nginx and php-fpm logs.
- For issues with the UI, check the Javascript error console in your web
browser.
- Some other things, like daemons, have their own debug flags or
troubleshooting steps. Check the documentation for information on
troubleshooting. Adjusting settings or enabling debugging modes may give
you more information about the issue.
Reproducibility
===============
The most important part of your report content is instructions on how to
reproduce the issue. What did you do? If you do it again, does it still break?
Does it depend on a specific browser? Can you reproduce the issue on
a fresh, unmodified Phorge instance?
It is nearly impossible for us to resolve many issues if we can not reproduce
them. We will not accept reports which do not contain the information required
to reproduce problems.
For help, see @{article:Providing Reproduction Steps}.
File a Bug Report
=================
If you're up to date, have collected information about the problem, and have
the best reproduction instructions you can come up with, you're ready
to file a report.
It is **particularly critical** that you include reproduction steps.
You can file a report [[ https://we.phorge.it/maniphest/task/edit/form/2/ | on this instance]].
Next Steps
==========
Continue by:
- reading general support information in @{article:Support Resources}; or
- returning to the @{article:Contributor Introduction}.

2
src/docs/tech/celerity.diviner → src/docs/contributor/celerity.diviner
View file

@ -1,5 +1,5 @@
@title Celerity Technical Documentation
@group celerity
@group developer
Technical overview of the Celerity system.

169
src/docs/contributor/cla.diviner
View file

@ -1,169 +0,0 @@
@title Understanding the Phacility CLA
@group detail
Describes the Contributor License Agreement (CLA).
Overview
========
IMPORTANT: This document is not legal advice.
Phacility requires contributors to sign a Contributor License Agreement
(often abbreviated "CLA") before we can accept contributions into the upstream.
This document explains what this document means and why we require it.
This requirement is not unusual, and many large open source projects require a
similar CLA, including Python, Go, jQuery, and Apache Software Foundation
projects.
You can read more about CLAs and find more examples of companies and projects
which require them on Wikipedia's
[[ https://en.wikipedia.org/wiki/Contributor_License_Agreement | CLA ]] page.
Our CLA is substantially similar to the CLA required by Apache, the
"Apache Individual Contributor License Agreement V2.0". Many projects which
require a CLA use this CLA or a similar one.
Why We Require a CLA
====================
While many projects require a CLA, others do not. This project requires a CLA
primarily because:
- it gives us certain rights, particularly the ability to relicense the work
later;
- it makes the terms of your contribution clear, protecting us from liability
related to copyright and patent disputes.
**More Rights**: We consider the cost of maintaining changes to greatly
outweigh the cost of writing them in the first place. When we accept work
into the upstream, we are agreeing to bear that maintenance cost.
This cost is not worthwhile to us unless the changes come with no strings
attached. Among other concerns, we would be unable to redistribute Phabricator
under a different license in the future without the additional rights the CLA
gives us.
For a concrete example of the problems this causes, Bootstrap switched from
GPLv2 to MIT in 2012-2013. You can see the issue tracking the process and read
about what they had to go through to do this here:
https://github.com/twbs/bootstrap/issues/2054
This took almost 18 months and required a huge amount of effort. We are not
willing to encumber the project with that kind of potential cost in order to
accept contributions.
The rights you give us by signing the CLA allow us to release the software
under a different license later without asking you for permission, including a
license you may not agree with.
They do not allow us to //undo// the existing release under the Apache license,
but allow us to make an //additional// release under a different license, or
release under multiple licenses (if we do, users may choose which license or
licenses they wish to use the software under). It would also allow us to
discontinue updating the release under the Apache license.
While we do not currently plan to relicense Phabricator, we do not want to
give up the ability to do so: we may want or need to in the future.
The most likely scenario which would lead to us changing the license is if a
new version of the Apache license is released. Open source software licenses
are still largely untested in the US legal system, and they may face challenges
in the future which could require adapting them to a changing legal
environment. If this occurs, we would want to be able to update to a newer
version of the license which accounted for these changes.
It is also possible that we may want to change open source licenses (for
example, to MIT) or adopt dual-licensing (for example, both Apache and MIT). We
might want to do this so that our license is compatible with the licenses used
by other software we want to be distributed alongside.
Although we currently believe it is unlikely, it is also possible we may want
to relicense Phabricator under a closed, proprietary, or literally evil license.
By signing the CLA, you are giving us the power to do this without requiring
you to consent. If you are not comfortable with this, do not sign the CLA and
do not contribute to Phabricator.
**Limitation of Liability**: The second benefit the CLA provides is that it
makes the terms of your contribution explicitly clear upfront, and it puts us
in a much stronger legal position if a contributor later claims there is
ambiguity about ownership of their work. We can point at the document they
signed as proof that they consented to our use and understood the terms of
their contribution.
//SCO v. IBM// was a lawsuit filed in 2003 alleging (roughly) that IBM had
improperly contributed code owned by SCO to Linux. The details of this and the
subsequent cases are very complex and the situation is not a direct parallel to
anything we are likely to face, but SCO claimed billions of dollars in damages
and the litigation has now been ongoing for more than a decade.
We want to avoid situations like this in the future by making the terms of
contribution explicit upfront.
Generally, we believe the terms of the CLA are fair and reasonable for
contributors, and that the primary way contributors benefit from contributing
to Phabricator is that we publish and maintain their changes so they do not
have to fork the software.
If you have strong ideological reasons for contributing to open source, you may
not be comfortable with the terms of the CLA (for example, it may be important
to you that your changes are never available under a license which you haven't
explicitly approved). This is fine and we can understand why contributors may
hold this viewpoint, but we can not accept your changes into the upstream.
Corporate vs Individual CLAs
============================
We offer two CLAs:
- {L28}
- {L30}
These are both substantially similar to the corresponding Apache CLAs.
If you own the work you are contributing, sign the individual CLA. If your
employer owns the work you are contributing, have them sign the corporate CLA.
**If you are employed, there is a substantial possibility that your employer
owns your work.** If they do, you do not have the right to contribute it to us
or assign the rights that we require, and can not contribute under the
individual CLA. Work with your employer to contribute under the corporate CLA
instead.
Particularly, this clause in the individual CLA is the important one:
> 4. You represent that you are legally entitled to grant the above license. If
> your employer(s) has rights to intellectual property that you create that
> includes your Contributions, you represent that you have received permission
> to make Contributions on behalf of that employer, that your employer has
> waived such rights for your Contributions to Phacility, or that your employer
> has executed a separate Corporate CLA with Phacility.
Ownership of your work varies based on where you live, how you are employed,
and your agreements with your employer. However, at least in the US, it is
likely that your employer owns your work unless you have anticipated conflicts
and specifically avoided them. This generally makes sense: if you are paid by
your employer for your work, they own the product of your work and you receive
salary and benefits in fair exchange for that work.
Your employer may have an ownership claim on your work even if you perform it
on your own time, if you use their equipment (like a company laptop or phone),
resources, facilities, or trade secrets, or signed something like an "Invention
Assignment Agreement" when you were hired. Such agreements are common. The
details of the strength of their claim will vary based on your situation and
local law.
If you are unsure, you should speak with your employer or a lawyer. If you
contribute code you do not own under the individual CLA, you are exposing
yourself to liability. You may also be exposing us to liability, but we'll have
the CLA on our side to show that we were unwilling pawns in your malicious
scheme to defraud your employer.
The good news is that most employers are happy to contribute to open source
projects. Incentives are generally well aligned: they get features they want,
and it reflects well on them. In the past, potential contributors who have
approached their employers about a corporate CLA have generally had little
difficulty getting approval.

23
src/docs/contributor/contrib_intro.diviner
View file

@ -1,12 +1,12 @@
@title Contributor Introduction
@group contrib
Introduction to contributing to Phabricator and Arcanist.
Introduction to contributing to Phorge and Arcanist.
Overview
========
If you'd like to contribute to Phabricator, this document can guide you though
If you'd like to contribute to Phorge, this document can guide you though
ways you can help improve the project.
Writing code is valuable, but often isn't the best or easiest way to contribute.
@ -19,24 +19,11 @@ heavy lifting.
Without writing any code, learning the whole codebase, making a big time
commitment, or having to touch PHP, here are some ways you can materially
contribute to Phabricator:
contribute to Phorge:
- Drop by the [[ https://phurl.io/u/discourse | community forum ]] just to
say "thanks". A big part of the reason we build this software is to help
people solve problems, and knowing that our efforts are appreciated is
really rewarding.
- Recommend Phabricator to people who you think might find it useful. Our
- Recommend Phorge to people who you think might find it useful. Our
most powerful growth channel is word of mouth, and mentioning or tweeting
about Phabricator helps the project grow. If writing a tweet sounds like
too much work, you can use one of these form tweets written by our PR
department to quickly and easily shill on our behalf. Hail corporate!
> Phabricator seems like it's pretty okay
> I am not being paid to mention Phabricator in this extemporaneous, completely organic tweet
> Phabricator is objectively the best thing. Source: I am a certified, internationally recognized expert.
about Phorge helps the project grow.
- Submit high-quality bug reports by carefully following the guide in
@{article:Contributing Bug Reports}.

195
src/docs/contributor/contributing_code.diviner
View file

@ -1,4 +1,197 @@
@title Contributing Code
@group detail
Effective June 1, 2021: Phabricator is no longer actively maintained, and no longer accepting contributions.
Phorge is an open-source project, and welcomes contributions from the community
at large. However, there are some guidelines we ask you to follow.
Overview
========
The most important parts of contributing code to Phorge are:
- File a task with a bug report or feature request //before// you write code.
- We do not accept GitHub pull requests.
- Some alternative approaches are available if your change isn't something
we want to bring upstream.
The rest of this article describes these points in more detail, and then
provides guidance on writing and submitting patches.
If you just want to contribute some code but don't have a specific bug or
feature in mind, see the bottom of this document for tips on finding ways to get
started.
For general information on contributing to Phorge, see
@{article:Contributor Introduction}.
Coordinate First
================
Before sending code, you should file a task describing what you'd like to write.
When you file a task, mention that you'd like to write the code to fix it. We
can help contextualize your request or bug and guide you through writing an
upstreamable patch, provided it's something that's upstreamable. If it isn't
upstreamable, we can let you know what the issues are and help find another
plan of attack.
You don't have to file first (for example, if you spot a misspelling it's
normally fine to just send a diff), but for anything even moderately complex
you're strongly encouraged to file first and coordinate with the upstream.
Rejecting Patches
=================
If you send us a patch without coordinating it with us first, it will probably
be immediately rejected, or sit in limbo for a long time and eventually be
rejected. The reasons we do this vary from patch to patch, but some of the most
common reasons are:
**Unjustifiable Costs**: We support code in the upstream forever. Support is
enormously expensive and takes up a huge amount of our time. The cost to support
a change over its lifetime is often 10x or 100x or 1000x greater than the cost
to write the first version of it. Many uncoordinated patches we receive are
"white elephants", which would cost much more to maintain than the value they
provide.
As an author, it may look like you're giving us free work and we're rejecting it
as too expensive, but this viewpoint doesn't align with the reality of a large
project which is actively supported by a small, experienced team. Writing code
is cheap; maintaining it is expensive.
By coordinating with us first, you can make sure the patch is something we
consider valuable enough to put long-term support resources behind, and that
you're building it in a way that we're comfortable taking over.
**Not a Good Fit**: Many patches aren't good fits for the upstream: they
implement features we simply don't want. Coordinating with us first helps
make sure we're on the same page and interested in a feature.
The most common type of patch along these lines is a patch which adds new
configuration options. We consider additional configuration options to have
an exceptionally high lifetime support cost and are very unlikely to accept
them. Coordinate with us first.
**Not a Priority**: If you send us a patch against something which isn't a
priority, we probably won't have time to look at it. We don't give special
treatment to low-priority issues just because there's code written: we'd still
be spending time on something lower-priority when we could be spending it on
something higher-priority instead.
If you coordinate with us first, you can make sure your patch is in an area
of the codebase that we can prioritize.
**Overly Ambitious Patches**: Sometimes we'll get huge patches from new
contributors. These can have a lot of fundamental problems and require a huge
amount of our time to review and correct. If you're interested in contributing,
you'll have more success if you start small and learn as you go.
We can help you break a large change into smaller pieces and learn how the
codebase works as you proceed through the implementation, but only if you
coordinate with us first.
**Generality**: We often receive several feature requests which ask for similar
features, and can come up with a general approach which covers all of the use
cases. If you send us a patch for //your use case only//, the approach may be
too specific. When a cleaner and more general approach is available, we usually
prefer to pursue it.
By coordinating with us first, we can make you aware of similar use cases and
opportunities to generalize an approach. These changes are often small, but can
have a big impact on how useful a piece of code is.
**Infrastructure and Sequencing**: Sometimes patches are written against a piece
of infrastructure with major planned changes. We don't want to accept these
because they'll make the infrastructure changes more difficult to implement.
Coordinate with us first to make sure a change doesn't need to wait on other
pieces of infrastructure. We can help you identify technical blockers and
possibly guide you through resolving them if you're interested.
No Prototype Changes
====================
With rare exceptions, we do not accept patches for prototype applications for
the same reasons that we don't accept feature requests or bug reports. To learn
more about prototype applications, see
@{article:User Guide: Prototype Applications}.
No Pull Requests
================
We do not accept pull requests on GitHub:
- Pull requests do not get lint and unit tests run, so issues which are
normally caught statically can slip by.
- Phorge is code review software, and developed using its own workflows.
Pull requests bypass some of these workflows (for example, they will not
trigger Herald rules to notify interested parties).
- GitHub is not the authoritative master repository and we maintain a linear
history, so merging pull requests is cumbersome on our end.
- If you're comfortable enough with Phorge to contribute to it, you
should also be comfortable using it to submit changes.
Instead of sending a pull request, use `arc diff` to create a revision on the
upstream install. Your change will go through the normal Phorge review
process.
(GitHub does not allow repositories to disable pull requests, which is why
it's technically possible to submit them.)
Alternatives
============
If you've written code but we're not accepting it into the upstream, some
alternative approaches include:
**Maintain a local fork.** This will require some ongoing effort to port your
changes forward when you update, but is often very reasonable for simple
changes.
**Develop as an application.** Many parts of Phorge's infrastructure are
modular, and modularity is increasing over time. A lot of changes can be built
as external modules or applications without forking Phorge itself. There
isn't much documentation for this right now, but you can look at
how other applications are implemented, and at other third-party code that
extends Phorge.
**Rise to prominence.** We're more willing to accept borderline changes from
community members who are active, make multiple contributions, or have a history
with the project. This is not carte blanche, but distinguishing yourself can
make us feel more comfortable about supporting a change which is slightly
outside of our comfort zone.
Writing and Submitting Patches
==================
To actually submit a patch, run `arc diff` in `phorge/` or `arcanist/`.
When executed in these directories, `arc` should automatically talk to the
upstream install. You can add #blessed_reviewers as a reviewer.
You should read the relevant coding convention documents before you submit a
change. If you're a new contributor, you don't need to worry about this too
much. Just try to make your code look similar to the code around it, and we
can help you through the details during review.
- @{article:General Coding Standards} (for all languages)
- @{article:PHP Coding Standards} (for PHP)
- @{article:Javascript Coding Standards} (for Javascript)
In general, if you're coordinating with us first, we can usually provide
guidance on how to implement things. The other articles in this section also
provide information on how to work in the Phorge codebase.
Next Steps
==========
Continue by:
- returning to the @{article:Contributor Introduction}.

12
src/docs/contributor/css_coding_standards.diviner
View file

@ -1,14 +1,14 @@
@title CSS Coding Standards
@group standards
This document describes CSS features and coding standards for Phabricator.
This document describes CSS features and coding standards for Phorge.
= Overview =
This document describes technical and style guidelines for writing CSS in
Phabricator.
Phorge.
Phabricator has a limited CSS preprocessor. This document describes the features
Phorge has a limited CSS preprocessor. This document describes the features
it makes available.
= Z-Indexes =
@ -19,7 +19,7 @@ Great Z-Index War where all indexes grow without bound in an endless arms race.
= Color Variables =
Phabricator's preprocessor provides some standard color variables. You can
Phorge's preprocessor provides some standard color variables. You can
reference these with `{$color}`. For example:
lang=css
@ -60,7 +60,7 @@ by the media query.
= Device Rules =
Phabricator's environment defines several device classes which can be used to
Phorge's environment defines several device classes which can be used to
adjust behavior responsively. In particular:
lang=css
@ -86,6 +86,6 @@ either tablets or phones:
= Image Inlining =
Phabricator's CSS preprocessor automatically inlines images which are less than
Phorge's CSS preprocessor automatically inlines images which are less than
32KB using `data:` URIs. This is primarily useful for gradients or textures
which are small and difficult to sprite.

34
src/docs/contributor/database.diviner
View file

@ -7,10 +7,10 @@ questions like how to store new types of data.
Database System
===============
Phabricator uses MySQL or another MySQL-compatible database (like MariaDB
Phorge uses MySQL or another MySQL-compatible database (like MariaDB
or Amazon RDS).
Phabricator uses the InnoDB table engine. The only exception is the
Phorge uses the InnoDB table engine. The only exception is the
`search_documentfield` table which uses MyISAM because MySQL doesn't support
fulltext search in InnoDB (recent versions do, but we haven't added support
yet).
@ -21,22 +21,22 @@ SQLite.
PHP Drivers
===========
Phabricator supports [[ http://www.php.net/book.mysql | MySQL ]] and
Phorge supports [[ http://www.php.net/book.mysql | MySQL ]] and
[[ http://www.php.net/book.mysqli | MySQLi ]] PHP extensions.
Databases
=========
Each Phabricator application has its own database. The names are prefixed by
`phabricator_` (this is configurable).
Each Phorge application has its own database. The names are prefixed by
`phorge_` (this is configurable).
Phabricator uses a separate database for each application. To understand why,
see @{article:Why does Phabricator need so many databases?}.
Phorge uses a separate database for each application. To understand why,
see @{article:Why does Phorge need so many databases?}.
Connections
===========
Phabricator specifies if it will use any opened connection just for reading or
Phorge specifies if it will use any opened connection just for reading or
also for writing. This allows opening write connections to a primary and read
connections to a replica in primary/replica setups (which are not actually
supported yet).
@ -45,7 +45,7 @@ Tables
======
Most table names are prefixed by their application names. For example,
Differential revisions are stored in database `phabricator_differential` and
Differential revisions are stored in database `phorge_differential` and
table `differential_revision`. This generally makes queries easier to recognize
and understand.
@ -57,7 +57,7 @@ We use lower-case table names with words separated by underscores.
Column Names
============
Phabricator uses `camelCase` names for columns. The main advantage is that they
Phorge uses `camelCase` names for columns. The main advantage is that they
directly map to properties in PHP classes.
Don't use MySQL reserved words (such as `order`) for column names.
@ -65,17 +65,17 @@ Don't use MySQL reserved words (such as `order`) for column names.
Data Types
==========
Phabricator defines a set of abstract data types (like `uint32`, `epoch`, and
Phorge defines a set of abstract data types (like `uint32`, `epoch`, and
`phid`) which map to MySQL column types. The mapping depends on the MySQL
version.
Phabricator uses `utf8mb4` character sets where available (MySQL 5.5 or newer),
Phorge uses `utf8mb4` character sets where available (MySQL 5.5 or newer),
and `binary` character sets in most other cases. The primary motivation is to
allow 4-byte unicode characters to be stored (the `utf8` character set, which
is more widely available, does not support them). On newer MySQL, we use
`utf8mb4` to take advantage of improved collation rules.
Phabricator stores dates with an `epoch` abstract data type, which maps to
Phorge stores dates with an `epoch` abstract data type, which maps to
`int unsigned`. Although this makes dates less readable when browsing the
database, it makes date and time manipulation more consistent and
straightforward in the application.
@ -134,8 +134,8 @@ eventually, but there isn't a strong case for them at the present time.
PHIDs
=====
Each globally referencable object in Phabricator has an associated PHID
("Phabricator ID") which serves as a global identifier, similar to a GUID.
Each globally referencable object in Phorge has an associated PHID
("Phorge ID") which serves as a global identifier, similar to a GUID.
We use PHIDs for referencing data in different databases.
We use both auto-incrementing IDs and global PHIDs because each is useful in
@ -150,6 +150,8 @@ are permitted to subscribe to different types of objects (revisions, tasks,
etc). Without PHIDs, we would need to add a "type" column to avoid ID collision;
using PHIDs makes implementing features like this simpler.
For more information, see @{article:Handles Technical Documentation}
Transactions
============
@ -169,7 +171,7 @@ update, and understand than application code.
Schema Denormalization
======================
Phabricator uses schema denormalization sparingly. Avoid denormalization unless
Phorge uses schema denormalization sparingly. Avoid denormalization unless
there is a compelling reason (usually, performance) to denormalize.
Schema Changes and Migrations

42
src/docs/contributor/describing_problems.diviner
View file

@ -37,21 +37,21 @@ a problem and why it's important for you to resolve it.
Here are some examples of good ways to start a problem description:
> My company does contracting work for government agencies. Because of the
> nature of our customers, deadlines are critical and it's very important
> for us to keep track of where we are on a timeline. We're using Maniphest
> to track tasks...
(NOTE) My company does contracting work for government agencies. Because of the
nature of our customers, deadlines are critical and it's very important
for us to keep track of where we are on a timeline. We're using Maniphest
to track tasks...
> I have poor eyesight, and use a screenreader to help me use software like
> Phabricator in my job as a developer. I'm having difficulty...
(NOTE) I have poor eyesight, and use a screenreader to help me use software like
Phorge in my job as a developer. I'm having difficulty...
> We work on a large server program which has very long compile times.
> Switching branches is a huge pain (you have to rebuild the binary after
> every switch, which takes about 8 minutes), but we've recently begun using
> `git worktree` to help, which has made life a lot better. However, ...
(NOTE) We work on a large server program which has very long compile times.
Switching branches is a huge pain (you have to rebuild the binary after
every switch, which takes about 8 minutes), but we've recently begun using
`git worktree` to help, which has made life a lot better. However, ...
> I triage manual test failures from our offshore QA team. Here's how our
> workflow works...
(NOTE) I triage manual test failures from our offshore QA team. Here's how our
workflow works...
All of these descriptions are helpful: the provide context about what goals
you're trying to accomplish and why.
@ -59,19 +59,19 @@ you're trying to accomplish and why.
Here are some examples of ways to start a problem description that probably
are not very good:
> {icon times color=red} Add custom keyboard shortcuts.
(IMPORTANT) Add custom keyboard shortcuts.
> {icon times color=red} I have a problem: there is no way to download
> .tar archives of repositories.
(IMPORTANT) I have a problem: there is no way to download
.tar archives of repositories.
> {icon times color=red} I want an RSS feed of my tokens. My root problem is
> that I do not have an RSS feed of my tokens.
(IMPORTANT) I want an RSS feed of my tokens. My root problem is
that I do not have an RSS feed of my tokens.
> {icon times color=red} There is no way to see other users' email addresses.
> That is a problem.
(IMPORTANT) There is no way to see other users' email addresses.
That is a problem.
> {icon times color=red} I've used some other software that has a cool
> feature. Phabricator should have that feature too.
(IMPORTANT) I've used some other software that has a cool
feature. Phorge should have that feature too.
These problem descriptions are not helpful. They do not describe goals or
provide context.

18
src/docs/contributor/developer_setup.diviner
View file

@ -1,19 +1,19 @@
@title Developer Setup
@group developer
How to configure a Phabricator development environment.
How to configure a Phorge development environment.
Overview
========
There are some options and workflows that may be useful if you are developing
or debugging Phabricator.
or debugging Phorge.
Configuration
=============
To adjust Phabricator for development:
To adjust Phorge for development:
- Enable `phabricator.developer-mode` to enable some options and show
more debugging information.
@ -48,17 +48,17 @@ After adding, renaming, or moving classes, run `arc liberate` to rebuild
the class map:
```
phabricator/ $ arc liberate
phorge/ $ arc liberate
```
Until you do this, Phabricator won't recognize your new, moved, or renamed
Until you do this, Phorge won't recognize your new, moved, or renamed
classes. You do not need to run this after modifying an existing class.
After any modifications to static resources (CSS / JS) but before sending
changes for review or pushing them to the remote, run `bin/celerity map`:
```
phabricator/ $ ./bin/celerity map
phorge/ $ ./bin/celerity map
```
This rebuilds the static resource map.
@ -91,7 +91,7 @@ Phame) you can normally test them by adding more entries to your webserver
configuration that look exactly like the primary entry (or expanding the
primary entry to match more domains).
Phabricator routes all requests based on host headers, so alternate domains
Phorge routes all requests based on host headers, so alternate domains
do not normally need any kind of special configuration.
You may also need to add `/etc/hosts` entries for the domains themselves.
@ -103,8 +103,8 @@ Creating Test Data
You can create test objects with the "Lipsum" utility:
```
phabricator/ $ ./bin/lipsum help generate
phabricator/ $ ./bin/lipsum generate ...
phorge/ $ ./bin/lipsum help generate
phorge/ $ ./bin/lipsum generate ...
```
Test data can make your local install feel a little more realistic. With

209
src/docs/contributor/feature_requests.diviner
View file

@ -1,4 +1,211 @@
@title Contributing Feature Requests
@group detail
Effective June 1, 2021: Phabricator is no longer actively maintained, and there is no way to file a feature request.
Describes how to file an effective Phorge feature request.
Overview
========
Phorge is an open-source project, and welcomes feature requests from the community
at large. However, there are some guidelines we ask you to follow.
Overview
========
This article describes how to file an effective feature request.
The most important things to do are:
- understand the upstream;
- make sure your feature makes sense in the project;
- align your expectations around timelines and priorities;
- describe your problem, not your solution.
The rest of this article walks through these points in detail.
If you have a bug report (not a feature request), see
@{article:Contributing Bug Reports} for a more tailored guide.
For general information on contributing to Phorge, see
@{article:Contributor Introduction}.
Understanding the Upstream
==========================
Before filing a feature request, it may be useful to understand how the
upstream operates.
Phorge has a designated core team who controls the project and roadmap.
We have a cohesive vision for the project in the long term, and a general
roadmap that extends for years into the future. While the specifics of how
we get there are flexible, many major milestones are well-established.
Although we set project direction, the community is also a critical part of
Phorge. We aren't all-knowing, and we rely on feedback to help us identify
issues, guide product direction, prioritize changes, and suggest features.
Feature requests are an important part of this, but we ultimately build only
features which make sense as part of the long term plan.
Since it's hard to absorb a detailed understanding of that vision, //describing
a problem// is often more effective than //requesting a feature//. We have the
context to develop solutions which fit into our plans, address similar use
cases, make sense with the available infrastructure, and work within the
boundaries of our product vision. For more details on this, see below.
Target Audiences
================
Some feature requests support very unusual use cases. Although we are broadly
inclusive of many different kinds of users and use cases, we are not trying
to make the software all things to all users. Use cases which are far afield
from the things the majority of users do with Phorge often face substantial
barriers.
Phorge is primarily targeted at software projects and organizations with
a heavy software focus. We are most likely to design, build, and prioritize
features which serve these organizations and projects.
Phorge is primarily targeted at software professionals and other
professionals with adjacent responsibilities (like project management and
operations). Particularly, we assume users are proficient computer users and
familiar with software development concepts. We are most likely to design, build
and prioritize features which serve these users.
Phorge is primarily targeted at professionals working in teams on full-time
projects. Particularly, we assume most users will use the software regularly and
are often willing to spend a little more time up front to get a more efficient
workflow in the long run. We are most likely to design, build and prioritize
features which serve these use cases.
Phorge is not limited to these kinds of organizations, users and use cases,
but features which are aimed at a different group of users (like students,
casual projects, or inexperienced computer users) may be harder to get
upstreamed. Features aimed at very different groups of users (like wedding
planners, book clubs, or dogs) will be much harder to get upstreamed.
In many cases, a feature makes something better for all users. For example,
suppose we fixed an issue where colorblind users had difficulty doing something.
Dogs would benefit the most, but colorblind human users would also benefit, and
no one would be worse off. If the benefit for core users is very small these
kinds of features may be hard to prioritize, but there is no exceptional barrier
to getting them upstreamed.
In other cases, a feature makes something better for some users and worse for
other users. These kinds of features face a high barrier if they make the
software better at planning weddings and worse at reviewing code.
Setting Expectations
====================
We have a lot of users and a small team. Even if your feature is something we're
interested in and a good fit for where we want the product to go, it may take
us a long time to get around to building it.
Our long-term roadmap (which we call our
[[ https://we.phorge.it/w/starmap/ | Starmap ]]) has many years worth
of work. Your feature request is competing against thousands of other requests
for priority.
In general, we try to prioritize work that will have the greatest impact on the
most users. Many feature requests are perfectly reasonable requests, but have
very little impact, impact only a few users, and/or are complex to develop and
support relative to their impact. It can take us a long time to get to these.
Even if your feature request is simple and has substantial impact for a large
number of users, the size of the request queue means that it is mathematically
unlikely to be near the top.
As a whole, this means that the overwhelming majority of feature requests will
sit in queue for a long time without any updates, and that we won't be able to
give you any updates or predictions about timelines. One day, out of nowhere,
your feature will materialize. That day may be a decade from now. You should
have realistic expectations about this when filing a feature request.
Describe Problems
=================
When you file a feature request, we need you to describe the problem you're
facing first, not just your desired solution. Describing the problem you are
facing is the **most important part** of a feature request.
Often, your problem may have a lot in common with other similar problems. If we
understand your use case we can compare it to other use cases and sometimes find
a more powerful or more general solution which solves several problems at once.
At other times, we'll have a planned solution to the problem that might be
different from your desired solution but accomplish the same goal. Understanding
the root issue can let us merge and contextualize things.
Sometimes there's already a way to solve your problem that might just not be
obvious.
Finally, your proposed solution may not be compatible with the direction we
want to take the product, but we may be able to come up with another solution
which has approximately the same effect and does fit into the product direction.
If you only describe the solution and not the problem, we can't generalize,
contextualize, merge, reframe, or offer alternative solutions or workarounds.
You must describe the problem you are facing when filing a feature request. We
will not accept feature requests which do not contextualize the request by
describing the root problem.
If you aren't sure exactly what we're after when we ask you to describe a root
problem, you can find examples and more discussion in
@{article:Describing Root Problems}.
Hypotheticals
=============
We sometimes receive hypothetical feature requests about anticipated problems
or concerns which haven't actually occurred yet. We usually can't do much about
these until the problems actually occur, since the context required to
understand and properly fix the root issue won't exist.
One situation where this happens is when installs are thinking about adopting
Phorge and trying to guess what problems users might encounter during the
transition. More generally, this includes any request like "if users do **X**,
they might find **Y** confusing", where no actual users have encountered
confusion yet.
These requests are necessarily missing important context, maybe including the
answers to questions like these:
- Why did users do **X**?
- What were they trying to do?
- What did they expect to happen?
- How often do users do this?
The answers to these questions are important in establishing that the issue is
really a problem, figuring out the best solution for it, and prioritizing the
issue relative to other issues.
Without knowing this information, we can't be confident that we've found a good
solution to the problem, can't know if we've actually fixed the problem, and
can't even know if the issue was really a problem in the first place (some
hypothetical requests describe problems which no users ever encounter).
We usually can't move forward without this information. In particular, we don't
want to spend time solving hypothetical problems which no real users will ever
encounter: the value of those changes is zero (or negative, by making the
product more complex without providing a benefit), but they consume development
time which could be better spent building much more valuable features.
Generally, you should wait until a problem actually occurs before filing a
request about it.
Next Steps
==========
Continue by:
- learning about @{article: Contributing Bug Reports}; or
- reading general support information in @{article:Support Resources}; or
- returning to the @{article:Contributor Introduction}.

4
src/docs/contributor/general_coding_standards.diviner
View file

@ -1,7 +1,7 @@
@title General Coding Standards
@group standards
This document is a general coding standard for contributing to Phabricator,
This document is a general coding standard for contributing to Phorge,
Arcanist, and Diviner.
= Overview =
@ -60,7 +60,7 @@ And, obviously, don't do this sort of thing:
determine if code is fast or slow by measuring it.
- Reject performance discussions that aren't rooted in concrete data.
In Phabricator, you can usually use the builtin XHProf profiling to quickly
In Phorge, you can usually use the builtin XHProf profiling to quickly
gather concrete performance data.

4
src/docs/tech/handles.diviner → src/docs/contributor/handles.diviner
View file

@ -1,12 +1,12 @@
@title Handles Technical Documentation
@group handles
@group developer
Technical overview of Handles.
Overview
========
Most objects in Phabricator have PHIDs, which are globally unique identifiers
Most objects in Phorge have PHIDs, which are globally unique identifiers
that look like `PHID-USER-2zw4hwdt4i5b5ypikv6x`. If you know the PHID for an
object, you can load a **handle** for that object to get more information
about it.

14
src/docs/contributor/internationalization.diviner
View file

@ -1,12 +1,12 @@
@title Internationalization
@group developer
Describes Phabricator translation and localization.
Describes Phorge translation and localization.
Overview
========
Phabricator partially supports internationalization, but many of the tools
Phorge partially supports internationalization, but many of the tools
are missing or in a prototype state.
This document describes what tools exist today, how to add new translations,
@ -23,7 +23,7 @@ Once you've created a locale, applications can add translations for that
locale.
For instructions on adding new classes, see
@{article@phabcontrib:Adding New Classes}.
@{article@contrib:Adding New Classes}.
Adding Translations to Locale
@ -38,7 +38,7 @@ provide translations into different locales without needing to define those
locales themselves.
For instructions on adding new classes, see
@{article@phabcontrib:Adding New Classes}.
@{article@contrib:Adding New Classes}.
Writing Translatable Code
@ -58,7 +58,7 @@ $dialog->appendParagraph(pht('This is an example.'));
```
This allows the code to return the correct Spanish or German or Russian
version of the text, if the viewer is using Phabricator in one of those
version of the text, if the viewer is using Phorge in one of those
languages and a translation is available.
Using `pht()` properly so that strings are translatable can be tricky. Briefly,
@ -275,7 +275,7 @@ return pht('This will take %s hour(s).', new PhutilNumber($count));
If you now load the web UI, you'll see "hour(s)" literally in the UI. To fix
this so the translation sounds better in English, provide translations for this
string in the @{class@phabricator:PhabricatorUSEnglishTranslation} file:
string in the @{class:PhabricatorUSEnglishTranslation} file:
```lang=php
'This will take %s hour(s).' => array(
@ -378,4 +378,4 @@ Next Steps
Continue by:
- adding a new locale or translation file with
@{article@phabcontrib:Adding New Classes}.
@{article@contrib:Adding New Classes}.

4
src/docs/contributor/javascript_coding_standards.diviner
View file

@ -1,12 +1,12 @@
@title Javascript Coding Standards
@group standards
This document describes Javascript coding standards for Phabricator and Javelin.
This document describes Javascript coding standards for Phorge and Javelin.
= Overview =
This document outlines technical and style guidelines which are followed in
Phabricator and Javelin. Contributors should also follow these guidelines. Many
Phorge and Javelin. Contributors should also follow these guidelines. Many
of these guidelines are automatically enforced by lint.
These guidelines are essentially identical to the Facebook guidelines, since I

2
src/docs/contributor/n_plus_one.diviner
View file

@ -39,7 +39,7 @@ queries which each return 1 result.** This is particularly true if your database
is on a different machine which is, say, 1-2ms away on the network. In this
case, issuing 100 queries serially has a minimum cost of 100-200ms, even if they
can be satisfied instantly by MySQL. This is far higher than the entire
server-side generation cost for most Phabricator pages should be.
server-side generation cost for most Phorge pages should be.
= Batching Queries =

42
src/docs/contributor/phabricator_code_layout.diviner → src/docs/contributor/phorge_code_layout.diviner
View file

@ -1,19 +1,19 @@
@title Phabricator Code Layout
@title Phorge Code Layout
@group developer
Guide to Phabricator code layout, including how URI mapping works through
Guide to Phorge code layout, including how URI mapping works through
application class and subdirectory organization best practices.
= URI Mapping =
When a user visits a Phabricator URI, the Phabricator infrastructure parses
that URI with a regular expression to determine what controller class to load.
When a user visits a Phorge URI, the Phorge infrastructure parses that URI with
a regular expression to determine what controller class to load.
The Phabricator infrastructure knows where a given controller class lives on
The Phorge infrastructure knows where a given controller class lives on
disk from a cache file the Arcanist phutil mapper generates. This mapping
should be updated whenever new classes or files are added:
arc liberate /path/to/phabricator/src
arc liberate /path/to/phorge/src
Finally, a given controller class will map to an application which will have
most of its code in standardized subdirectories and classes.
@ -22,11 +22,11 @@ most of its code in standardized subdirectories and classes.
Suppose you were working on the application `Derp`.
phabricator/src/applications/derp/
phorge/src/applications/derp/
If `Derp` were as simple as possible, it would have one subdirectory:
phabricator/src/applications/derp/controller/
phorge/src/applications/derp/controller/
containing the file `DerpController.php` with the class
@ -37,25 +37,25 @@ containing the file `DerpController.php` with the class
If `Derp` were (relatively) complex, one could reasonably expect to see
the following directory layout:
phabricator/src/applications/derp/conduit/
phabricator/src/applications/derp/constants/
phabricator/src/applications/derp/controller/
phabricator/src/applications/derp/editor/
phabricator/src/applications/derp/exception/
phabricator/src/applications/derp/query/
phabricator/src/applications/derp/replyhandler/
phabricator/src/applications/derp/storage/
phabricator/src/applications/derp/view/
phorge/src/applications/derp/conduit/
phorge/src/applications/derp/constants/
phorge/src/applications/derp/controller/
phorge/src/applications/derp/editor/
phorge/src/applications/derp/exception/
phorge/src/applications/derp/query/
phorge/src/applications/derp/replyhandler/
phorge/src/applications/derp/storage/
phorge/src/applications/derp/view/
(The following two folders are also likely to be included for JavaScript and
CSS respectively. However, static resources are largely outside the scope of
this document. See @{article:Adding New CSS and JS}.)
phabricator/webroot/rsrc/js/application/derp/
phabricator/webroot/rsrc/css/application/derp/
phorge/webroot/rsrc/js/application/derp/
phorge/webroot/rsrc/css/application/derp/
These directories under `phabricator/src/applications/derp/` represent
the basic set of class types from which most Phabricator applications are
These directories under `phorge/src/applications/derp/` represent
the basic set of class types from which most Phorge applications are
assembled. Each would contain a class file. For `Derp`, these classes could be
something like:

4
src/docs/contributor/php_coding_standards.diviner
View file

@ -1,13 +1,13 @@
@title PHP Coding Standards
@group standards
This document describes PHP coding standards for Phabricator and related
This document describes PHP coding standards for Phorge and related
projects (like Arcanist).
= Overview =
This document outlines technical and style guidelines which are followed in
Phabricator and Arcanist. Contributors should also follow these guidelines.
Phorge and Arcanist. Contributors should also follow these guidelines.
Many of these guidelines are automatically enforced by lint.
These guidelines are essentially identical to the Facebook guidelines, since I

8
src/docs/contributor/rendering_html.diviner
View file

@ -1,11 +1,11 @@
@title Rendering HTML
@group developer
Rendering HTML in the Phabricator environment.
Rendering HTML in the Phorge environment.
= Overview =
Phabricator attempts to prevent XSS by treating strings as default-unsafe when
Phorge attempts to prevent XSS by treating strings as default-unsafe when
rendering. This means that if you try to build HTML through string
concatenation, it won't work: the string will be escaped by the rendering
pipeline, and the browser will treat it as plain text, not HTML.
@ -51,7 +51,7 @@ content correctly (without double-escaping):
array(),
$content));
In Phabricator, the @{function:javelin_tag} function is similar to
In Phorge, the @{function:javelin_tag} function is similar to
@{function@arcanist:phutil_tag}, but provides special handling for the
`sigil` and `meta` attributes.
@ -117,7 +117,7 @@ If you need to build a list of items with some element in between each of them
= AphrontView Classes =
Subclasses of @{class:AphrontView} in Phabricator should return a
Subclasses of @{class:AphrontView} in Phorge should return a
@{class@arcanist:PhutilSafeHTML} object. The easiest way to do this is to
return `phutil_tag()` or `javelin_tag()`:

44
src/docs/contributor/reproduction_steps.diviner
View file

@ -6,7 +6,7 @@ Describes how to provide reproduction steps.
Overview
========
When you submit a bug report about Phabricator, you **MUST** include
When you submit a bug report about Phorge, you **MUST** include
reproduction steps. We can not help you with bugs we can not reproduce, and
will not accept reports which omit reproduction steps or have incomplete or
insufficient instructions.
@ -15,7 +15,7 @@ This document explains what we're looking for in good reproduction steps.
Briefly:
- Reproduction steps must allow us to reproduce the problem locally on a
clean, up-to-date install of Phabricator.
clean, up-to-date install of Phorge.
- Reproduction should be as simple as possible.
Good reproduction steps can take time to write out clearly, simplify, and
@ -70,7 +70,7 @@ Reliable Reproduction
=====================
When you file a bug report, the first thing we do to fix it is to try to
reproduce the problem locally on an up-to-date install of Phabricator. We will
reproduce the problem locally on an up-to-date install of Phorge. We will
do this by following the steps you provide. If we can recreate the issue
locally, we can almost always resolve the problem (often very promptly).
@ -80,7 +80,7 @@ settings, feed stories, etc) that we don't have access to. We either can't
follow these steps, or can't reproduce issues by following them.
Reproduction steps must be complete and self-contained, and must allow
**anyone** to reproduce the issue on a new, empty install of Phabricator. If
**anyone** to reproduce the issue on a new, empty install of Phorge. If
the bug you're seeing depends on data or configuration which would not be
present on a new install, you need to include that information in your steps.
@ -101,11 +101,7 @@ to private or proprietary data.
Now, to verify that your steps provide a complete, self-contained way to
reproduce the issue, follow them yourself on a new, empty, up-to-date instance
of Phabricator.
If you can't easily start an empty instance locally, you can launch an empty
instance on Phacility in about 60 seconds (see the "Resources" section for
details).
of Phorge.
If you can follow your steps and reproduce the issue on a clean instance,
we'll probably be able to follow them and reproduce the issue ourselves.
@ -128,32 +124,6 @@ them by removing some steps or describing steps more narrowly. For help, see
"Simplifying Steps" below.
Resources
=========
We provide some resources which can make it easier to start building steps, or
to simplify steps.
**Phacility Test Instances**: You can launch a new, up-to-date instance of
Phabricator on Phacility in about a minute at <https://admin.phacility.com>.
These instances run `stable`.
You can use these instances to make sure that issues haven't already been
fixed, that they reproduce on a clean install, or that your steps are really
complete, and that the root cause isn't custom code or local extensions. Using
a test instance will avoid disrupting other users on your install.
**Test Repositories**: There are several test repositories on
`secure.phabricator.com` which you can push commits to if you need to build
an example to demonstrate a problem.
For example, if you're seeing an issue with a certain filename but the commit
where the problem occurs is in a proprietary internal repository, push a commit
that affects a file with a similar name to a test repository, then reproduce
against the test data. This will allow you to generate steps which anyone can
follow.
Simplifying Steps
=================
@ -239,10 +209,6 @@ to a minimal reproduction case, we can't accept it as a bug report. These
issues are tremendously time consuming for us to pursue and rarely benefit
more than one install.
If the issue is important but falls outside the scope of permissible bug
reports, we're happy to provide more tailored support at consulting rates. See
[[ https://secure.phabricator.com/w/consulting/ | Consulting ]] for details.
Next Steps
==========

4
src/docs/contributor/running_builtin_php_webserver.diviner
View file

@ -3,7 +3,7 @@
As of version 5.4.0, the PHP command line interface provides a built-in web
server. This web server is designed for developmental purposes only, and should
not be used in production. Phabricator can be executed under it with the
not be used in production. Phorge can be executed under it with the
command:
$ php -S localhost:8000 -t path/to/phabricator/webroot/ path/to/phabricator/webroot/index.php
$ php -S localhost:8000 -t path/to/phorge/webroot/ path/to/phorge/webroot/index.php

14
src/docs/contributor/unit_tests.diviner
View file

@ -1,11 +1,11 @@
@title Writing Unit Tests
@group developer
Simple guide to Arcanist and Phabricator unit tests.
Simple guide to Arcanist and Phorge unit tests.
= Overview =
Arcanist and Phabricator provide and use a simple unit test framework. This
Arcanist and Phorge provide and use a simple unit test framework. This
document is aimed at project contributors and describes how to use it to add
and run tests in these projects or other libphutil libraries.
@ -16,11 +16,11 @@ for information on customizing engines.
= Adding Tests =
To add new tests to a Arcanist or Phabricator module:
To add new tests to a Arcanist or Phorge module:
- Create a `__tests__/` directory in the module if it doesn't exist yet.
- Add classes to the `__tests__/` directory which extend from
@{class:PhabricatorTestCase} (in Phabricator) or
@{class:PhabricatorTestCase} (in Phorge) or
@{class@arcanist:PhutilTestCase} (elsewhere).
- Run `arc liberate` on the library root so your classes are loadable.
@ -38,7 +38,7 @@ Once you've added test classes, you can run them with:
Here's a simple example test:
lang=php
class PhabricatorTrivialTestCase extends PhabricatorTestCase {
class PhorgeTrivialTestCase extends PhabricatorTestCase {
private $two;
@ -56,7 +56,7 @@ Here's a simple example test:
You can see this class at @{class:PhabricatorTrivialTestCase} and run it with:
phabricator/ $ arc unit src/infrastructure/testing/testcase/
phorge/ $ arc unit src/infrastructure/testing/testcase/
PASS <1ms* testAllIsRightWithTheWorld
For more information on writing tests, see
@ -64,7 +64,7 @@ For more information on writing tests, see
= Database Isolation =
By default, Phabricator isolates unit tests from the database. It makes a crude
By default, Phorge isolates unit tests from the database. It makes a crude
effort to simulate some side effects (principally, ID assignment on insert), but
any queries which read data will fail to select any rows and throw an exception
about isolation. In general, isolation is good, but this can make certain types

3
src/docs/contributor/using_edges.diviner
View file

@ -6,8 +6,7 @@ Guide to the Edges infrastructure.
= Overview =
Edges are a generic way of storing a relationship between two objects (like a
Task and its attached files). If you are familiar with the Facebook associations
framework, Phabricator Edges are substantially similar.
Task and its attached files).
An edge is defined by a source PHID (the edge origin), a destination PHID
(the edge destination) and an edge type (which describes the relationship,

18
src/docs/contributor/using_oauthserver.diviner
View file

@ -1,19 +1,19 @@
@title Using the Phabricator OAuth Server
@title Using the Phorge OAuth Server
@group developer
How to use the Phabricator OAuth Server.
How to use the Phorge OAuth Server.
= Overview =
Phabricator includes an OAuth Server which supports the
Phorge includes an OAuth Server which supports the
`Authorization Code Grant` flow as described in the OAuth 2.0
specification:
http://tools.ietf.org/html/draft-ietf-oauth-v2-23
This functionality can allow clients to integrate with a given
Phabricator instance in a secure way with granular data access.
For example, Phabricator can be used as a central identity store for any
Phorge instance in a secure way with granular data access.
For example, Phorge can be used as a central identity store for any
clients that implement OAuth 2.0.
= Vocabulary =
@ -41,7 +41,7 @@ clients that implement OAuth 2.0.
= Obtaining an Authorization Code =
POST or GET `https://phabricator.example.com/oauthserver/auth/` with the
POST or GET `https://phorge.example.com/oauthserver/auth/` with the
following parameters:
- Required - **client_id** - the id of the newly registered client.
@ -69,14 +69,14 @@ redirect_uri with a valid authorization code.
If there is an error, the OAuth Server will return a descriptive error
message. This error will be presented to the resource owner on the
Phabricator domain if there is reason to believe there is something fishy
Phorge domain if there is reason to believe there is something fishy
with the client. For example, if there is an issue with the redirect_uri.
Otherwise, the OAuth Server will redirect to the pertinent redirect_uri
and include the pertinent error information.
= Obtaining an Access Token =
POST or GET `https://phabricator.example.com/oauthserver/token/`
POST or GET `https://phorge.example.com/oauthserver/token/`
with the following parameters:
- Required - **client_id** - the id of the client
@ -101,7 +101,7 @@ message.
Simply include a query param with the key of "access_token" and the value
as the earlier obtained access token. For example:
```https://phabricator.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp```
```https://phorge.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp```
If the token has expired or is otherwise invalid, the client will receive
an error indicating as such. In these cases, the client should re-initiate

10
src/docs/contributor/version.diviner
View file

@ -19,10 +19,10 @@ resolved because valid reproduction steps must also reproduce against a clean,
up-to-date install. See @{article:Providing Reproduction Steps} for details.
Phabricator Version
===================
Phorge Version
==============
To get Phabricator version information:
To get Phorge version information:
- Go to the {nav Config} application. You can type "Config" into the global
search box, or navigate to `https://your.install.com/config/`. You must
@ -52,7 +52,7 @@ prevents you from reaching the version reporting screen.
Running a Fork?
===============
If you've forked Phabricator and have local commits, please make sure you are
If you've forked Phorge and have local commits, please make sure you are
reporting upstream commit hashes, not local commit hashes. The UI will attempt
to figure out where you branched from, but it may not be able to in all cases.
@ -68,7 +68,7 @@ $ git merge-base HEAD origin/master
```
Note that if you report a bug and have local commits, we will almost always ask
you to reproduce the issue against a clean copy of Phabricator before we
you to reproduce the issue against a clean copy of Phorge before we
continue. You can get help faster by doing this //before// reporting an issue.

9
src/docs/flavor/about_flavor_text.diviner
View file

@ -1,9 +0,0 @@
@title About Flavor Text
@group overview
Explains what's going on here.
= Overview =
Flavor Text is a collection of short articles which pertain to software
development in general, not necessarily to Phabricator specifically.

61
src/docs/flavor/project_history.diviner
View file

@ -1,30 +1,27 @@
@title Phabricator Project History
@title Phorge Project History
@group lore
A riveting tale of adventure. In this document, I refer to worldly and
sophisticated engineer Evan Priestley as "I", which is only natural as I am he.
This document is mostly just paragraph after paragraph of self-aggrandizement.
A riveting tale of adventure.
= In The Beginning =
I wrote the original version of Differential in one night at a Facebook
Hackathon in April or May 2007, along with Luke Shepard. I joined the company in
April and code review was already an established and mostly-mandatory part of
the culture, but it happened over email and was inefficient and hard to keep
track of. I remember feeling like I was spending a lot of time waiting for code
review to happen, which was a major motivator for building the tool.
Evan Priestley wrote the original version of Differential in one night at a
Facebook Hackathon in April or May 2007, along with Luke Shepard. He joined the
company in April and code review was already an established and mostly-mandatory
part of the culture, but it happened over email and was inefficient and hard to
keep track of. Evan remembers feeling like he was spending a lot of time waiting
for code review to happen, which was a major motivator for building the tool.
The original name of the tool was "Diffcamp". Some time earlier there had been
an attempt to create a project management tool that was a sort of hybrid between
Trac and Basecamp called "Traccamp". Since we were writing the code review tool
at the height of the brief popularity Traccamp enjoyed, we integrated and called
the new tool Diffcamp even though it had no relation to Basecamp. Traccamp fell
by the wayside shortly thereafter and was eventually removed.
Trac and Basecamp called "Traccamp". Since they were writing the code review tool
at the height of the brief popularity Traccamp enjoyed, Evan and Luke integrated
and called the new tool Diffcamp even though it had no relation to Basecamp.
Traccamp fell by the wayside shortly thereafter and was eventually removed.
However, Diffcamp didn't share its fate. We spent some more time working on it
and got good enough to win hearts and minds over emailing diffs around and was
soon the de facto method of code review at Facebook.
However, Diffcamp didn't share its fate. Evan and Luke spent some more time
working on it and got good enough to win hearts and minds over emailing diffs
around and was soon the de facto method of code review at Facebook.
= The Long Bloat =
@ -34,10 +31,10 @@ was 100% SVN in early 2007 but 90%+ of Engineers worked primarily in git with
SVN bridging by 2010). As these patches were contributed pretty much randomly,
it also gained a lot of performance problems, usability issues, and bugs.
Through 2007 and 2008 I worked mostly on frontend and support infrastructure;
among other things, I wrote a static resource management system called Haste. In
2009 I worked on the Facebook Lite site, where I built the Javelin Javascript
library and an MVC-flavored framework called Alite.
Through 2007 and 2008 Evan worked mostly on frontend and support infrastructure;
among other things, he wrote a static resource management system called Haste.
In 2009 Evan worked on the Facebook Lite site, where he built the Javelin
Javascript library and an MVC-flavored framework called Alite.
But by early 2010, Diffcamp was in pretty bad shape. Two years of having random
features grafted onto it without real direction had left it slow and difficult
@ -49,12 +46,18 @@ problems.
= Differential =
I joined the new Dev Tools team around February 2010 and took over Diffcamp. I
renamed it to Differential, moved it to a new Alite-based infrastructure with
Javelin, and started making it somewhat less terrible. I eventually wrote
Evan joined the new Dev Tools team around February 2010 and took over Diffcamp.
He renamed it to Differential, moved it to a new Alite-based infrastructure with
Javelin, and started making it somewhat less terrible. He eventually wrote
Diffusion and built Herald to replace a very difficult-to-use predecessor. These
tools were less negatively received than the older versions. By December 2010 I
started open sourcing them; Haste became //Celerity// and Alite became
//Aphront//. I wrote Maniphest to track open issues with the project in January
or February, left Facebook in April, and shortly after, we open sourced
tools were less negatively received than the older versions. By December 2010,
Evan started open sourcing them; Haste became //Celerity// and Alite became
//Aphront//. He wrote Maniphest to track open issues with the project in January
or February, left Facebook in April, and shortly after, open sourced
Phabricator.
= Phork =
In 2021, Evan announced that Phabricator was no longer maintained. A group of
open-source contributors came together and forked it. This new
group called renamed the project "Phorge" and continues to maintain this
beloved and well-used project.

6
src/docs/flavor/recommendations_on_branching.diviner
View file

@ -7,13 +7,13 @@ This document discusses organizing branches in your remote/origin for feature
development and release management, not the use of local branches in Git or
queues or bookmarks in Mercurial.
This document is purely advisory. Phabricator works with a variety of branching
This document is purely advisory. Phorge works with a variety of branching
strategies, and diverging from the recommendations in this document
will not impact your ability to use it for code review and source management.
= Overview =
This document describes a branching strategy used by Facebook and Phabricator to
This document describes a branching strategy used by Facebook and Phorge to
develop software. It scales well and removes the pain associated with most
branching strategies. This strategy is most applicable to web applications, and
may be less applicable to other types of software. The basics are:
@ -118,7 +118,7 @@ describing similar systems:
- Martin Fowler discusses these systems in a 2010 blog post here:
[[http://martinfowler.com/bliki/FeatureToggle.html |
Martin Fowler's FeatureToggle]].
- Phabricator just adds config options but defaults them to off. When
- Phorge just adds config options but defaults them to off. When
developing, we turn them on locally. Once a feature is ready, we default it
on. We have a vastly less context to deal with than most projects, however,
and sometimes get away with simply not linking new features in the UI until

6
src/docs/flavor/recommendations_on_revision_control.diviner
View file

@ -3,12 +3,12 @@
Project recommendations on how to organize revision control.
This document is purely advisory. Phabricator works with a variety of revision
This document is purely advisory. Phorge works with a variety of revision
control strategies, and diverging from the recommendations in this document
will not impact your ability to use it for code review and source management.
This is my (epriestley's) personal take on the issue and not necessarily
representative of the views of the Phabricator team as a whole.
This is Evan's personal take on the issue and not necessarily
representative of the views of the Phorge team as a whole.
= Overview =

20
src/docs/flavor/so_many_databases.diviner
View file

@ -1,19 +1,19 @@
@title Why does Phabricator need so many databases?
@title Why does Phorge need so many databases?
@group lore
Phabricator uses about 60 databases (and we may have added more by the time you
Phorge uses about 60 databases (and we may have added more by the time you
read this document). This sometimes comes as a surprise, since you might assume
it would only use one database.
The approach we use is designed to work at scale for huge installs with many
thousands of users. We care a lot about working well for large installs, and
about scaling up gracefully to meet the needs of growing organizations. We want
small startups to be able to install Phabricator and have it grow with them as
small startups to be able to install Phorge and have it grow with them as
they expand to many thousands of employees.
A cost of this approach is that it makes Phabricator more difficult to install
A cost of this approach is that it makes Phorge more difficult to install
on shared hosts which require a lot of work to create or authorize access to
each database. However, Phabricator does a lot of advanced or complex things
each database. However, Phorge does a lot of advanced or complex things
which are difficult to configure or manage on shared hosts, and we don't
recommend installing it on a shared host. The install documentation explicitly
discourages installing on shared hosts.
@ -26,11 +26,11 @@ operating at scale.
Listing Databases
=================
You can get a full list of the databases Phabricator needs with `bin/storage
You can get a full list of the databases Phorge needs with `bin/storage
databases`. It will look something like this:
```
$ /core/lib/phabricator/bin/storage databases
$ /core/lib/phorge/bin/storage databases
secure_audit
secure_calendar
secure_chatlog
@ -89,9 +89,9 @@ tables which are organized into separate application databases, just like it's
easier to work with a large project if you organize source files into
directories.
If you aren't developing Phabricator and never look at the data in the
If you aren't developing Phorge and never look at the data in the
database, you probably won't benefit from this organization. However, if you
are a developer or want to extend Phabricator or look under the hood, it's
are a developer or want to extend Phorge or look under the hood, it's
easier to find what you're looking for and work with the tables when they're
organized by application.
@ -118,7 +118,7 @@ each database, databases do cost something.
However, this cost is an artificial cost imposed by the selected environment,
and this is only the first of many issues you'll run into trying to install and
run Phabricator on a shared host. These issues are why we strongly discourage
run Phorge on a shared host. These issues are why we strongly discourage
using shared hosts, and recommend against them in the install guide.

2
src/docs/flavor/soon_static_resources.diviner
View file

@ -121,6 +121,6 @@ version of CSS and JS into the database.
= Reference Implementation: Celerity =
Some of the ideas discussed here are implemented in Phabricator's //Celerity//
Some of the ideas discussed here are implemented in Phorge's's //Celerity//
system, which is essentially a simplified version of the //Haste// system used
by Facebook.

2
src/docs/flavor/things_you_should_do_now.diviner
View file

@ -134,5 +134,5 @@ query escaping system the rest of the application does.
Hopefully, whatever language you're writing in has good query libraries that
can handle escaping for you. If so, use them. If you're using PHP and don't have
a solution in place yet, the Phabricator implementation of `qsprintf()` is
a solution in place yet, the Phorge implementation of `qsprintf()` is
similar to Facebook's system and was successful there.

10
src/docs/flavor/writing_reviewable_code.diviner
View file

@ -3,14 +3,14 @@
Project recommendations on how to structure changes.
This document is purely advisory. Phabricator works with a variety of revision
This document is purely advisory. Phorge works with a variety of revision
control strategies, and diverging from the recommendations in this document
will not impact your ability to use it for code review and source management.
= Overview =
This document describes a strategy for structuring changes used successfully at
Facebook and in Phabricator. In essence:
Facebook and in Phorge. In essence:
- Each commit should be as small as possible, but no smaller.
- The smallest a commit can be is a single cohesive idea: don't make commits
@ -71,8 +71,8 @@ make any sense and you would increase the collective complexity. The real goal
is for each change to have minimal complexity, line size is just a proxy that is
often well-correlated with complexity.
We generally follow these practices in Phabricator. The median change size for
Phabricator is 35 lines.
We generally follow these practices in Phorge. The median change size for
Phorge is 35 lines.
= Write Sensible Commit Messages =
@ -146,7 +146,7 @@ really all that important in commit messages include:
reasons //why// a change is happening into the commit message.
- Although maybe the spelling and grammar shouldn't be egregiously bad?
Phabricator does not have guidelines for this stuff. You can obviously set
Phorge does not have guidelines for this stuff. You can obviously set
guidelines at your organization if you prefer, but getting the //why// into the
message is the most important part.

22
src/docs/user/cluster/cluster.diviner
View file

@ -1,7 +1,7 @@
@title Clustering Introduction
@group cluster
Guide to configuring Phabricator across multiple hosts for availability and
Guide to configuring Phorge across multiple hosts for availability and
performance.
@ -12,7 +12,7 @@ WARNING: This feature is a prototype. Installs should expect a challenging
adventure when deploying clusters. In the best of times, configuring a
cluster is complex and requires significant operations experience.
Phabricator can be configured to run on multiple hosts with redundant services
Phorge can be configured to run on multiple hosts with redundant services
to improve its availability and scalability, and make disaster recovery much
easier.
@ -20,7 +20,7 @@ Clustering is more complex to setup and maintain than running everything on a
single host, but greatly reduces the cost of recovering from hardware and
network failures.
Each Phabricator service has an array of clustering options that can be
Each Phorge service has an array of clustering options that can be
configured somewhat independently. Configuring a cluster is inherently complex,
and this is an advanced feature aimed at installs with large userbases and
experienced operations personnel who need this high degree of flexibility.
@ -55,7 +55,7 @@ See below for a walkthrough of these services in greater detail.
Preparing for Clustering
========================
To begin deploying Phabricator in cluster mode, set up `cluster.addresses`
To begin deploying Phorge in cluster mode, set up `cluster.addresses`
in your configuration.
This option should contain a list of network address blocks which are considered
@ -65,8 +65,8 @@ hosts in the cluster, so this list should be as small as possible. See "Cluster
Whitelist Security" below for discussion.
If you are deploying hardware in EC2, a reasonable approach is to launch a
dedicated Phabricator VPC, whitelist the whole VPC as a Phabricator cluster,
and then deploy only Phabricator services into that VPC.
dedicated Phorge VPC, whitelist the whole VPC as a Phorge cluster,
and then deploy only Phorge services into that VPC.
If you have additional auxiliary hosts which run builds and tests via Drydock,
you should //not// include them in the cluster address definition. For more
@ -84,7 +84,7 @@ When you configure `cluster.addresses`, you should keep the list of trusted
cluster hosts as small as possible. Hosts on this list gain additional
capabilities, including these:
**Trusted HTTP Headers**: Normally, Phabricator distrusts the load balancer
**Trusted HTTP Headers**: Normally, Phorge distrusts the load balancer
HTTP headers `X-Forwarded-For` and `X-Forwarded-Proto` because they may be
client-controlled and can be set to arbitrary values by an attacker if no load
balancer is deployed. In particular, clients can set `X-Forwarded-For` to any
@ -134,7 +134,7 @@ highest impact on availability and resistance to data loss. This is usually the
most important service to make redundant if your focus is on availability and
disaster recovery.
Configuring replicas allows Phabricator to run in read-only mode if you lose
Configuring replicas allows Phorge to run in read-only mode if you lose
the master and to quickly promote the replica as a replacement.
For details, see @{article:Cluster: Databases}.
@ -147,7 +147,7 @@ Configuring multiple repository hosts is complex, but is required before you
can add multiple daemon or web hosts.
Repository replicas are important for availability if you host repositories
on Phabricator, but less important if you host repositories elsewhere
on Phorge, but less important if you host repositories elsewhere
(instead, you should focus on making that service more available).
The distributed nature of Git and Mercurial tend to mean that they are
@ -243,7 +243,7 @@ Cluster: Fulltext Search
Configuring search services is relatively simple and has no pre-requisites.
By default, Phabricator uses MySQL as a fulltext search engine, so deploying
By default, Phorge uses MySQL as a fulltext search engine, so deploying
multiple database hosts will effectively also deploy multiple fulltext search
hosts.
@ -257,7 +257,7 @@ Overlaying Services
===================
Although hosts can run a single dedicated service type, certain groups of
services work well together. Phabricator clusters usually do not need to be
services work well together. Phorge clusters usually do not need to be
very large, so deploying a small number of hosts with multiple services is a
good place to start.

4
src/docs/user/cluster/cluster_daemons.diviner
View file

@ -1,7 +1,7 @@
@title Cluster: Daemons
@group cluster
Configuring Phabricator to use multiple daemon hosts.
Configuring Phorge to use multiple daemon hosts.
Overview
========
@ -38,7 +38,7 @@ Dedicated Daemon Hosts
You can launch additional daemon hosts without any special configuration.
Daemon hosts must be able to reach other hosts on the network, but do not need
to run any services (like HTTP or SSH). Simply deploy the Phabricator software
to run any services (like HTTP or SSH). Simply deploy the Phorge software
and configuration and start the daemons.
Normally, there is little reason to deploy dedicated daemon hosts. They can

96
src/docs/user/cluster/cluster_databases.diviner
View file

@ -1,12 +1,12 @@
@title Cluster: Databases
@group cluster
Configuring Phabricator to use multiple database hosts.
Configuring Phorge to use multiple database hosts.
Overview
========
You can deploy Phabricator with multiple database hosts, configured as a master
You can deploy Phorge with multiple database hosts, configured as a master
and a set of replicas. The advantages of doing this are:
- faster recovery from disasters by promoting a replica;
@ -15,24 +15,24 @@ and a set of replicas. The advantages of doing this are:
This configuration is complex, and many installs do not need to pursue it.
If you lose the master, Phabricator can degrade automatically into read-only
If you lose the master, Phorge can degrade automatically into read-only
mode and remain available, but can not fully recover without operational
intervention unless the master recovers on its own.
Phabricator will not currently send read traffic to replicas unless the master
Phorge will not currently send read traffic to replicas unless the master
has failed, so configuring a replica will not currently spread any load away
from the master. Future versions of Phabricator are expected to be able to
from the master. Future versions of Phorge are expected to be able to
distribute some read traffic to replicas.
Phabricator can not currently be configured into a multi-master mode, nor can
Phorge can not currently be configured into a multi-master mode, nor can
it be configured to automatically promote a replica to become the new master.
There are no current plans to support multi-master mode or autonomous failover,
although this may change in the future.
Phabricator applications //can// be partitioned across multiple database
Phorge applications //can// be partitioned across multiple database
masters. This does not provide redundancy and generally does not increase
resilience or resistance to data loss, but can help you scale and operate
Phabricator. For details, see
Phorge. For details, see
@{article:Cluster: Partitioning and Advanced Configuration}.
@ -44,32 +44,32 @@ To begin, set up a replica database server and configure MySQL replication.
If you aren't sure how to do this, refer to the MySQL manual for instructions.
The MySQL documentation is comprehensive and walks through the steps and
options in good detail. You should understand MySQL replication before
deploying it in production: Phabricator layers on top of it, and does not
deploying it in production: Phorge layers on top of it, and does not
attempt to abstract it away.
Some useful notes for configuring replication for Phabricator:
Some useful notes for configuring replication for Phorge:
**Binlog Format**: Phabricator issues some queries which MySQL will detect as
**Binlog Format**: Phorge issues some queries which MySQL will detect as
unsafe if you use the `STATEMENT` binlog format (the default). Instead, use
`MIXED` (recommended) or `ROW` as the `binlog_format`.
**Grant `REPLICATION CLIENT` Privilege**: If you give the user that Phabricator
**Grant `REPLICATION CLIENT` Privilege**: If you give the user that Phorge
will use to connect to the replica database server the `REPLICATION CLIENT`
privilege, Phabricator's status console can give you more information about
privilege, Phorge's status console can give you more information about
replica health and state.
**Copying Data to Replicas**: Phabricator currently uses a mixture of MyISAM
**Copying Data to Replicas**: Phorge currently uses a mixture of MyISAM
and InnoDB tables, so it can be difficult to guarantee that a dump is wholly
consistent and suitable for loading into a replica because MySQL uses different
consistency mechanisms for the different storage engines.
An approach you may want to consider to limit downtime but still produce a
consistent dump is to leave Phabricator running but configured in read-only
consistent dump is to leave Phorge running but configured in read-only
mode while dumping:
- Stop all the daemons.
- Set `cluster.read-only` to `true` and deploy the new configuration. The
web UI should now show that Phabricator is in "Read Only" mode.
web UI should now show that Phorge is in "Read Only" mode.
- Dump the database. You can do this with `bin/storage dump --for-replica`
to add the `--master-data` flag to the underlying command and include a
`CHANGE MASTER ...` statement in the dump.
@ -81,18 +81,18 @@ binary logs on startup with the `expire_logs_days` option. If you do not
configure this and do not explicitly purge old logs with `PURGE BINARY LOGS`,
the binary logs on disk will grow unboundedly and relatively quickly.
Once you have a working replica, continue below to tell Phabricator about it.
Once you have a working replica, continue below to tell Phorge about it.
Configuring Replicas
====================
Once your replicas are in working order, tell Phabricator about them by
Once your replicas are in working order, tell Phorge about them by
configuring the `cluster.databases` option. This option must be configured from
the command line or in configuration files because Phabricator needs to read
the command line or in configuration files because Phorge needs to read
it //before// it can connect to databases.
This option value will list all of the database hosts that you want Phabricator
This option value will list all of the database hosts that you want Phorge
to interact with: your master and all your replicas. Each entry in the list
should have these keys:
@ -105,7 +105,7 @@ should have these keys:
host. If omitted, the default from `mysql.user` will be used.
- `pass`: //Optional string.// The password to use to connect to this host.
If omitted, the default from `mysql.pass` will be used.
- `disabled`: //Optional bool.// If set to `true`, Phabricator will not
- `disabled`: //Optional bool.// If set to `true`, Phorge will not
connect to this host. You can use this to temporarily take a host out
of service.
@ -113,7 +113,7 @@ When `cluster.databases` is configured the `mysql.host` option is not used.
The other MySQL connection configuration options (`mysql.port`, `mysql.user`,
`mysql.pass`) are used only to provide defaults.
Once you've configured this option, restart Phabricator for the changes to take
Once you've configured this option, restart Phorge for the changes to take
effect, then continue to "Monitoring Replicas" to verify the configuration.
@ -131,7 +131,7 @@ request//. If you are recovering from a disaster, the view this page shows
may be partial or misleading, and two requests served by different servers may
see different views of the cluster.
**Connection**: Phabricator tries to connect to each configured database, then
**Connection**: Phorge tries to connect to each configured database, then
shows the result in this column. If it fails, a brief diagnostic message with
details about the error is shown. If it succeeds, the column shows a rough
measurement of latency from the current webserver to the database.
@ -141,7 +141,7 @@ things are properly configured and stable, the replicas should be actively
replicating and no more than a few seconds behind master, and the master
should //not// be replicating from another database.
To report this status, the user Phabricator is connecting as must have the
To report this status, the user Phorge is connecting as must have the
`REPLICATION CLIENT` privilege (or the `SUPER` privilege) so it can run the
`SHOW SLAVE STATUS` command. The `REPLICATION CLIENT` privilege only enables
the user to run diagnostic commands so it should be reasonable to grant it in
@ -163,12 +163,12 @@ see an older view of the world which could be confusing for users: it may
appear that their data has been lost, even if it is safe and just hasn't
replicated yet.
Phabricator will attempt to prevent clients from seeing out-of-date views, but
Phorge will attempt to prevent clients from seeing out-of-date views, but
sometimes sending traffic to a delayed replica is the best available option
(for example, if the master can not be reached).
**Health**: This column shows the result of recent health checks against the
server. After several checks in a row fail, Phabricator will mark the server
server. After several checks in a row fail, Phorge will mark the server
as unhealthy and stop sending traffic to it until several checks in a row
later succeed.
@ -189,12 +189,12 @@ To test that your configuration can survive a disaster, turn off the master
database. Do this with great ceremony, making a cool explosion sound as you
run the `mysqld stop` command.
If things have been set up properly, Phabricator should degrade to a temporary
If things have been set up properly, Phorge should degrade to a temporary
read-only mode immediately. After a brief period of unresponsiveness, it will
degrade further into a longer-term read-only mode. For details on how this
works internally, see "Unreachable Masters" below.
Once satisfied, turn the master back on. After a brief delay, Phabricator
Once satisfied, turn the master back on. After a brief delay, Phorge
should recognize that the master is healthy again and recover fully.
Throughout this process, the {nav Database Servers} console will show a
@ -202,7 +202,7 @@ current view of the world from the perspective of the web server handling the
request. You can use it to monitor state.
You can perform a more narrow test by enabling `cluster.read-only` in
configuration. This will put Phabricator into read-only mode immediately
configuration. This will put Phorge into read-only mode immediately
without turning off any databases.
You can use this mode to understand which capabilities will and will not be
@ -211,7 +211,7 @@ accessible in a disaster (like wiki pages or contact information) is really
accessible.
See the next section, "Degradation to Read Only Mode", for more details about
when, why, and how Phabricator degrades.
when, why, and how Phorge degrades.
If you run custom code or extensions, they may not accommodate read-only mode
properly. You should specifically test that they function correctly in
@ -221,14 +221,14 @@ read-only mode and do not prevent you from accessing important information.
Degradation to Read-Only Mode
=============================
Phabricator will degrade to read-only mode when any of these conditions occur:
Phorge will degrade to read-only mode when any of these conditions occur:
- you turn it on explicitly;
- you configure cluster mode, but don't set up any masters;
- the master can not be reached while handling a request; or
- recent attempts to connect to the master have consistently failed.
When Phabricator is running in read-only mode, users can still read data and
When Phorge is running in read-only mode, users can still read data and
browse and clone repositories, but they can not edit, update, or push new
changes. For example, users can still read disaster recovery information on
the wiki or emergency contact information on user profiles.
@ -239,14 +239,14 @@ reasons you might want to do this include:
- to test that the mode works like you expect it to;
- to make sure that information you need will be available;
- to prevent new writes while performing database maintenance; or
- to permanently archive a Phabricator install.
- to permanently archive a Phorge install.
You can also enable this mode implicitly by configuring `cluster.databases`
but disabling the master, or by not specifying any host as a master. This may
be more convenient than turning it on explicitly during the course of
operations work.
If Phabricator is unable to reach the master database, it will degrade into
If Phorge is unable to reach the master database, it will degrade into
read-only mode automatically. See "Unreachable Masters" below for details on
how this process works.
@ -258,12 +258,12 @@ the new master. See the next section, "Promoting a Replica", for details.
Promoting a Replica
===================
If you lose access to the master database, Phabricator will degrade into
If you lose access to the master database, Phorge will degrade into
read-only mode. This is described in greater detail below.
The easiest way to get out of read-only mode is to restore the master database.
If the database recovers on its own or operations staff can revive it,
Phabricator will return to full working order after a few moments.
Phorge will return to full working order after a few moments.
If you can't restore the master or are unsure you will be able to restore the
master quickly, you can promote a replica to become the new master instead.
@ -295,16 +295,16 @@ redundancy.
Unreachable Masters
===================
This section describes how Phabricator determines that a master has been lost,
This section describes how Phorge determines that a master has been lost,
marks it unreachable, and degrades into read-only mode.
Phabricator degrades into read-only mode automatically in two ways: very
Phorge degrades into read-only mode automatically in two ways: very
briefly in response to a single connection failure, or more permanently in
response to a series of connection failures.
In the first case, if a request needs to connect to the master but is not able
to, Phabricator will temporarily degrade into read-only mode for the remainder
of that request. The alternative is to fail abruptly, but Phabricator can
to, Phorge will temporarily degrade into read-only mode for the remainder
of that request. The alternative is to fail abruptly, but Phorge can
sometimes degrade successfully and still respond to the user's request, so it
makes an effort to finish serving the request from replicas.
@ -314,19 +314,19 @@ if it was a read that did not actually need to use the master it may succeed.
This temporary mode is intended to recover as gracefully as possible from brief
interruptions in service (a few seconds), like a server being restarted, a
network link becoming temporarily unavailable, or brief periods of load-related
disruption. If the anomaly is temporary, Phabricator should recover immediately
disruption. If the anomaly is temporary, Phorge should recover immediately
(on the next request once service is restored).
This mode can be slow for users (they need to wait on connection attempts to
the master which fail) and does not reduce load on the master (requests still
attempt to connect to it).
The second way Phabricator degrades is by running periodic health checks
The second way Phorge degrades is by running periodic health checks
against databases, and marking them unhealthy if they fail over a longer period
of time. This mechanism is very similar to the health checks that most HTTP
load balancers perform against web servers.
If a database fails several health checks in a row, Phabricator will mark it as
If a database fails several health checks in a row, Phorge will mark it as
unhealthy and stop sending all traffic (except for more health checks) to it.
This improves performance during a service interruption and reduces load on the
master, which may help it recover from load problems.
@ -336,13 +336,13 @@ console. The "Health" column shows how many checks have run recently and
how many have succeeded.
Health checks run every 3 seconds, and 5 checks in a row must fail or succeed
before Phabricator marks the database as healthy or unhealthy, so it will
before Phorge marks the database as healthy or unhealthy, so it will
generally take about 15 seconds for a database to change state after it goes
down or comes up.
If all of the recent checks fail, Phabricator will mark the database as
If all of the recent checks fail, Phorge will mark the database as
unhealthy and stop sending traffic to it. If the master was the database that
was marked as unhealthy, Phabricator will actively degrade into read-only mode
was marked as unhealthy, Phorge will actively degrade into read-only mode
until it recovers.
This mode only attempts to connect to the unhealthy database once every few
@ -350,7 +350,7 @@ seconds to see if it is recovering, so performance will be better on average
(users rarely need to wait for bad connections to fail or time out) and the
database will receive less load.
Once all of the recent checks succeed, Phabricator will mark the database as
Once all of the recent checks succeed, Phorge will mark the database as
healthy again and continue sending traffic to it.
Health checks are tracked individually for each web server, so some web servers
@ -397,7 +397,7 @@ might be quick) without needing to restore backups (which might be very slow).
Delayed replication is outside the scope of this document, but may be worth
considering as an additional data security step on top of backup snapshots
depending on your resources and needs. If you configure a delayed replica, do
not add it to the `cluster.databases` configuration: Phabricator should never
not add it to the `cluster.databases` configuration: Phorge should never
send traffic to it, and does not need to know about it.

34
src/docs/user/cluster/cluster_devices.diviner
View file

@ -6,7 +6,7 @@ Guide to configuring hosts to act as cluster devices.
Cluster Context
===============
This document describes a step in configuring Phabricator to run on
This document describes a step in configuring Phorge to run on
multiple hosts in a cluster configuration. This is an advanced feature. For
more information on clustering, see @{article:Clustering Introduction}.
@ -38,7 +38,7 @@ Today, this is primarily necessary when configuring repository clusters.
Using Almanac
=============
The tool Phabricator uses to manage cluster devices is the **Almanac**
The tool Phorge uses to manage cluster devices is the **Almanac**
application, and most configuration will occur through the application's web
UI. If you are not familiar with it, see @{article:Almanac User Guide} first.
This document assumes you are familiar with Almanac concepts.
@ -52,7 +52,7 @@ remainder of this document walks through these points in more detail.
- Create an Almanac device record for each device.
- Generate, add, and trust SSH keys if necessary.
- Install Phabricator on the host.
- Install Phorge on the host.
- Use `bin/almanac register` from the host to register it as a device.
See below for guidance on each of these steps.
@ -76,7 +76,7 @@ setting up a small cluster (2-3 devices) for the first time.
Using **shared keys** makes key management easier but safety checks won't be
able to catch a few kinds of mistakes. This may be a better choice if you are
setting up a larger cluster, plan to expand the cluster later, or have
experience with Phabricator clustering.
experience with Phorge clustering.
Because all cluster keys are all-powerful, there is no material difference
between these methods from a security or trust viewpoint. Unique keys are just
@ -87,11 +87,11 @@ easier at larger scales.
Create Almanac Device Records
=============================
For each host you plan to make part of a Phabricator cluster, go to the
For each host you plan to make part of a Phorge cluster, go to the
{nav Almanac} application and create a **device** record. For guidance on this
application, see @{article:Almanac User Guide}.
Add **interfaces** to each device record so Phabricator can tell how to
Add **interfaces** to each device record so Phorge can tell how to
connect to these hosts. Normally, you'll add one HTTP interface (usually on
port 80) and one SSH interface (by default, on port 2222) to each device:
@ -107,9 +107,9 @@ up with records that look like these:
Note that these hosts will normally run two `sshd` ports: the standard `sshd`
which you connect to to operate and administrate the host, and the special
Phabricator `sshd` that you connect to to clone and push repositories.
Phorge `sshd` that you connect to to clone and push repositories.
You should specify the Phabricator `sshd` port, **not** the standard `sshd`
You should specify the Phorge `sshd` port, **not** the standard `sshd`
port.
If you're using **unique** SSH keys for each device, continue to the next step.
@ -141,8 +141,8 @@ in the web UI and run this command from the command line for each key, to mark
each key as trusted:
```
phabricator/ $ ./bin/almanac trust-key --id <key-id-1>
phabricator/ $ ./bin/almanac trust-key --id <key-id-2>
phorge/ $ ./bin/almanac trust-key --id <key-id-1>
phorge/ $ ./bin/almanac trust-key --id <key-id-2>
...
```
@ -153,27 +153,27 @@ policy checks without requiring additional credentials. Guard them carefully!
If you need to revoke trust for a key later, use `untrust-key`:
```
phabricator/ $ ./bin/almanac untrust-key --id <key-id>
phorge/ $ ./bin/almanac untrust-key --id <key-id>
```
Once the keys are trusted, continue to the next step.
Install Phabricator
Install Phorge
===================
If you haven't already, install Phabricator on each device you plan to enroll
If you haven't already, install Phorge on each device you plan to enroll
in the cluster. Cluster repository devices must provide services over both HTTP
and SSH, so you need to install and configure both a webserver and a
Phabricator `sshd` on these hosts.
Phorge `sshd` on these hosts.
Generally, you will follow whatever process you otherwise use when installing
Phabricator.
Phorge.
NOTE: Do not start the daemons on the new devices yet. They won't work properly
until you've finished configuring things.
Once Phabricator is installed, you can enroll the devices in the cluster by
Once Phorge is installed, you can enroll the devices in the cluster by
registering them.
@ -223,7 +223,7 @@ with the trusted key. The `--identify-as` flag allows several different hosts
to share the same key but still identify as different devices.
The overall effect of the `bin/almanac` command is to copy identity and key
files into `phabricator/conf/keys/`. You can inspect the results by examining
files into `phorge/conf/keys/`. You can inspect the results by examining
that directory. The helper script just catches potential mistakes and makes
sure the process is completed correctly.

6
src/docs/user/cluster/cluster_notifications.diviner
View file

@ -1,7 +1,7 @@
@title Cluster: Notifications
@group cluster
Configuring Phabricator to use multiple notification servers.
Configuring Phorge to use multiple notification servers.
Overview
========
@ -29,7 +29,7 @@ never authoritative and never the only way for users to learn about events.
For example, if a notification about a task update is not delivered, the next
page you load will still show the notification in your notification menu.
Generally, Phabricator works fine without notifications configured at all, so
Generally, Phorge works fine without notifications configured at all, so
clustering assumes that losing some messages during a disruption is acceptable.
@ -88,7 +88,7 @@ A simple example with two servers might look like this:
```
Configuring Phabricator
Configuring Phorge
=======================
To configure clustering on the client side, add every service you run to

36
src/docs/user/cluster/cluster_partitioning.diviner
View file

@ -1,12 +1,12 @@
@title Cluster: Partitioning and Advanced Configuration
@group cluster
Guide to partitioning Phabricator applications across multiple database hosts.
Guide to partitioning Phorge applications across multiple database hosts.
Overview
========
You can partition Phabricator's applications across multiple databases. For
You can partition Phorge's applications across multiple databases. For
example, you can move an application like Files or Maniphest to a dedicated
database host.
@ -18,7 +18,7 @@ The advantages of doing this are:
operating the cluster easier.
This configuration is complex, and very few installs will benefit from pursuing
it. Phabricator will normally run comfortably with a single database master
it. Phorge will normally run comfortably with a single database master
even for large organizations.
Partitioning generally does not do much to increase resilience or make it
@ -41,10 +41,10 @@ See "Advanced Configuration", below, for additional discussion.
What Partitioning Does
======================
When you partition Phabricator, you move all of the data for one or more
When you partition Phorge, you move all of the data for one or more
applications (like Maniphest) to a new master database host. This is possible
because Phabricator stores data for each application in its own logical
database (like `phabricator_maniphest`) and performs no joins between databases.
because Phorge stores data for each application in its own logical
database (like `phorge_maniphest`) and performs no joins between databases.
If you're running into scale limits on a single master database, you can move
one or more of your most commonly-used applications to a second database host
@ -78,7 +78,7 @@ each `replica` database follows. Here's a simple example config:
{
"host": "db001.corporation.com",
"role": "master",
"user": "phabricator",
"user": "phorge",
"pass": "hunter2!trustno1",
"port": 3306,
"partition": [
@ -88,7 +88,7 @@ each `replica` database follows. Here's a simple example config:
{
"host": "db002.corporation.com",
"role": "replica",
"user": "phabricator",
"user": "phorge",
"pass": "hunter2!trustno1",
"port": 3306,
"master": "db001.corporation.com:3306"
@ -96,7 +96,7 @@ each `replica` database follows. Here's a simple example config:
{
"host": "db003.corporation.com",
"role": "master",
"user": "phabricator",
"user": "phorge",
"pass": "hunter2!trustno1",
"port": 3306,
"partition": [
@ -108,7 +108,7 @@ each `replica` database follows. Here's a simple example config:
{
"host": "db004.corporation.com",
"role": "replica",
"user": "phabricator",
"user": "phorge",
"pass": "hunter2!trustno1",
"port": 3306,
"master": "db003.corporation.com:3306"
@ -137,7 +137,7 @@ configuration.
To commit the configuration, run this command:
```
phabricator/ $ ./bin/storage partition
phorge/ $ ./bin/storage partition
```
Run this command after making any partition or clustering changes. Webservers
@ -154,16 +154,16 @@ To add a new partition, follow these steps:
- Add the new database to `cluster.databases`, but keep its "partition"
configuration empty (just an empty list). If this is the first time you
are partitioning, you will need to configure your existing master as the
new "default". This will let Phabricator interact with it, but won't send
new "default". This will let Phorge interact with it, but won't send
any traffic to it yet.
- Run `bin/storage partition`.
- Run `bin/storage upgrade` to initialize the schemata on the new hosts.
- Stop writes to the applications you want to move by putting Phabricator
- Stop writes to the applications you want to move by putting Phorge
in read-only mode, or shutting down the webserver and daemons, or telling
everyone not to touch anything.
- Dump the data from the application databases on the old master.
- Load the data into the application databases on the new master.
- Reconfigure the "partition" setup so that Phabricator knows the databases
- Reconfigure the "partition" setup so that Phorge knows the databases
have moved.
- Run `bin/storage partition`.
- While still in read-only mode, check that all the data appears to be
@ -178,7 +178,7 @@ end-to-end before performing a larger, higher-stakes migration.
How Partitioning Works
======================
If you have multiple masters, Phabricator keeps the entire set of schemata up
If you have multiple masters, Phorge keeps the entire set of schemata up
to date on all of them. When you run `bin/storage upgrade` or other storage
management commands, they generally affect all masters (if they do not, they
will prompt you to be more specific).
@ -197,7 +197,7 @@ There are some exceptions to this rule. For example, all masters keep track
of which patches have been applied to that particular master so that
`bin/storage upgrade` can upgrade hosts correctly.
Phabricator does not perform joins across logical databases, so there are no
Phorge does not perform joins across logical databases, so there are no
meaningful differences in runtime behavior if two applications are on the same
physical host or different physical hosts.
@ -212,7 +212,7 @@ only one master.
`persistent` //(bool)// Enables persistent connections. Defaults to off.
With persistent connections enabled, Phabricator will keep a pool of database
With persistent connections enabled, Phorge will keep a pool of database
connections open between web requests and reuse them when serving subsequent
requests.
@ -224,7 +224,7 @@ because requests are unable to bind to an outbound port, enabling this option
is likely to fix the issue. This option may also slightly increase performance.
The cost of using persistent connections is that you may need to raise the
MySQL `max_connections` setting: although Phabricator will make far fewer
MySQL `max_connections` setting: although Phorge will make far fewer
connections, the connections it does make will be longer-lived. Raising this
setting will increase MySQL memory requirements and may run into other limits,
like `open_files_limit`, which may also need to be raised.

56
src/docs/user/cluster/cluster_repositories.diviner
View file

@ -1,12 +1,12 @@
@title Cluster: Repositories
@group cluster
Configuring Phabricator to use multiple repository hosts.
Configuring Phorge to use multiple repository hosts.
Overview
========
If you use Git, you can deploy Phabricator with multiple repository hosts,
If you use Git, you can deploy Phorge with multiple repository hosts,
configured so that each host is readable and writable. The advantages of doing
this are:
@ -22,11 +22,11 @@ This configuration is not currently supported with Subversion or Mercurial.
How Reads and Writes Work
=========================
Phabricator repository replicas are multi-master: every node is readable and
Phorge repository replicas are multi-master: every node is readable and
writable, and a cluster of nodes can (almost always) survive the loss of any
arbitrary subset of nodes so long as at least one node is still alive.
Phabricator maintains an internal version for each repository, and increments
Phorge maintains an internal version for each repository, and increments
it when the repository is mutated.
Before responding to a read, replicas make sure their version of the repository
@ -77,7 +77,7 @@ similar agents of other rogue nations is beyond the scope of this document.
Repository Hosts
================
Repository hosts must run a complete, fully configured copy of Phabricator,
Repository hosts must run a complete, fully configured copy of Phorge,
including a webserver. They must also run a properly configured `sshd`.
If you are converting existing hosts into cluster hosts, you may need to
@ -123,7 +123,7 @@ Almanac:
- First, register at least one device according to the device clustering
instructions.
- Create a new service of type **Phabricator Cluster: Repository** in
- Create a new service of type **Phorge Cluster: Repository** in
Almanac.
- Bind this service to all the interfaces on the device or devices.
- For each binding, add a `protocol` key with one of these values:
@ -170,11 +170,11 @@ To migrate a repository back off a service, use this command:
$ ./bin/repository clusterize <repository> --remove-service
```
This command only changes how Phabricator connects to the repository; it does
This command only changes how Phorge connects to the repository; it does
not move any data or make any complex structural changes.
When Phabricator needs information about a non-clustered repository, it just
runs a command like `git log` directly on disk. When Phabricator needs
When Phorge needs information about a non-clustered repository, it just
runs a command like `git log` directly on disk. When Phorge needs
information about a clustered repository, it instead makes a service call to
another server, asking that server to run `git log` instead.
@ -213,9 +213,9 @@ To expand an existing cluster, follow these general steps:
For instructions on configuring and registering devices, see
@{article:Cluster: Devices}.
As soon as you add active bindings to a service, Phabricator will begin
As soon as you add active bindings to a service, Phorge will begin
synchronizing repositories and sending traffic to the new device. You do not
need to copy any repository data to the device: Phabricator will automatically
need to copy any repository data to the device: Phorge will automatically
synchronize it.
If you have a large amount of repository data, you may want to help this
@ -297,7 +297,7 @@ Configuration}.
This screen shows all the configured devices which are hosting the repository
and the available version on that device.
**Version**: When a repository is mutated by a push, Phabricator increases
**Version**: When a repository is mutated by a push, Phorge increases
an internal version number for the repository. This column shows which version
is on disk on the corresponding device.
@ -335,9 +335,9 @@ There are three major cluster failure modes:
are reachable.
- **Ambiguous Leaders**: The internal state of the repository is unclear.
Phabricator can detect these issues, and responds by freezing the repository
Phorge can detect these issues, and responds by freezing the repository
(usually preventing all reads and writes) until the issue is resolved. These
conditions are normally rare and very little data is at risk, but Phabricator
conditions are normally rare and very little data is at risk, but Phorge
errs on the side of caution and requires decisions which may result in data
loss to be confirmed by a human.
@ -357,13 +357,13 @@ in a brief window during and immediately after a write. This looks like this:
- During or immediately after the write, lightning strikes the server
and destroys it.
Phabricator can not commit changes to a working copy (stored on disk) and to
Phorge can not commit changes to a working copy (stored on disk) and to
the global state (stored in a database) atomically, so there is necessarily a
narrow window between committing these two different states when some tragedy
can befall a server, leaving the global and local views of the repository state
possibly divergent.
In these cases, Phabricator fails into a frozen state where further writes
In these cases, Phorge fails into a frozen state where further writes
are not permitted until the failure is investigated and resolved. When a
repository is frozen in this way it remains readable.
@ -391,7 +391,7 @@ was complete on disk. To demote the device and release the write lock, run this
command:
```
phabricator/ $ ./bin/repository thaw <repository> --demote <device>
phorge/ $ ./bin/repository thaw <repository> --demote <device>
```
{icon exclamation-triangle, color="yellow"} Any committed but unacknowledged
@ -411,7 +411,7 @@ this:
and destroys it.
Here, all of the "leader" devices with the most up-to-date copy of the
repository have been lost. Phabricator will freeze the repository refuse to
repository have been lost. Phorge will freeze the repository refuse to
serve requests because it can not serve reads consistently and can not accept
new writes without data loss.
@ -424,7 +424,7 @@ quickly, you can use the monitoring console to review which changes are
present on the leaders but not present on the followers by examining the
push logs.
If you are comfortable discarding these changes, you can instruct Phabricator
If you are comfortable discarding these changes, you can instruct Phorge
that it can forget about the leaders by doing this:
- Disable the service bindings to all of the leader devices so they are no
@ -434,7 +434,7 @@ that it can forget about the leaders by doing this:
To demote a device, run this command:
```
phabricator/ $ ./bin/repository thaw rXYZ --demote repo002.corp.net
phorge/ $ ./bin/repository thaw rXYZ --demote repo002.corp.net
```
{icon exclamation-triangle, color="red"} Any data which is only present on
@ -450,7 +450,7 @@ devices by using `--demote <service>` and `--all-repositories`. **This is
dangerous and discards all unreplicated data in any repository on any device.**
```
phabricator/ $ ./bin/repository thaw --demote repo.corp.net --all-repositories
phorge/ $ ./bin/repository thaw --demote repo.corp.net --all-repositories
```
After you do this, continue below to promote a leader and restore the cluster
@ -474,15 +474,15 @@ error, like these:
If you are moving repositories into cluster services, you can also reach this
state if you use `clusterize` to associate a repository with a service that is
bound to multiple active devices. In this case, Phabricator will not know which
bound to multiple active devices. In this case, Phorge will not know which
device or devices have up-to-date information.
When Phabricator can not tell which device in a cluster is a leader, it freezes
When Phorge can not tell which device in a cluster is a leader, it freezes
the cluster because it is possible that some devices have less data and others
have more, and if it chooses a leader arbitrarily it may destroy some data
which you would prefer to retain.
To resolve this, you need to tell Phabricator which device has the most
To resolve this, you need to tell Phorge which device has the most
up-to-date data and promote that device to become a leader. If you know all
devices have the same data, you are free to promote any device.
@ -496,7 +496,7 @@ Once you have identified a device which has data you're happy with, use
device will become authoritative:
```
phabricator/ $ ./bin/repository thaw rXYZ --promote repo002.corp.net
phorge/ $ ./bin/repository thaw rXYZ --promote repo002.corp.net
```
{icon exclamation-triangle, color="red"} Any data which is only present on
@ -514,7 +514,7 @@ If something issues a `--force` push that destroys branch heads, the mutation
will propagate to the replicas.
You may be able to manually restore the branches by using tools like the
Phabricator push log or the Git reflog so it is less important to retain
Phorge push log or the Git reflog so it is less important to retain
repository snapshots than database snapshots, but it is still possible for
data to be lost permanently, especially if you don't notice the problem for
some time.
@ -543,8 +543,8 @@ changes may either encounter conflicts or encounter problems with change
propagation.
You can encounter conflicts because directly modifying the working copy on disk
won't prevent users or Phabricator itself from performing writes to the same
working copy at the same time. Phabricator does not compromise the lower-level
won't prevent users or Phorge itself from performing writes to the same
working copy at the same time. Phorge does not compromise the lower-level
locks provided by the VCS so this is theoretically safe -- and this rarely
causes any significant problems in practice -- but doesn't make things any
simpler or easier.

16
src/docs/user/cluster/cluster_search.diviner
View file

@ -4,10 +4,10 @@
Overview
========
You can configure Phabricator to connect to one or more fulltext search
You can configure Phorge to connect to one or more fulltext search
services.
By default, Phabricator will use MySQL for fulltext search. This is suitable
By default, Phorge will use MySQL for fulltext search. This is suitable
for most installs. However, alternate engines are supported.
@ -33,10 +33,10 @@ like this:
]
```
When a user makes a change to a document, Phabricator writes the updated
When a user makes a change to a document, Phorge writes the updated
document into every configured, writable fulltext service.
When a user issues a query, Phabricator tries configured, readable services
When a user issues a query, Phorge tries configured, readable services
in order until it is able to execute the query successfully.
These options are supported by all service types:
@ -141,7 +141,7 @@ After adding new search services, you will need to rebuild document indexes
on them. To do this, first initialize the services:
```
phabricator/ $ ./bin/search init
phorge/ $ ./bin/search init
```
This will perform index setup steps and other one-time configuration.
@ -149,14 +149,14 @@ This will perform index setup steps and other one-time configuration.
To populate documents in all indexes, run this command:
```
phabricator/ $ ./bin/search index --force --background --type all
phorge/ $ ./bin/search index --force --background --type all
```
This initiates an exhaustive rebuild of the document indexes. To get a more
detailed list of indexing options available, run:
```
phabricator/ $ ./bin/search help index
phorge/ $ ./bin/search help index
```
@ -166,7 +166,7 @@ Advanced Example
This is a more advanced example which shows a configuration with multiple
different services in different roles. In this example:
- Phabricator is using an Elasticsearch 2 service as its primary fulltext
- Phorge is using an Elasticsearch 2 service as its primary fulltext
service.
- An Elasticsearch 5 service is online, but only receiving writes.
- The MySQL service is serving as a backup if Elasticsearch fails.

8
src/docs/user/cluster/cluster_ssh.diviner
View file

@ -1,12 +1,12 @@
@title Cluster: SSH Servers
@group cluster
Configuring Phabricator to use multiple SSH servers.
Configuring Phorge to use multiple SSH servers.
Overview
========
You can run Phabricator on multiple SSH servers. The advantages of doing this
You can run Phorge on multiple SSH servers. The advantages of doing this
are:
- you can completely survive the loss of multiple SSH hosts.
@ -24,14 +24,14 @@ Adding SSH Hosts
After configuring repositories in cluster mode, you can add more web hosts
at any time.
First, deploy the Phabricator software and configuration to a host, then
First, deploy the Phorge software and configuration to a host, then
register the host as a cluster device if it is not already registered (for
help, see @{article:Cluster: Devices}.)
Once the host is registered, start the SSH server, and then add the host to the
SSH load balancer pool.
Phabricator SSH servers are stateless, so you can pull them in and out of
Phorge SSH servers are stateless, so you can pull them in and out of
production freely.
You may also want to run web services on these hosts, since the service is very

8
src/docs/user/cluster/cluster_webservers.diviner
View file

@ -1,12 +1,12 @@
@title Cluster: Web Servers
@group cluster
Configuring Phabricator to use multiple web servers.
Configuring Phorge to use multiple web servers.
Overview
========
You can run Phabricator on multiple web servers. The advantages of doing this
You can run Phorge on multiple web servers. The advantages of doing this
are:
- you can completely survive the loss of multiple web hosts; and
@ -22,14 +22,14 @@ Adding Web Hosts
After configuring repositories in cluster mode, you can add more web hosts
at any time.
First, deploy the Phabricator software and configuration to a host, then
First, deploy the Phorge software and configuration to a host, then
register the host as a cluster device if it is not already registered (for
help, see @{article:Cluster: Devices}.)
Once the host is registered, start the web server, and then add the host to the
load balancer pool.
Phabricator web servers are stateless, so you can pull them in and out of
Phorge web servers are stateless, so you can pull them in and out of
production freely.
You may also want to run SSH services on these hosts, since the service is very

32
src/docs/user/configuration/advanced_configuration.diviner
View file

@ -1,21 +1,21 @@
@title Configuration User Guide: Advanced Configuration
@group config
Configuring Phabricator for multiple environments.
Configuring Phorge for multiple environments.
= Overview =
Phabricator reads configuration from multiple sources. This document explains
Phorge reads configuration from multiple sources. This document explains
the configuration stack and how to set up advanced configuration sources, which
may be useful for deployments with multiple environments (e.g., development and
production).
This is a complicated topic for advanced users. You do not need to understand
this topic to install Phabricator.
this topic to install Phorge.
= Configuration Sources =
Phabricator supports the following configuration sources, from highest priority
Phorge supports the following configuration sources, from highest priority
to lowest priority:
- **Database**: Values are stored in the database and edited from the web UI
@ -26,14 +26,14 @@ to lowest priority:
- **Config Files**: Values are stored in a config file in `conf/`. The file
to use is selected by writing to `conf/local/ENVIRONMENT`, or setting the
`PHABRICATOR_ENV` configuration variable. See below for more information.
- **Defaults**: Defaults hard-coded in the Phabricator source, which can not
- **Defaults**: Defaults hard-coded in the Phorge source, which can not
be edited. They have the lowest priority, and all other settings override
them.
Normally, you install and configure Phabricator by writing enough configuration
Normally, you install and configure Phorge by writing enough configuration
into the local config to get access to the database configuration (e.g., the
MySQL username, password, and hostname), then use the web interface to further
configure Phabricator.
configure Phorge.
= Configuration Files =
@ -52,7 +52,7 @@ examples below.
First, write an `exampleconfig.conf.php` file here (rename it according to the
name you chose):
phabricator/conf/custom/exampleconfig.conf.php
phorge/conf/custom/exampleconfig.conf.php
Its contents should look like this:
@ -77,14 +77,14 @@ a config like this:
== Selecting a Configuration File ==
To select a configuration file, write the name of the file (relative to
`phabricator/conf/`) to `phabricator/conf/local/ENVIRONMENT`. For example, to
select `phabricator/conf/custom/exampleconfig.conf.php`, you would write
"custom/exampleconfig" to `phabricator/conf/local/ENVIRONMENT`:
`phorge/conf/`) to `phorge/conf/local/ENVIRONMENT`. For example, to
select `phorge/conf/custom/exampleconfig.conf.php`, you would write
"custom/exampleconfig" to `phorge/conf/local/ENVIRONMENT`:
phabricator/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
phabricator/ $ cat conf/local/ENVIRONMENT
phorge/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
phorge/ $ cat conf/local/ENVIRONMENT
custom/exampleconfig
phabricator/ $
phorge/ $
You can also set the environmental variable `PHABRICATOR_ENV`. This is more
involved but may be easier in some deployment environments. Note that this needs
@ -107,8 +107,8 @@ setenv.add-environment = (
)
```
After creating and selecting a configuration file, restart Phabricator (for
help, see @{article:Restarting Phabricator}). Any configuration you set should
After creating and selecting a configuration file, restart Phorge (for
help, see @{article:Restarting Phorge}). Any configuration you set should
take effect immediately, and your file should be visible in the Config
application when examining configuration.

46
src/docs/user/configuration/configuration_guide.diviner
View file

@ -1,7 +1,7 @@
@title Configuration Guide
@group config
This document contains basic configuration instructions for Phabricator.
This document contains basic configuration instructions for Phorge.
= Prerequisites =
@ -11,7 +11,7 @@ If you haven't, see @{article:Installation Guide}.
The next steps are:
- Configure your webserver (Apache, nginx, or lighttpd).
- Access Phabricator with your browser.
- Access Phorge with your browser.
- Follow the instructions to complete setup.
= Webserver: Configuring Apache =
@ -24,8 +24,8 @@ documentation for help. Make sure `mod_php` and `mod_rewrite` are enabled,
and `mod_ssl` if you intend to set up SSL.
If you haven't already, set up a domain name to point to the host you're
installing on. You can either install Phabricator on a subdomain (like
phabricator.example.com) or an entire domain, but you can not install it in
installing on. You can either install Phorge on a subdomain (like
phorge.example.com) or an entire domain, but you can not install it in
some subdirectory of an existing website. Navigate to whatever domain you're
going to use and make sure Apache serves you something to verify that DNS
is correctly configured.
@ -33,32 +33,32 @@ is correctly configured.
NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like
'http://example/'. Some web browsers will not set cookies otherwise.
Now create a VirtualHost entry for Phabricator. It should look something like
Now create a VirtualHost entry for Phorge. It should look something like
this:
name=httpd.conf
<VirtualHost *>
# Change this to the domain which points to your host.
ServerName phabricator.example.com
ServerName phorge.example.com
# Change this to the path where you put 'phabricator' when you checked it
# out from GitHub when following the Installation Guide.
# Change this to the path where you put 'phorge' when you checked it
# out from the upstream when following the Installation Guide.
#
# Make sure you include "/webroot" at the end!
DocumentRoot /path/to/phabricator/webroot
DocumentRoot /path/to/phorge/webroot
RewriteEngine on
RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
</VirtualHost>
If Apache isn't currently configured to serve documents out of the directory
where you put Phabricator, you may also need to add `<Directory />` section. The
where you put Phorge, you may also need to add `<Directory />` section. The
syntax for this section depends on which version of Apache you're running.
(If you don't know, you can usually figure this out by running `httpd -v`.)
For Apache versions older than 2.4, use this:
name="Apache Older Than 2.4"
<Directory "/path/to/phabricator/webroot">
<Directory "/path/to/phorge/webroot">
Order allow,deny
Allow from all
</Directory>
@ -66,7 +66,7 @@ For Apache versions older than 2.4, use this:
For Apache versions 2.4 and newer, use this:
name="Apache 2.4 and Newer"
<Directory "/path/to/phabricator/webroot">
<Directory "/path/to/phorge/webroot">
Require all granted
</Directory>
@ -81,8 +81,8 @@ For nginx, use a configuration like this:
name=nginx.conf
server {
server_name phabricator.example.com;
root /path/to/phabricator/webroot;
server_name phorge.example.com;
root /path/to/phorge/webroot;
location / {
index index.php;
@ -121,8 +121,8 @@ up to their sections.
For lighttpd, add a section like this to your lighttpd.conf:
$HTTP["host"] =~ "phabricator(\.example\.com)?" {
server.document-root = "/path/to/phabricator/webroot"
$HTTP["host"] =~ "phorge(\.example\.com)?" {
server.document-root = "/path/to/phorge/webroot"
url.rewrite-once = (
# This simulates QSA ("query string append") mode in apache
"^(/[^?]*)\?(.*)" => "/index.php?__path__=$1&$2",
@ -167,22 +167,22 @@ no one else will be able to sign up or log in. For more information, see
During setup, you'll need to configure MySQL. To do this, get MySQL running and
verify you can connect to it. Consult the MySQL documentation for help. When
MySQL works, you need to load the Phabricator schemata into it. To do this, run:
MySQL works, you need to load the Phorge schemata into it. To do this, run:
phabricator/ $ ./bin/storage upgrade
phorge/ $ ./bin/storage upgrade
If your configuration uses an unprivileged user to connect to the database, you
may have to override the default user so the schema changes can be applied with
root or some other admin user:
phabricator/ $ ./bin/storage upgrade --user <user> --password <password>
phorge/ $ ./bin/storage upgrade --user <user> --password <password>
You can avoid the prompt the script issues by passing the `--force` flag (for
example, if you are scripting the upgrade process).
phabricator/ $ ./bin/storage upgrade --force
phorge/ $ ./bin/storage upgrade --force
NOTE: When you update Phabricator, run `storage upgrade` again to apply any
NOTE: When you update Phorge, run `storage upgrade` again to apply any
new updates.
= Next Steps =
@ -200,7 +200,7 @@ Continue by:
@{article:Configuring a Preamble Script}; or
- configuring where uploaded files and attachments will be stored with
@{article:Configuring File Storage}; or
- configuring Phabricator so it can send mail with
- configuring Phorge so it can send mail with
@{article:Configuring Outbound Email}; or
- configuring inbound mail with @{article:Configuring Inbound Email}; or
- importing repositories with @{article:Diffusion User Guide}; or
@ -209,4 +209,4 @@ Continue by:
@{article:Notifications User Guide: Setup and Configuration}; or
- configuring backups with
@{article:Configuring Backups and Performing Migrations}; or
- contributing to Phabricator with @{article:Contributor Introduction}.
- contributing to Phorge with @{article:Contributor Introduction}.

32
src/docs/user/configuration/configuration_locked.diviner
View file

@ -24,7 +24,7 @@ Locked Configuration
can edit it from the CLI instead, with `bin/config`:
```
phabricator/ $ ./bin/config set <key> <value>
phorge/ $ ./bin/config set <key> <value>
```
Some configuration options take complicated values which can be difficult
@ -42,7 +42,7 @@ file:
Then, set it with `--stdin` like this:
```
phabricator/ $ ./bin/config set <key> --stdin < config.json
phorge/ $ ./bin/config set <key> --stdin < config.json
```
A few settings have alternate CLI tools. Refer to the setting page for
@ -57,13 +57,13 @@ locked include:
**Required for bootstrapping**: Some options, like `mysql.host`, must be
available before Phabricator can read configuration from the database.
available before Phorge can read configuration from the database.
If you stored `mysql.host` only in the database, Phabricator would not know how
If you stored `mysql.host` only in the database, Phorge would not know how
to connect to the database in order to read the value in the first place.
These options must be provided in a configuration source which is read earlier
in the bootstrapping process, before Phabricator connects to the database.
in the bootstrapping process, before Phorge connects to the database.
**Errors could not be fixed from the web UI**: Some options, like
@ -83,7 +83,7 @@ attacker who has gained access to an administrator account in order to gain
greater access.
For example, an attacker who could modify `cluster.mailers` (and other
similar options), could potentially reconfigure Phabricator to send mail
similar options), could potentially reconfigure Phorge to send mail
through an evil server they controlled, then trigger password resets on other
user accounts to compromise them.
@ -105,8 +105,8 @@ administrator accounts) from reading them.
You can review (and edit) hidden configuration from the CLI:
```
phabricator/ $ ./bin/config get <key>
phabricator/ $ ./bin/config set <key> <value>
phorge/ $ ./bin/config get <key>
phorge/ $ ./bin/config set <key> <value>
```
@ -117,12 +117,12 @@ Locked Configuration With Database Values
You may receive a setup issue warning you that a locked configuration key has a
value set in the database. Most commonly, this is because:
- In some earlier version of Phabricator, this configuration was not locked.
- In some earlier version of Phorge, this configuration was not locked.
- In the past, you or some other administrator used the web UI to set a
value. This value was written to the database.
- In a later version of the software, the value became locked.
When Phabricator was originally released, locked configuration did not yet
When Phorge was originally released, locked configuration did not yet
exist. Locked configuration was introduced later, and then configuration options
were gradually locked for a long time after that.
@ -134,10 +134,10 @@ to lock the value.
Locking values was more common in the past, and it is now relatively rare for
an unlocked value to become locked: when new values are introduced, they are
generally locked or hidden appropriately. In most cases, this setup issue only
affects installs that have used Phabricator for a long time.
affects installs that have used Phorge for a long time.
At time of writing (February 2019), Phabricator currently respects these old
database values. However, some future version of Phabricator will refuse to
At time of writing (February 2019), Phorge currently respects these old
database values. However, some future version of Phorge will refuse to
read locked configuration from the database, because this improves security if
an attacker manages to find a way to bypass restrictions on editing locked
configuration from the web UI.
@ -147,19 +147,19 @@ you should move these configuration values from the database to a local config
file. Usually, you'll do this by first copying the value from the database:
```
phabricator/ $ ./bin/config get <key>
phorge/ $ ./bin/config get <key>
```
...into local configuration:
```
phabricator/ $ ./bin/config set <key> <value>
phorge/ $ ./bin/config set <key> <value>
```
...and then removing the database value:
```
phabricator/ $ ./bin/config delete --database <key>
phorge/ $ ./bin/config delete --database <key>
```
See @{Configuration User Guide: Advanced Configuration} for some more detailed

12
src/docs/user/configuration/configuring_accounts_and_registration.diviner
View file

@ -1,12 +1,12 @@
@title Configuring Accounts and Registration
@group config
Describes how to configure user access to Phabricator.
Describes how to configure user access to Phorge.
Overview
========
Phabricator supports a number of login systems. You can enable or disable these
Phorge supports a number of login systems. You can enable or disable these
systems to configure who can register for and access your install, and how users
with existing accounts can login.
@ -18,7 +18,7 @@ support logging in with other credentials. For example:
- **LDAP:** Users use LDAP credentials to log in or register.
- **OAuth:** Users use accounts on a supported OAuth2 provider (like
GitHub, Facebook, or Google) to log in or register.
- **Other Providers:** More providers are available, and Phabricator
- **Other Providers:** More providers are available, and Phorge
can be extended with custom providers. See the "Auth" application for
a list of available providers.
@ -26,14 +26,14 @@ By default, no providers are enabled. You must use the "Auth" application to
add one or more providers after you complete the installation process.
After you add a provider, you can link it to existing accounts (for example,
associate an existing Phabricator account with a GitHub OAuth account) or users
associate an existing Phorge account with a GitHub OAuth account) or users
can use it to register new accounts (assuming you enable these options).
Recovering Inaccessible Accounts
================================
If you accidentally lock yourself out of Phabricator (for example, by disabling
If you accidentally lock yourself out of Phorge (for example, by disabling
all authentication providers), you can normally use the "send a login link"
action from the login screen to email yourself a login link and regain access
to your account.
@ -43,7 +43,7 @@ can use the `bin/auth` script to recover access to an account. To recover
access, run:
```
phabricator/ $ ./bin/auth recover <username>
phorge/ $ ./bin/auth recover <username>
```
...where `<username>` is the account username you want to recover access

40
src/docs/user/configuration/configuring_backups.diviner
View file

@ -1,21 +1,21 @@
@title Configuring Backups and Performing Migrations
@group config
Advice for backing up Phabricator, or migrating from one machine to another.
Advice for backing up Phorge, or migrating from one machine to another.
Overview
========
Phabricator does not currently have a comprehensive backup system, but creating
backups is not particularly difficult and Phabricator does have a few basic
Phorge does not currently have a comprehensive backup system, but creating
backups is not particularly difficult and Phorge does have a few basic
tools which can help you set up a reasonable process. In particular, the things
which needs to be backed up are:
- the MySQL databases;
- hosted repositories;
- uploaded files; and
- your Phabricator configuration files.
- your Phorge configuration files.
This document discusses approaches for backing up this data.
@ -24,25 +24,25 @@ same steps you would if you were creating a backup and then restoring it, you
will just backup the old machine and then restore the data onto the new
machine.
WARNING: You need to restart Phabricator after restoring data.
WARNING: You need to restart Phorge after restoring data.
Restarting Phabricator after performing a restore makes sure that caches are
Restarting Phorge after performing a restore makes sure that caches are
flushed properly. For complete instructions, see
@{article:Restarting Phabricator}.
@{article:Restarting Phorge}.
Backup: MySQL Databases
=======================
Most of Phabricator's data is stored in MySQL, and it's the most important thing
Most of Phorge's data is stored in MySQL, and it's the most important thing
to back up. You can run `bin/storage dump` to get a dump of all the MySQL
databases. This is a convenience script which just runs a normal `mysqldump`,
but will only dump databases Phabricator owns.
but will only dump databases Phorge owns.
Since most of this data is compressible, it may be helpful to run it through
gzip prior to storage. For example:
phabricator/ $ ./bin/storage dump --compress --output backup.sql.gz
phorge/ $ ./bin/storage dump --compress --output backup.sql.gz
Then store the backup somewhere safe, like in a box buried under an old tree
stump. No one will ever think to look for it there.
@ -59,7 +59,7 @@ to uncompress it first, if you compressed it prior to storage.)
Backup: Hosted Repositories
===========================
If you host repositories in Phabricator, you should back them up. You can use
If you host repositories in Phorge, you should back them up. You can use
`bin/repository list-paths` to show the local paths on disk for each
repository. To back them up, copy them elsewhere.
@ -87,11 +87,11 @@ need to do any additional work.
**Amazon S3**: If you use Amazon S3, redundancy and backups are built in to the
service. This is probably sufficient for most installs. If you trust Amazon with
your data //except not really//, you can backup your S3 bucket outside of
Phabricator.
Phorge.
**Local Disk**: If you use the local disk storage engine, you'll need to back up
files manually. You can do this by creating a copy of the root directory where
you told Phabricator to put files (the `storage.local-disk.path` configuration
you told Phorge to put files (the `storage.local-disk.path` configuration
setting).
For more information about configuring how files are stored, see
@ -108,15 +108,15 @@ Backup: Configuration Files
===========================
You should also backup your configuration files, and any scripts you use to
deploy or administrate Phabricator (like a customized upgrade script). The best
deploy or administrate Phorge (like a customized upgrade script). The best
way to do this is to check them into a private repository somewhere and just use
whatever backup process you already have in place for repositories. Just copying
them somewhere will work fine too, of course.
In particular, you should backup this configuration file which Phabricator
In particular, you should backup this configuration file which Phorge
creates:
phabricator/conf/local/local.json
phorge/conf/local/local.json
This file contains all of the configuration settings that have been adjusted
by using `bin/config set <key> <value>`.
@ -126,14 +126,14 @@ Restore: Configuration Files
============================
To restore configuration files, just copy them into the right locations. Copy
your backup of `local.json` to `phabricator/conf/local/local.json`.
your backup of `local.json` to `phorge/conf/local/local.json`.
Security
========
MySQL dumps have no builtin encryption and most data in Phabricator is stored in
MySQL dumps have no builtin encryption and most data in Phorge is stored in
a raw, accessible form, so giving a user access to backups is a lot like giving
them shell access to the machine Phabricator runs on. In particular, a user who
them shell access to the machine Phorge runs on. In particular, a user who
has the backups can:
- read data that policies do not permit them to see;
@ -141,7 +141,7 @@ has the backups can:
- read other users' session and conduit tokens and impersonate them.
Some of this information is durable, so disclosure of even a very old backup may
present a risk. If you restrict access to the Phabricator host or database, you
present a risk. If you restrict access to the Phorge host or database, you
should also restrict access to the backups.

14
src/docs/user/configuration/configuring_encryption.diviner
View file

@ -6,14 +6,14 @@ Setup guide for configuring encryption.
Overview
========
Phabricator supports at-rest encryption of uploaded file data stored in the
Phorge supports at-rest encryption of uploaded file data stored in the
"Files" application.
Configuring at-rest file data encryption does not encrypt any other data or
resources. In particular, it does not encrypt the database and does not encrypt
Passphrase credentials.
Attackers who compromise a Phabricator host can read the master key and decrypt
Attackers who compromise a Phorge host can read the master key and decrypt
the data. In most configurations, this does not represent a significant
barrier above and beyond accessing the file data. Thus, configuring at-rest
encryption is primarily useful for two types of installs:
@ -81,7 +81,7 @@ Format: Raw Data
The `raw` storage format is automatically selected for all newly uploaded
file data if no key is marked as the `default` key in the keyring. This is
the behavior of Phabricator if you haven't configured anything.
the behavior of Phorge if you haven't configured anything.
This format stores raw data without modification.
@ -104,7 +104,7 @@ length, then base64 encoded when represented in `keyring`.
You can generate a valid, properly encoded AES256 master key with this command:
```
phabricator/ $ ./bin/files generate-key --type aes-256-cbc
phorge/ $ ./bin/files generate-key --type aes-256-cbc
```
This mode is generally similar to the default server-side encryption mode
@ -134,7 +134,7 @@ default.
To change the format of an individual file, run this command:
```
phabricator/ $ ./bin/files encode --as <format> F123 [--key <key>]
phorge/ $ ./bin/files encode --as <format> F123 [--key <key>]
```
This will change the storage format of the specified file.
@ -167,7 +167,7 @@ to leave the old key in place for now so existing data can be decrypted.
To cycle an individual file, run this command:
```
phabricator/ $ ./bin/files cycle F123
phorge/ $ ./bin/files cycle F123
```
Verify that cycling worked properly by examining the command output and
@ -177,7 +177,7 @@ can cycle additional files to gain additional confidence.
You can cycle all files with this command:
```
phabricator/ $ ./bin/files cycle --all
phorge/ $ ./bin/files cycle --all
```
Once all files have been cycled, remove the old master key from the keyring.

34
src/docs/user/configuration/configuring_file_domain.diviner
View file

@ -6,7 +6,7 @@ Setup guide for an alternate file domain or CDN.
Overview
========
Serving files that users upload from the same domain that Phabricator runs on
Serving files that users upload from the same domain that Phorge runs on
is a security risk.
In general, doing this creates a risk that users who have permission to upload
@ -17,7 +17,7 @@ history of security issues). The attacker can then trick another user into
executing the file and gain access to their session.
The best way to mitigate this threat is to serve files from a separate domain.
For example, if Phabricator is hosted at `https://phabricator.example.com/`,
For example, if Phorge is hosted at `https://phorge.example.com/`,
you can serve files from `https://files.exampleusercontent.com/`.
The alternate file domain should be a completely different domain from your
@ -48,7 +48,7 @@ CloudFront is a CDN service that's part of Amazon Web Services. It makes
particular sense to use if you're hosting your install in AWS.
To configure it, set up a new CloudFront distribution which is pointed at
your Phabricator install as an origin (make sure you point it at the primary
your Phorge install as an origin (make sure you point it at the primary
domain name of your install, not just a load balancer or instance). You do not
need to set up a new domain name, which makes setup a bit more straightforward.
@ -57,10 +57,10 @@ the **Allowed HTTP Methods** setting from `GET, HEAD` to
`GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`.
Once configured, accessing the distribution's domain name should return a
Phabricator error page indicating that Phabricator does not recognize the
Phorge error page indicating that Phorge does not recognize the
domain. If you see this page, it means you've configured things correctly.
Continue to "Configuring Phabricator", below.
Continue to "Configuring Phorge", below.
Approach: CloudFlare
========
@ -68,7 +68,7 @@ Approach: CloudFlare
WARNING: You should review all your CloudFlare settings, and be very
sure to turn off all JavaScript, HTML, CSS minification and
optimization features, including systems like "Rocket Loader". These
features will break Phabricator in strange and mysterious ways that
features will break Phorge in strange and mysterious ways that
are unpredictable. Only allow CloudFlare to cache files, and never
optimize them.
@ -76,23 +76,23 @@ optimize them.
To set up CloudFlare, you'll need to register a second domain and go through
their enrollment process to host the alternate domain on their servers. Use a
CNAME record to forward a subdomain to your Phabricator install.
CNAME record to forward a subdomain to your Phorge install.
CloudFlare will automatically generate SSL certificates for hosted domains,
which can significantly reduce the cost and complexity of setup.
Once configured, accessing the CNAME-forwarded subdomain should return a
Phabricator error page indicating that Phabricator does not recognize the
Phorge error page indicating that Phorge does not recognize the
domain. If you see this page, it means you've configured things correctly.
Continue to "Configuring Phabricator", below.
Continue to "Configuring Phorge", below.
Approach: Self Hosted
========
To do this, just set up a second domain exactly like your primary domain is
set up. When setup is complete, visiting the domain should return a Phabricator
error page indicating that Phabricator does not recognize the domain. This
set up. When setup is complete, visiting the domain should return a Phorge
error page indicating that Phorge does not recognize the domain. This
means that you've configured things correctly.
Note that if you use SSL (which you should), you'll also need to get a
@ -102,18 +102,18 @@ You can also configure a self-hosted domain to route through a caching server
to provide some of the performance benefits of a CDN, but this is advanced and
outside the scope of this documentation.
Continue to "Configuring Phabricator", below.
Continue to "Configuring Phorge", below.
Configuring Phabricator
Configuring Phorge
========
After you've set up a CDN or an alternate domain, configure Phabricator to
After you've set up a CDN or an alternate domain, configure Phorge to
recognize the domain. Run this command, providing the domain you have
configured in place of the `<domain>` token. You should include the protocol,
so an example domain might be `https://cdn.phabcdn.net/`.
so an example domain might be `https://cdn.examplecdn.com/`.
phabricator/ $ ./bin/config set security.alternate-file-domain <domain>
phorge/ $ ./bin/config set security.alternate-file-domain <domain>
Phabricator should now serve CSS, JS, images, profile pictures, and user
Phorge should now serve CSS, JS, images, profile pictures, and user
content through the file domain. You can verify this with "View Source" or
by downloading a file and checking the URL.

36
src/docs/user/configuration/configuring_file_storage.diviner
View file

@ -6,8 +6,8 @@ Setup file storage and support for large files.
Overview
========
This document describes how to configure Phabricator to support large file
uploads, and how to choose where Phabricator stores files.
This document describes how to configure Phorge to support large file
uploads, and how to choose where Phorge stores files.
There are two major things to configure:
@ -17,16 +17,16 @@ There are two major things to configure:
The following sections will guide you through this configuration.
How Phabricator Stores Files
How Phorge Stores Files
============================
Phabricator stores files in "storage engines", which are modular backends
Phorge stores files in "storage engines", which are modular backends
that implement access to some storage system (like MySQL, the filesystem, or
a cloud storage service like Amazon S3).
Phabricator stores large files by breaking them up into many chunks (a few
Phorge stores large files by breaking them up into many chunks (a few
megabytes in size) and storing the chunks in an underlying storage engine.
This makes it easier to implement new storage engines and gives Phabricator
This makes it easier to implement new storage engines and gives Phorge
more flexibility in managing file data.
The first section of this document discusses configuring your install so that
@ -45,7 +45,7 @@ of the stack. Generally, the minimum value of all the limits is the effective
one.
To upload large files, you need to increase all the limits to at least
**32MB**. This will allow you to upload file chunks, which will let Phabricator
**32MB**. This will allow you to upload file chunks, which will let Phorge
store arbitrarily large files.
The settings which limit file uploads are:
@ -62,20 +62,20 @@ somewhat larger than the desired maximum filesize.
- **lighttpd**: lighttpd limits requests with the lighttpd
`server.max-request-size` directive.
Set the applicable limit to at least **32MB**. Phabricator can not read these
Set the applicable limit to at least **32MB**. Phorge can not read these
settings, so it can not raise setup warnings if they are misconfigured.
**PHP**: PHP has several directives which limit uploads. These directives are
found in `php.ini`.
- **post_max_size**: Maximum POST request size PHP will accept. If you
exceed this, Phabricator will give you a useful error. This often defaults
to `8M`. Set this to at least `32MB`. Phabricator will give you a setup
exceed this, Phorge will give you a useful error. This often defaults
to `8M`. Set this to at least `32MB`. Phorge will give you a setup
warning about this if it is set too low.
- **memory_limit**: For some uploads, file data will be read into memory
before Phabricator can adjust the memory limit. If you exceed this, PHP
before Phorge can adjust the memory limit. If you exceed this, PHP
may give you a useful error, depending on your configuration. It is
recommended that you set this to `-1` to disable it. Phabricator will
recommended that you set this to `-1` to disable it. Phorge will
give you a setup warning about this if it is set too low.
You may also want to configure these PHP options:
@ -87,7 +87,7 @@ You may also want to configure these PHP options:
- **upload_max_filesize**: Maximum file size PHP will accept in a raw file
upload. This is not normally used when uploading files via drag-and-drop,
but affects some other kinds of file uploads. If you exceed this,
Phabricator will give you a useful error. This often defaults to `2M`. Set
Phorge will give you a useful error. This often defaults to `2M`. Set
this to at least `32MB`.
Once you've adjusted all this configuration, your server will be able to
@ -98,7 +98,7 @@ enable you to store arbitrarily large files.
Storage Engines
===============
Phabricator supports several different file storage engines:
Phorge supports several different file storage engines:
| Engine | Setup | Cost | Notes |
|--------|-------|------|-------|
@ -110,7 +110,7 @@ Phabricator supports several different file storage engines:
You can review available storage engines and their configuration by navigating
to {nav Applications > Files > Help/Options > Storage Engines} in the web UI.
By default, Phabricator is configured to store files up to 1MB in MySQL, and
By default, Phorge is configured to store files up to 1MB in MySQL, and
reject files larger than 1MB. To store larger files, you can either:
- increase the MySQL limit to at least 8MB; or
@ -172,7 +172,7 @@ Testing Storage Engines
=======================
You can test that things are correctly configured by dragging and dropping
a file onto the Phabricator home page. If engines have been configured
a file onto the Phorge home page. If engines have been configured
properly, the file should upload.
Migrating Files Between Engines
@ -183,11 +183,11 @@ script to perform migrations. For example, suppose you previously used MySQL but
recently set up S3 and want to migrate all your files there. First, migrate one
file to make sure things work:
phabricator/ $ ./bin/files migrate --engine amazon-s3 F12345
phorge/ $ ./bin/files migrate --engine amazon-s3 F12345
If that works properly, you can then migrate everything:
phabricator/ $ ./bin/files migrate --engine amazon-s3 --all
phorge/ $ ./bin/files migrate --engine amazon-s3 --all
You can use `--dry-run` to show which migrations would be performed without
taking any action. Run `bin/files help` for more options and information.

72
src/docs/user/configuration/configuring_inbound_email.diviner
View file

@ -2,15 +2,15 @@
@group config
This document contains instructions for configuring inbound email, so users
may interact with some Phabricator applications via email.
may interact with some Phorge applications via email.
Preamble
========
Phabricator can process inbound mail in two general ways:
Phorge can process inbound mail in two general ways:
**Handling Replies**: When users reply to email notifications about changes,
Phabricator can turn email into comments on the relevant discussion thread.
Phorge can turn email into comments on the relevant discussion thread.
**Creating Objects**: You can configure an address like `bugs@yourcompany.com`
to create new objects (like tasks) when users send email.
@ -21,7 +21,7 @@ broader set of changes to objects beyond commenting. (For example, you can use
To configure inbound mail, you will generally:
- Configure some mail domain to submit mail to Phabricator for processing.
- Configure some mail domain to submit mail to Phorge for processing.
- For handling replies, set `metamta.reply-handler-domain` in your
configuration.
- For handling email that creates objects, configure inbound addresses in the
@ -34,11 +34,11 @@ Configuration Overview
======================
Usually, the most challenging part of configuring inbound mail is getting mail
delivered to Phabricator for processing. This step can be made much easier if
you use a third-party mail service which can submit mail to Phabricator via
delivered to Phorge for processing. This step can be made much easier if
you use a third-party mail service which can submit mail to Phorge via
webhooks.
Some available approaches for delivering mail to Phabricator are:
Some available approaches for delivering mail to Phorge are:
| Receive Mail With | Setup | Cost | Notes |
|--------|-------|------|-------|
@ -47,37 +47,37 @@ Some available approaches for delivering mail to Phabricator are:
| SendGrid | Easy | Cheap | |
| Local MTA | Difficult | Free | Discouraged |
The remainder of this document walks through configuring Phabricator to
The remainder of this document walks through configuring Phorge to
receive mail, and then configuring your chosen transport to deliver mail
to Phabricator.
to Phorge.
Configuring "Reply" Email
=========================
By default, Phabricator uses a `noreply@phabricator.example.com` email address
By default, Phorge uses a `noreply@phorge.example.com` email address
as the "From" address when it sends mail. The exact address it uses can be
configured with `metamta.default-address`.
When a user takes an action that generates mail, Phabricator sets the
When a user takes an action that generates mail, Phorge sets the
"Reply-To" addresss for the mail to that user's name and address. This means
that users can reply to email to discuss changes, but: the conversation won't
be recorded in Phabricator; and users will not be able to use email commands
be recorded in Phorge; and users will not be able to use email commands
to take actions or make edits.
To change this behavior so that users can interact with objects in Phabricator
To change this behavior so that users can interact with objects in Phorge
over email, change the configuration key `metamta.reply-handler-domain` to some
domain you configure according to the instructions below, e.g.
`phabricator.example.com`. Once you set this key, email will use a
"Reply-To" like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
`phorge.example.com`. Once you set this key, email will use a
"Reply-To" like `T123+273+af310f9220ad@phorge.example.com`, which -- when
configured correctly, according to the instructions below -- will parse incoming
email and allow users to interact with Differential revisions, Maniphest tasks,
etc. over email.
If you don't want Phabricator to take up an entire domain (or subdomain) you
If you don't want Phorge to take up an entire domain (or subdomain) you
can configure a general prefix so you can use a single mailbox to receive mail
on. To make use of this set `metamta.single-reply-handler-prefix` to the
prefix of your choice, and Phabricator will prepend this to the "Reply-To"
prefix of your choice, and Phorge will prepend this to the "Reply-To"
mail address. This works because everything up to the first (optional) '+'
character in an email address is considered the receiver, and everything
after is essentially ignored.
@ -87,7 +87,7 @@ Configuring "Create" Email
==========================
You can set up application email addresses to allow users to create objects via
email. For example, you could configure `bugs@phabricator.example.com` to
email. For example, you could configure `bugs@phorge.example.com` to
create a Maniphest task out of any email which is sent to it.
You can find application email settings for each application at:
@ -104,7 +104,7 @@ with the `[ Content source ]` and/or `[ Receiving email address ]` fields to
route or handle objects based on which address mail was sent to.
You'll also need to configure the actual mail domain to submit mail to
Phabricator by following the instructions below. Phabricator will let you add
Phorge by following the instructions below. Phorge will let you add
any address as an application address, but can only process mail which is
actually delivered to it.
@ -130,7 +130,7 @@ authenticating senders in the general case (e.g., where you are an open source
project and need to interact with users whose email accounts you have no control
over).
You can also set `metamta.public-replies`, which will change how Phabricator
You can also set `metamta.public-replies`, which will change how Phorge
delivers email. Instead of sending each recipient a unique mail with a personal
reply-to address, it will send a single email to everyone with a public reply-to
address. This decreases security because anyone who can spoof a "From" address
@ -142,7 +142,7 @@ not received an email about an object can not blindly interact with it.
If you enable application email addresses, those addresses also use the weaker
"From" authentication mechanism.
NOTE: Phabricator does not currently attempt to verify "From" addresses because
NOTE: Phorge does not currently attempt to verify "From" addresses because
this is technically complex, seems unreasonably difficult in the general case,
and no installs have had a need for it yet. If you have a specific case where a
reasonable mechanism exists to provide sender verification (e.g., DKIM
@ -155,17 +155,17 @@ Testing and Debugging Inbound Email
===================================
You can use the `bin/mail` utility to test and review inbound mail. This can
help you determine if mail is being delivered to Phabricator or not:
help you determine if mail is being delivered to Phorge or not:
phabricator/ $ ./bin/mail list-inbound # List inbound messages.
phabricator/ $ ./bin/mail show-inbound # Show details about a message.
phorge/ $ ./bin/mail list-inbound # List inbound messages.
phorge/ $ ./bin/mail show-inbound # Show details about a message.
You can also test receiving mail, but note that this just simulates receiving
the mail and doesn't send any information over the network. It is
primarily aimed at developing email handlers: it will still work properly
if your inbound email configuration is incorrect or even disabled.
phabricator/ $ ./bin/mail receive-test # Receive test message.
phorge/ $ ./bin/mail receive-test # Receive test message.
Run `bin/mail help <command>` for detailed help on using these commands.
@ -179,7 +179,7 @@ like this:
- Configure a mail domain according to Mailgun's instructions.
- Add a Mailgun route with a `catch_all()` rule which takes the action
`forward("https://phabricator.example.com/mail/mailgun/")`. Replace the
`forward("https://phorge.example.com/mail/mailgun/")`. Replace the
example domain with your actual domain.
- Configure a mailer in `cluster.mailers` with your Mailgun API key.
@ -191,7 +191,7 @@ To process inbound mail from Postmark, configure this URI as your inbound
webhook URI in the Postmark control panel:
```
https://<phabricator.yourdomain.com>/mail/postmark/
https://<phorge.yourdomain.com>/mail/postmark/
```
See also the Postmark section in @{article:Configuring Outbound Email} for
@ -206,21 +206,21 @@ To use SendGrid, you need a SendGrid account with access to the "Parse API" for
inbound email. Provided you have such an account, configure it like this:
- Configure an MX record according to SendGrid's instructions, i.e. add
`phabricator.example.com MX 10 mx.sendgrid.net.` or similar.
`phorge.example.com MX 10 mx.sendgrid.net.` or similar.
- Go to the "Parse Incoming Emails" page on SendGrid
(<http://sendgrid.com/developer/reply>) and add the domain as the
"Hostname".
- Add the URL `https://phabricator.example.com/mail/sendgrid/` as the "Url",
- Add the URL `https://phorge.example.com/mail/sendgrid/` as the "Url",
using your domain (and HTTP instead of HTTPS if you are not configured with
SSL).
- If you get an error that the hostname "can't be located or verified", it
means your MX record is either incorrectly configured or hasn't propagated
yet.
- Set `metamta.reply-handler-domain` to `phabricator.example.com`
- Set `metamta.reply-handler-domain` to `phorge.example.com`
(whatever you configured the MX record for).
That's it! If everything is working properly you should be able to send email
to `anything@phabricator.example.com` and it should appear in
to `anything@phorge.example.com` and it should appear in
`bin/mail list-inbound` within a few seconds.
@ -264,10 +264,10 @@ probably means something like this:
- add your host to /etc/mail/local-host-names; and
- restart sendmail.
Now, you can actually configure sendmail to deliver to Phabricator. In
Now, you can actually configure sendmail to deliver to Phorge. In
`/etc/aliases`, add an entry like this:
phabricator: "| /path/to/phabricator/scripts/mail/mail_handler.php"
phorge: "| /path/to/phorge/scripts/mail/mail_handler.php"
If you use the `PHABRICATOR_ENV` environmental variable to select a
configuration, you can pass the value to the script as an argument:
@ -280,12 +280,12 @@ without an argument.
After making this change, run `sudo newaliases`. Now you likely need to symlink
this script into `/etc/smrsh/`:
sudo ln -s /path/to/phabricator/scripts/mail/mail_handler.php /etc/smrsh/
sudo ln -s /path/to/phorge/scripts/mail/mail_handler.php /etc/smrsh/
Finally, edit `/etc/mail/virtusertable` and add an entry like this:
@yourdomain.com phabricator@localhost
@yourdomain.com phorge@localhost
That will forward all mail to @yourdomain.com to the Phabricator processing
That will forward all mail to @yourdomain.com to the Phorge processing
script. Run `sudo /etc/mail/make` or similar and then restart sendmail with
`sudo /etc/init.d/sendmail restart`.

50
src/docs/user/configuration/configuring_outbound_email.diviner
View file

@ -1,17 +1,17 @@
@title Configuring Outbound Email
@group config
Instructions for configuring Phabricator to send email and other types of
Instructions for configuring Phorge to send email and other types of
messages, like text messages.
Overview
========
Phabricator sends outbound messages through "mailers". Most mailers send
Phorge sends outbound messages through "mailers". Most mailers send
email and most messages are email messages, but mailers may also send other
types of messages (like text messages).
Phabricator can send outbound messages through multiple different mailers,
Phorge can send outbound messages through multiple different mailers,
including a local mailer or various third-party services. Options include:
| Send Mail With | Setup | Cost | Inbound | Media | Notes |
@ -41,7 +41,7 @@ options.
If you have some internal mail or messaging service you'd like to use you can
also write a custom mailer, but this requires digging into the code.
Phabricator sends mail in the background, so the daemons need to be running for
Phorge sends mail in the background, so the daemons need to be running for
it to be able to deliver mail. You should receive setup warnings if they are
not. For more information on using daemons, see
@{article:Managing Daemons with phd}.
@ -50,10 +50,10 @@ not. For more information on using daemons, see
Outbound "From" and "To" Addresses
==================================
When Phabricator sends outbound mail, it must select some "From" address to
When Phorge sends outbound mail, it must select some "From" address to
send mail from, since mailers require this.
When mail only has "CC" recipients, Phabricator generates a dummy "To" address,
When mail only has "CC" recipients, Phorge generates a dummy "To" address,
since some mailers require this and some users write mail rules that depend
on whether they appear in the "To" or "CC" line.
@ -65,12 +65,12 @@ contrast, if the address is a real user address, that user will receive a lot
of mail they probably don't want.
If you plan to configure //inbound// mail later, you usually don't need to do
anything. Phabricator will automatically create a `noreply@` mailbox which
anything. Phorge will automatically create a `noreply@` mailbox which
works the right way (accepts and discards all mail it receives) and
automatically use it when generating addresses.
If you don't plan to configure inbound mail, you may need to configure an
address for Phabricator to use. You can do this by setting
address for Phorge to use. You can do this by setting
`metamta.default-address`.
@ -131,7 +131,7 @@ It also supports these local mailers:
- `smtp`: Connect directly to an SMTP server.
- `test`: Internal mailer for testing. Does not send mail.
You can also write your own mailer by extending `PhabricatorMailAdapter`.
You can also write your own mailer by extending `PhorgeMailAdapter`.
The `media` field supports these values:
@ -169,7 +169,7 @@ tricky because of shell escaping. The easiest way to do it is to use the
Then set the value like this:
```
phabricator/ $ ./bin/config set --stdin cluster.mailers < mailers.json
phorge/ $ ./bin/config set --stdin cluster.mailers < mailers.json
```
For alternatives and more information on configuration, see
@ -310,7 +310,7 @@ SendGrid is a third-party email delivery service. You can learn more at
<https://sendgrid.com/>.
You can configure SendGrid in two ways: you can send via SMTP or via the REST
API. To use SMTP, configure Phabricator to use an `smtp` mailer.
API. To use SMTP, configure Phorge to use an `smtp` mailer.
To use the REST API mailer, set `type` to `sendgrid`, then configure
these `options`:
@ -343,7 +343,7 @@ do any of this, strongly consider using Postmark or Mailgun instead.
To use this mailer, set `type` to `sendmail`, then configure these `options`:
- `message-id`: Optional bool. Set to `false` if Phabricator will not be
- `message-id`: Optional bool. Set to `false` if Phorge will not be
able to select a custom "Message-ID" header when sending mail via this
mailer. See "Message-ID Headers" below.
@ -365,7 +365,7 @@ To use this mailer, set `type` to `smtp`, then configure these `options`:
- `password`: Optional string. Password for authentication.
- `protocol`: Optional string. Set to `tls` or `ssl` if necessary. Use
`ssl` for Gmail.
- `message-id`: Optional bool. Set to `false` if Phabricator will not be
- `message-id`: Optional bool. Set to `false` if Phorge will not be
able to select a custom "Message-ID" header when sending mail via this
mailer. See "Message-ID Headers" below.
@ -390,9 +390,9 @@ Testing and Debugging Outbound Email
You can use the `bin/mail` utility to test, debug, and examine outbound mail. In
particular:
phabricator/ $ ./bin/mail list-outbound # List outbound mail.
phabricator/ $ ./bin/mail show-outbound # Show details about messages.
phabricator/ $ ./bin/mail send-test # Send test messages.
phorge/ $ ./bin/mail list-outbound # List outbound mail.
phorge/ $ ./bin/mail show-outbound # Show details about messages.
phorge/ $ ./bin/mail send-test # Send test messages.
Run `bin/mail help <command>` for more help on using these commands.
@ -406,12 +406,12 @@ You can monitor daemons using the Daemon Console (`/daemon/`, or click
Priorities
==========
By default, Phabricator will try each mailer in order: it will try the first
By default, Phorge will try each mailer in order: it will try the first
mailer first. If that fails (for example, because the service is not available
at the moment) it will try the second mailer, and so on.
If you want to load balance between multiple mailers instead of using one as
a primary, you can set `priority`. Phabricator will start with mailers in the
a primary, you can set `priority`. Phorge will start with mailers in the
highest priority group and go through them randomly, then fall back to the
next group.
@ -441,14 +441,14 @@ like this:
}
```
Phabricator will start with servers in the highest priority group (the group
Phorge will start with servers in the highest priority group (the group
with the **largest** `priority` number). In this example, the highest group is
`300`, which has the two SMTP servers. They'll be tried in random order first.
If both fail, Phabricator will move on to the next priority group. In this
If both fail, Phorge will move on to the next priority group. In this
example, there are no other priority groups.
If it still hasn't sent the mail, Phabricator will try servers which are not
If it still hasn't sent the mail, Phorge will try servers which are not
in any priority group, in the configured order. In this example there is
only one such server, so it will try to send via Mailgun.
@ -457,14 +457,14 @@ Message-ID Headers
==================
Email has a "Message-ID" header which is important for threading messages
correctly in mail clients. Normally, Phabricator is free to select its own
correctly in mail clients. Normally, Phorge is free to select its own
"Message-ID" header values for mail it sends.
However, some mailers (including Amazon SES) do not allow selection of custom
"Message-ID" values and will ignore or replace the "Message-ID" in mail that
is submitted through them.
When Phabricator adds other mail headers which affect threading, like
When Phorge adds other mail headers which affect threading, like
"In-Reply-To", it needs to know if its "Message-ID" headers will be respected
or not to select header values which will produce good threading behavior. If
we guess wrong and think we can set a "Message-ID" header when we can't, you
@ -493,11 +493,11 @@ we can set a "Message-ID" header.
If the outbound pathway does not actually allow selection of a "Message-ID"
header, you can set the `message-id` option on the mailer to `false` to tell
Phabricator that it should not assume it can select a value for this header.
Phorge that it should not assume it can select a value for this header.
For example, if you are sending mail via a local Postfix server which then
forwards the mail to Amazon SES (a service which does not allow selection of
a "Message-ID" header), your `smtp` configuration in Phabricator should
a "Message-ID" header), your `smtp` configuration in Phorge should
specify `"message-id": false`.

22
src/docs/user/configuration/configuring_preamble.diviner
View file

@ -6,14 +6,14 @@ Adjust environmental settings (SSL, remote IPs) using a preamble script.
Overview
========
If Phabricator is deployed in an environment where HTTP headers behave oddly
If Phorge is deployed in an environment where HTTP headers behave oddly
(usually, because it is behind a load balancer), it may not be able to detect
some environmental features (like the client's IP, or the presence of SSL)
correctly.
You can use a special preamble script to make arbitrary adjustments to the
environment and some parts of Phabricator's configuration in order to fix these
problems and set up the environment which Phabricator expects.
environment and some parts of Phorge's configuration in order to fix these
problems and set up the environment which Phorge expects.
Creating a Preamble Script
@ -21,15 +21,15 @@ Creating a Preamble Script
To create a preamble script, write a file to:
phabricator/support/preamble.php
phorge/support/preamble.php
(This file is in Phabricator's `.gitignore`, so you do not need to worry about
(This file is in Phorge's `.gitignore`, so you do not need to worry about
colliding with `git` or interacting with updates.)
This file should be a valid PHP script. If you aren't very familiar with PHP,
you can check for syntax errors with `php -l`:
phabricator/ $ php -l support/preamble.php
phorge/ $ php -l support/preamble.php
No syntax errors detected in support/preamble.php
If present, this script will be executed at the very beginning of each web
@ -40,14 +40,14 @@ examples, see the next sections.
Adjusting Client IPs
====================
If your install is behind a load balancer, Phabricator may incorrectly detect
If your install is behind a load balancer, Phorge may incorrectly detect
all requests as originating from the load balancer, rather than from the
correct client IPs.
In common cases where networks are configured like this, the `X-Forwarded-For`
header will have trustworthy information about the real client IP. You
can use the function `preamble_trust_x_forwarded_for_header()` in your
preamble to tell Phabricator that you expect to receive requests from a
preamble to tell Phorge that you expect to receive requests from a
load balancer or proxy which modifies this header:
```name="Trust X-Forwarded-For Header", lang=php
@ -89,9 +89,9 @@ if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) {
Adjusting SSL
=============
If your install is behind an SSL terminating load balancer, Phabricator may
If your install is behind an SSL terminating load balancer, Phorge may
detect requests as HTTP when the client sees them as HTTPS. This can cause
Phabricator to generate links with the wrong protocol, issue cookies without
Phorge to generate links with the wrong protocol, issue cookies without
the SSL-only flag, or reject requests outright.
To fix this, you can set `$_SERVER['HTTPS']` explicitly:
@ -103,7 +103,7 @@ name=Explicitly Configure SSL Availability
$_SERVER['HTTPS'] = true;
```
You can also set this value to `false` to explicitly tell Phabricator that a
You can also set this value to `false` to explicitly tell Phorge that a
request is not an SSL request.

14
src/docs/user/configuration/custom_fields.diviner
View file

@ -5,7 +5,7 @@ How to add custom fields to applications which support them.
= Overview =
Several Phabricator applications allow the configuration of custom fields. These
Several Phorge applications allow the configuration of custom fields. These
fields allow you to add more information to objects, and in some cases reorder
or remove builtin fields.
@ -134,7 +134,7 @@ The `strings` value supports different strings per control type. They are:
- **search.default** Text for the search interface, defaults to "(Any)".
- **search.require** Text for the search interface, defaults to "Require".
Internally, Phabricator implements some additional custom field types and
Internally, Phorge implements some additional custom field types and
options. These are not intended for general use and are subject to abrupt
change, but are documented here for completeness:
@ -149,7 +149,7 @@ change, but are documented here for completeness:
If you want custom fields to have advanced behaviors (sophisticated rendering,
advanced validation, complicated controls, interaction with other systems, etc),
you can write a custom field as an extension and add it to Phabricator.
you can write a custom field as an extension and add it to Phorge.
NOTE: This API is somewhat new and fairly large. You should expect that there
will be occasional changes to the API requiring minor updates in your code.
@ -167,9 +167,9 @@ want to add a field to:
| Projects | @{class:PhabricatorProjectCustomField} |
The easiest way to get started is to drop your subclass into
`phabricator/src/extensions/`. If Phabricator is configured in development
`phorge/src/extensions/`. If Phorge is configured in development
mode, the class should immediately be available in the UI. If not, you can
restart Phabricator (for help, see @{article:Restarting Phabricator}).
restart Phorge (for help, see @{article:Restarting Phorge}).
For example, this is a simple template which adds a custom field to Maniphest:
@ -211,6 +211,6 @@ integrations, see the base class for your application and
Continue by:
- learning more about extending Phabricator with custom code in
@{article@phabcontrib:Adding New Classes};
- learning more about extending Phorge with custom code in
@{article@contrib:Adding New Classes};
- or returning to the @{article: Configuration Guide}.

16
src/docs/user/configuration/managing_caches.diviner
View file

@ -1,17 +1,17 @@
@title Managing Caches
@group config
Discusses Phabricator caches and cache management.
Discusses Phorge caches and cache management.
Overview
========
Phabricator uses various caches to improve performance, similar to the caches
Phorge uses various caches to improve performance, similar to the caches
a web browser uses to improve web performance.
In particular, blocks of text which are expensive to render (like formatted
text and syntax highlighted code) are often cached after they're rendered for
the first time. When they're rendered again, Phabricator can read the cache
the first time. When they're rendered again, Phorge can read the cache
instead of recomputing the result.
Because text is cached, you may continue to see the old result even after you
@ -28,20 +28,20 @@ you can just ignore the out of date caches and they'll fix themselves
eventually (usually within 30 days).
If you don't want to wait, you can purge the caches. This will remove any
cached data and force Phabricator to recompute the results.
cached data and force Phorge to recompute the results.
Purging Caches
==============
If you need to purge Phabricator's caches, you can use the CLI tool. Run it
If you need to purge Phorge's caches, you can use the CLI tool. Run it
with the `--help` flag to see options:
phabricator/ $ ./bin/cache purge --help
phorge/ $ ./bin/cache purge --help
This tool can purge caches in a granular way, but it's normally easiest to
just purge all of the caches:
phabricator/ $ ./bin/cache purge --all
phorge/ $ ./bin/cache purge --all
You can purge caches safely. The data they contain can always be rebuilt from
other data if Phabricator needs it.
other data if Phorge needs it.

24
src/docs/user/configuration/managing_daemons.diviner
View file

@ -1,11 +1,11 @@
@title Managing Daemons with phd
@group config
Explains Phabricator daemons and the daemon control program `phd`.
Explains Phorge daemons and the daemon control program `phd`.
= Overview =
Phabricator uses daemons (background processing scripts) to handle a number of
Phorge uses daemons (background processing scripts) to handle a number of
tasks:
- tracking repositories, discovering new commits, and importing and parsing
@ -16,19 +16,19 @@ tasks:
Daemons are started and stopped with **phd** (the **Ph**abricator **D**aemon
launcher). Daemons can be monitored via a web console.
You do not need to run daemons for most parts of Phabricator to work, but some
You do not need to run daemons for most parts of Phorge to work, but some
features (principally, repository tracking with Diffusion) require them and
several features will benefit in performance or stability if you configure
daemons.
= phd =
**phd** is a command-line script (located at `phabricator/bin/phd`). To get
**phd** is a command-line script (located at `phorge/bin/phd`). To get
a list of commands, run `phd help`:
phabricator/ $ ./bin/phd help
phorge/ $ ./bin/phd help
NAME
phd - phabricator daemon launcher
phd - phorge daemon launcher
...
Generally, you will use:
@ -43,7 +43,7 @@ If you want finer-grained control, you can use:
- **phd launch** to launch individual daemons; and
- **phd debug** to debug problems with daemons.
NOTE: When you upgrade Phabricator or change configuration, you should restart
NOTE: When you upgrade Phorge or change configuration, you should restart
the daemons by running `phd restart`.
= Daemon Console =
@ -81,12 +81,12 @@ launch custom daemons, or launch special daemons like the IRC bot.
To debug a daemon, use `phd debug`:
phabricator/bin/ $ ./phd debug <daemon>
phorge/bin/ $ ./phd debug <daemon>
You can pass arguments like this (normal arguments are passed to the daemon
control mechanism, not to the daemon itself):
phabricator/bin/ $ ./phd debug <daemon> -- --flavor apple
phorge/bin/ $ ./phd debug <daemon> -- --flavor apple
In debug mode, daemons do not daemonize, and they print additional debugging
output to the console. This should make it easier to debug problems. You can
@ -94,7 +94,7 @@ terminate the daemon with `^C`.
To launch a nonstandard daemon, use `phd launch`:
phabricator/bin/ $ ./phd launch <daemon>
phorge/bin/ $ ./phd launch <daemon>
This daemon will daemonize and run normally.
@ -109,7 +109,7 @@ This daemon will daemonize and run normally.
just those started with `phd start`. If you're writing a restart script,
have it launch any custom daemons explicitly after `phd restart`.
- You can write your own daemons and manage them with `phd` by extending
@{class:PhabricatorDaemon}. See @{article@phabcontrib:Adding New Classes}.
@{class:PhabricatorDaemon}. See @{article@contrib:Adding New Classes}.
- See @{article:Diffusion User Guide} for details about tuning the repository
daemon.
@ -128,4 +128,4 @@ Continue by:
- learning about the repository daemon with @{article:Diffusion User Guide};
or
- writing your own daemons with @{article@phabcontrib:Adding New Classes}.
- writing your own daemons with @{article@contrib:Adding New Classes}.

6
src/docs/user/configuration/managing_garbage.diviner
View file

@ -6,7 +6,7 @@ Understanding and configuring garbage collection.
Overview
========
Phabricator generates various logs and caches during normal operation. Some of
Phorge generates various logs and caches during normal operation. Some of
these logs and caches are usually of very little use after some time has
passed, so they are deleted automatically (often after a month or two) in a
process called "garbage collection".
@ -35,7 +35,7 @@ You can review the current retention policies in
`bin/garbage set-policy` to select a new policy:
```
phabricator/ $ ./bin/garbage set-policy --collector cache.markup --days 7
phorge/ $ ./bin/garbage set-policy --collector cache.markup --days 7
```
You can use `--days` to select how long data is retained for. You can also use
@ -53,7 +53,7 @@ Troubleshooting
You can manually run a collector with `bin/garbage collect`.
```
phabricator/ $ ./bin/garbage collect --collector cache.general
phorge/ $ ./bin/garbage collect --collector cache.general
```
By using the `--trace` flag, you can inspect the operation of the collector

40
src/docs/user/configuration/notifications.diviner
View file

@ -6,11 +6,11 @@ Guide to setting up notifications.
Overview
========
By default, Phabricator delivers information about events (like users creating
By default, Phorge delivers information about events (like users creating
tasks or commenting on code reviews) through email and in-application
notifications.
Phabricator can also be configured to deliver notifications in real time, by
Phorge can also be configured to deliver notifications in real time, by
popping up a message in any open browser windows if something has happened or
an object has been updated.
@ -44,8 +44,8 @@ To install Node.js, follow the instructions on
You will also need to install the `ws` module for Node. This needs to be
installed into the notification server directory:
phabricator/ $ cd support/aphlict/server/
phabricator/support/aphlict/server/ $ npm install ws
phorge/ $ cd support/aphlict/server/
phorge/support/aphlict/server/ $ npm install ws
Once Node.js and the `ws` module are installed, you're ready to start the
server.
@ -57,21 +57,21 @@ Running the Aphlict Server
After installing Node.js, you can control the notification server with the
`bin/aphlict` command. To start the server:
phabricator/ $ bin/aphlict start
phorge/ $ bin/aphlict start
By default, the server must be able to listen on port `22280`. If you're using
a host firewall (like a security group in EC2), make sure traffic can reach the
server.
The server configuration is controlled by a configuration file, which is
separate from Phabricator's configuration settings. The default file can
be found at `phabricator/conf/aphlict/aphlict.default.json`.
separate from Phorge's configuration settings. The default file can
be found at `phorge/conf/aphlict/aphlict.default.json`.
To make adjustments to the default configuration, either copy this file to
create `aphlict.custom.json` in the same directory (this file will be used if
it exists) or specify a configuration file explicitly with the `--config` flag:
phabricator/ $ bin/aphlict start --config path/to/config.json
phorge/ $ bin/aphlict start --config path/to/config.json
The configuration file has these settings:
@ -118,12 +118,12 @@ installs. For more information on how to configure a cluster, see
The defaults are appropriate for simple cases, but you may need to adjust them
if you are running a more complex configuration.
Configuring Phabricator
Configuring Phorge
=======================
After starting the server, configure Phabricator to connect to it by adjusting
After starting the server, configure Phorge to connect to it by adjusting
`notification.servers`. This configuration option should have a list of servers
that Phabricator should interact with.
that Phorge should interact with.
Normally, you'll list one client server and one admin server, like this:
@ -131,7 +131,7 @@ Normally, you'll list one client server and one admin server, like this:
[
{
"type": "client",
"host": "phabricator.mycompany.com",
"host": "phorge.mycompany.com",
"port": 22280,
"protocol": "https"
},
@ -165,7 +165,7 @@ Troubleshooting
You can run `aphlict` in the foreground to get output to your console:
phabricator/ $ ./bin/aphlict debug
phorge/ $ ./bin/aphlict debug
Because the notification server uses WebSockets, your browser error console
may also have information that is useful in figuring out what's wrong.
@ -178,10 +178,10 @@ information that is useful in resolving issues.
SSL and HTTPS
=============
If you serve Phabricator over HTTPS, you must also serve websockets over HTTPS.
If you serve Phorge over HTTPS, you must also serve websockets over HTTPS.
Browsers will refuse to connect to `ws://` websockets from HTTPS pages.
If a client connects to Phabricator over HTTPS, Phabricator will automatically
If a client connects to Phorge over HTTPS, Phorge will automatically
select an appropriate HTTPS service from `notification.servers` and instruct
the browser to open a websocket connection with `wss://`.
@ -241,10 +241,10 @@ upstream websocket_pool {
}
```
```lang=nginx, name=/etc/nginx/sites-enabled/phabricator.example.com.conf
```lang=nginx, name=/etc/nginx/sites-enabled/phorge.example.com.conf
server {
server_name phabricator.example.com;
root /path/to/phabricator/webroot;
server_name phorge.example.com;
root /path/to/phorge/webroot;
// ...
@ -260,10 +260,10 @@ server {
With this approach, you should make these additional adjustments:
**Phabricator Configuration**: The entry in `notification.servers` with type
**Phorge Configuration**: The entry in `notification.servers` with type
`"client"` should have these adjustments made:
- Set `host` to the Phabricator host.
- Set `host` to the Phorge host.
- Set `port` to the standard HTTPS port (usually `443`).
- Set `protocol` to `"https"`.
- Set `path` to `/ws/`, so it matches the special `location` in your

30
src/docs/user/configuration/storage_adjust.diviner
View file

@ -6,13 +6,13 @@ Explains how to apply storage adjustments to the MySQL schemata.
Overview
========
Phabricator uses a workflow called //storage adjustment// to make some minor
Phorge uses a workflow called //storage adjustment// to make some minor
kinds of changes to the MySQL schema. This workflow compliments the //storage
upgrade// workflow, which makes major changes.
You can perform storage adjustment by running:
phabricator/ $ ./bin/storage adjust
phorge/ $ ./bin/storage adjust
This document describes what adjustments are, how they relate to storage
upgrades, how to perform them, and how to troubleshoot issues with storage
@ -22,7 +22,7 @@ adjustment.
Understanding Adjustments
===================
Storage adjustments make minor changes to the Phabricator MySQL schemata to
Storage adjustments make minor changes to the Phorge MySQL schemata to
improve consistency, unicode handling, and performance. Changes covered by
adjustment include:
@ -62,7 +62,7 @@ adjustment workflow can resolve.
You can also review adjustments from the CLI, by running:
phabricator/ $ ./bin/storage adjust
phorge/ $ ./bin/storage adjust
Before you're prompted to actually apply adjustments, you'll be given a list of
available adjustments. You can then make a choice to apply them.
@ -73,11 +73,11 @@ Performing Adjustments
To perform adjustments, run the `adjust` workflow:
phabricator/ $ ./bin/storage adjust
phorge/ $ ./bin/storage adjust
For details about flags, use:
phabricator/ $ ./bin/storage help adjust
phorge/ $ ./bin/storage help adjust
You do not normally need to run this workflow manually: it will be run
automatically after you run the `upgrade` workflow.
@ -97,7 +97,7 @@ set can safely store 4-byte unicode characters.
The adjustment workflow allows us to alter the schema to primarily use
`binary` character sets on older MySQL, and primarily use `utf8mb4` character
sets on newer MySQL. The net effect is that Phabricator works consistently and
sets on newer MySQL. The net effect is that Phorge works consistently and
can store 4-byte unicode characters regardless of the MySQL version. Under
newer MySQL, we can also take advantage of the better collation rules the
`utf8mb4` character set offers.
@ -143,7 +143,7 @@ upstream.
In general, adjustments are not critical. If you run into issues applying
adjustments, it is safe to file a task in the upstream describing the problem
you've encountered and continue using Phabricator normally until the issue can
you've encountered and continue using Phorge normally until the issue can
be resolved.
Surplus Schemata
@ -154,13 +154,13 @@ After performing adjustment, you may receive an error that a table or column is
| Target | Error |
| --- | --- |
| phabricator_example.example_table | Surplus |
| phorge_example.example_table | Surplus |
Generally, "Surplus" means that Phabricator does not expect the table or column
Generally, "Surplus" means that Phorge does not expect the table or column
to exist. These surpluses usually exist because you (or someone else
with database access) added the table or column manually. Rarely, they can
also exist for other reasons. They are usually safe to delete, but because
deleting them destroys data and Phabricator can not be sure that the table or
deleting them destroys data and Phorge can not be sure that the table or
column doesn't have anything important in it, it does not delete them
automatically.
@ -174,18 +174,18 @@ message):
```lang=sql
CREATE DATABASE my_backups;
RENAME TABLE phabricator_example.example_table
RENAME TABLE phorge_example.example_table
TO my_backups.example_table;
```
Phabricator will ignore tables that aren't in databases it owns, so you can
safely move anything you aren't sure about outside of the Phabricator databases.
Phorge will ignore tables that aren't in databases it owns, so you can
safely move anything you aren't sure about outside of the Phorge databases.
If you're sure you don't need a table, use `DROP TABLE` to destroy it,
specifying the correct table name (the one given in the error message):
```lang=sql
DROP TABLE phabricator_example.example_table;
DROP TABLE phorge_example.example_table;
```
This will destroy the table permanently.

8
src/docs/user/configuration/troubleshooting_https.diviner
View file

@ -5,7 +5,7 @@ Detailed instructions for troubleshooting HTTPS connection problems.
= Overview =
If you're having trouble connecting to an HTTPS install of Phabricator, and
If you're having trouble connecting to an HTTPS install of Phorge, and
particularly if you're receiving a "There was an error negotiating the SSL
connection." error, this document may be able to help you diagnose and resolve
the problem.
@ -17,7 +17,7 @@ Connection negotiation can fail for several reasons. The major ones are:
certificates).
- The SSL certificate is signed for the wrong domain. For example, a
certificate signed for `www.example.com` will not work for
`phabricator.example.com`.
`phorge.example.com`.
- The server rejects TLSv1 SNI connections for the domain (this is
complicated, see below).
@ -50,7 +50,7 @@ with:
$ openssl x509 -text -in <certificate>
If the certificate was accidentally generated for, e.g. `www.example.com` but
you installed Phabricator on `phabricator.example.com`, you need to generate a
you installed Phorge on `phorge.example.com`, you need to generate a
new certificate for the right domain.
= SNI Problems =
@ -73,7 +73,7 @@ an error in `SSL23_GET_SERVER_HELLO` with `reason(1112)`, like this:
/SourceCache/OpenSSL098/OpenSSL098-44/src/ssl/s23_clnt.c:602:
...it indicates server is misconfigured. The most common cause of this problem
is an Apache server that does not explicitly name the Phabricator domain as a
is an Apache server that does not explicitly name the Phorge domain as a
valid VirtualHost.
This error occurs only for some versions of the OpenSSL client library

7
src/docs/user/feedback.diviner
View file

@ -1,7 +0,0 @@
@title Give Feedback! Get Support!
@short Feedback/Support
@group cellar
Deprecated.
This article has moved to @{article:Support Resources}.

2
src/docs/user/field/conduit_changes.diviner
View file

@ -25,7 +25,7 @@ Methods have one of three statuses:
them before they stabilize.
- **Stable**: This is an established method which generally will not change.
- **Deprecated**: This method will be removed in a future version of
Phabricator and callers should cease using it.
Phorge and callers should cease using it.
Normally, a method is deprecated only when it is obsolete or a new, more
powerful method is available to replace it.

4
src/docs/user/field/darkconsole.diviner
View file

@ -6,9 +6,9 @@ Enabling and using the built-in debugging and performance console.
Overview
========
DarkConsole is a debugging console built into Phabricator which exposes
DarkConsole is a debugging console built into Phorge which exposes
configuration, performance and error information. It can help you detect,
understand and resolve bugs and performance problems in Phabricator
understand and resolve bugs and performance problems in Phorge
applications.

21
src/docs/user/field/exit_codes.diviner
View file

@ -1,7 +1,7 @@
@title Command Line Exit Codes
@group fieldmanual
Explains the use of exit codes in Phabricator command line scripts.
Explains the use of exit codes in Phorge command line scripts.
Overview
========
@ -21,7 +21,7 @@ like `cmdx && cmdy` operate on exit codes.
The code `0` means success. Other codes signal some sort of error or status
condition, depending on the system and command.
With rare exception, Phabricator uses //all other codes// to signal
With rare exception, Phorge uses //all other codes// to signal
**catastrophic failure**.
This is an explicit architectural decision and one we are unlikely to deviate
@ -35,10 +35,10 @@ they are not appropriate for communicating application state in a modern
operational environment. This document explains the reasoning behind our use of
exit codes in more detail.
In particular, this approach is informed by a focus on operating Phabricator
In particular, this approach is informed by a focus on operating Phorge
clusters at scale. This is not a common deployment scenario, but we consider it
the most important one. Our use of exit codes makes it easier to deploy and
operate a Phabricator cluster at larger scales. It makes it slightly harder to
operate a Phorge cluster at larger scales. It makes it slightly harder to
deploy and operate a small cluster or single host by gluing together `bash`
scripts. We are willingly trading the small scale away for advantages at larger
scales.
@ -56,11 +56,10 @@ operations environment faces different forces than the interactive shell did
in the 1970s, particularly at scale.
We consider correctness to be very important to modern operations environments.
In particular, we manage a Phabricator cluster (Phacility) and believe that
having reliable, repeatable processes for provisioning, configuration and
deployment is critical to maintaining and scaling our operations. Our use of
exit codes makes it easier to implement processes that are correct and reliable
on top of Phabricator management scripts.
In particular, we believe that having reliable, repeatable processes for
provisioning, configuration and deployment is critical to maintaining and
scaling our operations. Our use of exit codes makes it easier to implement
processes that are correct and reliable on top of Phorge management scripts.
Exit codes as signals for application state are problematic because they are
ambiguous: you can't use them to distinguish between dissimilar failure states
@ -228,13 +227,13 @@ particular, ease of use in a `bash` environment is not a compelling motivation.
We are broadly willing to make output machine parseable or provide an explicit
machine output mode (often a `--json` flag) if there is a reasonable use case
for it. However, we operate a large production cluster of Phabricator instances
for it. However, we operate a large production cluster of Phorge instances
with the tools available in the upstream, so the lack of machine parseable
output is not sufficient to motivate adding such output on its own: we also
need to understand the problem you're facing, and why it isn't a problem we
face. A simpler or cleaner approach to the problem may already exist.
If you just want to write `bash` scripts on top of Phabricator scripts and you
If you just want to write `bash` scripts on top of Phorge scripts and you
are unswayed by these concerns, you can often just build a composite command to
get roughly the same effect that you'd get out of an exit code.

8
src/docs/user/field/performance.diviner
View file

@ -23,18 +23,18 @@ Performance and the Upstream
============================
Performance issues and hangs will often require upstream involvement to fully
resolve. The intent is for Phabricator to perform well in all reasonable cases,
resolve. The intent is for Phorge to perform well in all reasonable cases,
not require tuning for different workloads (as long as those workloads are
generally reasonable). Poor performance with a reasonable workload is likely a
bug, not a configuration problem.
However, some pages are slow because Phabricator legitimately needs to do a lot
However, some pages are slow because Phorge legitimately needs to do a lot
of work to generate them. For example, if you write a 100MB wiki document,
Phabricator will need substantial time to process it, it will take a long time
Phorge will need substantial time to process it, it will take a long time
to download over the network, and your browser will probably not be able to
render it especially quickly.
We may be able to improve performance in some cases, but Phabricator is not
We may be able to improve performance in some cases, but Phorge is not
magic and can not wish away real complexity. The best solution to these problems
is usually to find another way to solve your problem: for example, maybe the
100MB document can be split into several smaller documents.

14
src/docs/user/field/permanently_destroying_data.diviner
View file

@ -6,7 +6,7 @@ How to permanently destroy data and manage leaked secrets.
Overview
========
Phabricator intentionally makes it difficult to permanently destroy data, but
Phorge intentionally makes it difficult to permanently destroy data, but
provides a command-line tool for destroying objects if you're certain that
you want to destroy something.
@ -24,7 +24,7 @@ Destroying Data
To permanently destroy an object, run this command from the command line:
```
phabricator/ $ ./bin/remove destroy <object>
phorge/ $ ./bin/remove destroy <object>
```
The `<object>` may be an object monogram or PHID. For instance, you can use
@ -36,7 +36,7 @@ The `<object>` may be an object monogram or PHID. For instance, you can use
CLI Access Required
===================
In almost all cases, Phabricator requires operational access from the CLI to
In almost all cases, Phorge requires operational access from the CLI to
permanently destroy data. One major reason for this requirement is that it
limits the reach of an attacker who compromises a privileged account.
@ -56,9 +56,9 @@ Sometimes you may want to destroy an object because it has leaked a secret,
like an API key or another credential. For example, an engineer might
accidentally send a change for review which includes a sensitive private key.
No Phabricator command can rewind time, and once data is written to Phabricator
No Phorge command can rewind time, and once data is written to Phorge
the cat is often out of the bag: it has often been transmitted to external
systems which Phabricator can not interact with via email, webhooks, API calls,
systems which Phorge can not interact with via email, webhooks, API calls,
repository mirroring, CDN caching, and so on. You can try to clean up the mess,
but you're generally already too late.
@ -66,7 +66,7 @@ The `bin/remove destroy` command will make a reasonable attempt to completely
destroy objects, but this is just an attempt. It can not unsend email or uncall
the API, and no command can rewind time and undo a leak.
**Revoking Credentials**: If Phabricator credentials were accidentally
**Revoking Credentials**: If Phorge credentials were accidentally
disclosed, you can revoke them so they no longer function. See
@{article:Revoking Credentials} for more information.
@ -75,7 +75,7 @@ Preventing Leaks
================
Because time can not be rewound, it is best to prevent sensitive data from
leaking in the first place. Phabricator supports some technical measures that
leaking in the first place. Phorge supports some technical measures that
can make it more difficult to accidentally disclose secrets:
**Differential Diff Herald Rules**: You can write "Differential Diff" rules

14
src/docs/user/field/repository_hints.diviner
View file

@ -6,7 +6,7 @@ Dealing with rewrites of published repositories and other unusual problems.
Overview
========
Some repositories have unusual commits. You can provide "hints" to Phabricator
Some repositories have unusual commits. You can provide "hints" to Phorge
about these commits to improve behavior.
Supported hints are:
@ -17,7 +17,7 @@ Supported hints are:
new pages.
- **Unreadable Commits**: If some commits are not readable (which is rare,
but can happen in some cases if they are generated with an external tool)
you can provide hints so that Phabricator doesn't try to read them.
you can provide hints so that Phorge doesn't try to read them.
The remainder of this document explains how to create and remove hints, and how
to specify each type of hint.
@ -28,7 +28,7 @@ Creating Hints
To create hints, pipe a JSON list of hints to `bin/repository hint`:
```
phabricator/ $ cat hints.json | ./bin/repository hint
phorge/ $ cat hints.json | ./bin/repository hint
```
The hints should be a list of objects like this:
@ -76,7 +76,7 @@ For example, use a hint specification like this:
]
```
Phabricator won't treat commits without any hint specially.
Phorge won't treat commits without any hint specially.
Hint: Rewritten Commits
@ -104,13 +104,13 @@ For example, a hint might look like this:
]
```
Phabricator will show users that the commit was rewritten in the web UI.
Phorge will show users that the commit was rewritten in the web UI.
Hint: Unreadable Commits
========================
The `"unreadable"` hint allows you to tell Phabricator that it should not
The `"unreadable"` hint allows you to tell Phorge that it should not
bother trying to read the changes associated with a particular commit. In
some rare cases, repositories can contain commits which aren't readable
(for example, if they were created by external tools during an import or
@ -130,5 +130,5 @@ For example, a hint might look like this:
]
```
Phabricator won't try to read, parse, import, or display the changes associated
Phorge won't try to read, parse, import, or display the changes associated
with this commit.

26
src/docs/user/field/repository_imports.diviner
View file

@ -7,7 +7,7 @@ Overview
========
When you first import an external source code repository (or push new commits to
a hosted repository), Phabricator imports those commits in the background.
a hosted repository), Phorge imports those commits in the background.
While a repository is initially importing, some features won't work. While
individual commits are importing, some of their metadata won't be available in
@ -20,7 +20,7 @@ help you understand the import process and troubleshoot problems with it.
Understanding the Import Pipeline
=================================
Phabricator first performs commit discovery on repositories. This examines
Phorge first performs commit discovery on repositories. This examines
a repository and identifies all the commits in it at a very shallow level,
then creates stub objects for them. These stub objects primarily serve to
assign various internal IDs to each commit.
@ -54,7 +54,7 @@ the import process is stuck.
First, to identify which commits have missing import steps, run this command:
```
phabricator/ $ ./bin/repository importing rXYZ
phorge/ $ ./bin/repository importing rXYZ
```
That will show what work remains to be done. Each line shows a commit which
@ -69,7 +69,7 @@ sections are "Queued Tasks" (work waiting in queue) and "Leased Tasks"
Third, run this command to look at the daemon logs:
```
phabricator/ $ ./bin/phd log
phorge/ $ ./bin/phd log
```
This can show you any errors the daemons have encountered recently.
@ -104,14 +104,14 @@ importing` and use this command to re-run any missing steps manually in the
foreground:
```
phabricator/ $ ./bin/repository reparse --importing --trace rXYZabcdef012...
phorge/ $ ./bin/repository reparse --importing --trace rXYZabcdef012...
```
This command is always safe to run, no matter what the actual root cause of
the problem is.
If this fails with an error, you've likely identified a problem with
Phabricator. Collect as much information as you can about what makes the commit
Phorge. Collect as much information as you can about what makes the commit
special and file a bug in the upstream by following the instructions in
@{article:Contributing Bug Reports}.
@ -132,7 +132,7 @@ wait that long.
In the Daemon console, temporarily failures usually look like tasks in the
"Leased Tasks" column with a large "Expires" value but a low "Failures" count
(usually 0 or 1). The "Expires" column is showing how long Phabricator is
(usually 0 or 1). The "Expires" column is showing how long Phorge is
waiting to retry these tasks.
In the daemon log, these temporary failures might have created log entries, but
@ -150,7 +150,7 @@ daemons, all task leases are immediately expired, so any tasks waiting for a
long time will run right away:
```
phabricator/ $ ./bin/phd restart
phorge/ $ ./bin/phd restart
```
This command is always safe to run, no matter what the actual root cause of
@ -172,7 +172,7 @@ been too ambitious with running manual SQL commands and deleted a bunch of
extra things they shouldn't have.
There is no normal set of conditions under which this should occur, but you can
force Phabricator to re-queue the tasks to recover from it if it does occur.
force Phorge to re-queue the tasks to recover from it if it does occur.
This will look like missing steps in `repository importing`, but nothing in the
"Queued Tasks" or "Leased Tasks" sections of the daemon console. The daemon
@ -182,12 +182,12 @@ To re-queue parse tasks for a repository, run this command, which will queue
up all of the missing work in `repository importing`:
```
phabricator/ $ ./bin/repository reparse --importing --all rXYZ
phorge/ $ ./bin/repository reparse --importing --all rXYZ
```
This command may cause duplicate work to occur if you have misdiagnosed the
problem and the tasks aren't actually lost. For example, it could queue a
second task to perform publishing, which could cause Phabricator to send a
second task to perform publishing, which could cause Phorge to send a
second copy of email about the commit. Other than that, it is safe to run even
if this isn't the problem.
@ -215,7 +215,7 @@ To mark a repository as imported even though it really isn't, run this
command:
```
phabricator/ $ ./bin/repository mark-imported rXYZ
phorge/ $ ./bin/repository mark-imported rXYZ
```
If you do this by mistake, you can reverse it later by using the
@ -231,7 +231,7 @@ to any command to get more details about what it is doing. For any command,
you can use `help` to learn more about what it does and which flag it takes:
```
phabricator/ $ bin/repository help <command>
phorge/ $ bin/repository help <command>
```
In particular, you can use flags with the `repository reparse` command to

6
src/docs/user/field/restarting.diviner
View file

@ -1,14 +1,14 @@
@title Restarting Phabricator
@title Restarting Phorge
@group fieldmanual
Instructions on how to restart HTTP and PHP servers to reload configuration
changes in Phabricator.
changes in Phorge.
Overview
========
Phabricator's setup and configuration instructions sometimes require you to
Phorge's setup and configuration instructions sometimes require you to
restart your server processes, particularly after making configuration changes.
This document explains how to restart them properly.

16
src/docs/user/field/revoking_credentials.diviner
View file

@ -21,7 +21,7 @@ specified targets. For example, if you believe `@alice` may have had her SSH
key compromised, you can revoke her keys like this:
```
phabricator/ $ ./bin/auth revoke --type ssh --from @alice
phorge/ $ ./bin/auth revoke --type ssh --from @alice
```
The flag `--everything` revokes all credential types.
@ -41,13 +41,13 @@ third-party credential types if you have extensions installed.
To list all revokable credential types:
```
phabricator/ $ ./bin/auth revoke --list
phorge/ $ ./bin/auth revoke --list
```
To get details about exactly how a specific revoker works:
```
phabricator/ $ ./bin/auth revoke --list --type ssh
phorge/ $ ./bin/auth revoke --list --type ssh
```
@ -79,10 +79,10 @@ are normally sent over the network.
You can revoke these credentials by running these commands:
```
phabricator/ $ ./bin/auth revoke --type password --everywhere
phabricator/ $ ./bin/auth revoke --type conduit --everywhere
phabricator/ $ ./bin/auth revoke --type session --everywhere
phabricator/ $ ./bin/auth revoke --type temporary --everywhere
phorge/ $ ./bin/auth revoke --type password --everywhere
phorge/ $ ./bin/auth revoke --type conduit --everywhere
phorge/ $ ./bin/auth revoke --type session --everywhere
phorge/ $ ./bin/auth revoke --type temporary --everywhere
```
Depending on the nature of the compromise you may also consider revoking `ssh`
@ -97,5 +97,5 @@ credentials without affecting other users.
You can revoke all credentials for a user by running this command:
```
phabricator/ $ ./bin/auth revoke --everything --from @alice
phorge/ $ ./bin/auth revoke --everything --from @alice
```

12
src/docs/user/field/worker_queue.diviner
View file

@ -6,7 +6,7 @@ Advanced guide to managing the background worker task queue.
Overview
========
Phabricator uses daemonized worker processes to execute some tasks (like
Phorge uses daemonized worker processes to execute some tasks (like
importing repositories and sending mail) in the background.
In most cases, this queue will automatically execute tasks in an appropriate
@ -16,7 +16,7 @@ which tasks execute, when, and at what priority.
Reference: Priority Levels
==========================
Tasks queued by Phabricator use these default priority levels:
Tasks queued by Phorge use these default priority levels:
| Priority | Name | Tasks |
|---|---|---|
@ -33,7 +33,7 @@ with priority 2000).
Any positive integer is a valid priority level, and if you adjust the priority
of tasks with `bin/worker priority` you may select any level even if
Phabricator would never naturally queue tasks at that level. For example, you
Phorge would never naturally queue tasks at that level. For example, you
may adjust tasks to priority `5678`, which will make them execute after all
other types of natural tasks.
@ -48,7 +48,7 @@ The most common case where you may want to make an adjustment to the default
behavior of the worker queue is when importing a very large repository like
the Linux kernel.
Although Phabricator will automatically process imports of new repositories at
Although Phorge will automatically process imports of new repositories at
a lower priority level than all other non-import tasks, you may still run into
issues like these:
@ -63,7 +63,7 @@ import at a lower priority than all other tasks (including other imports of
new repositories), you can run a command like this:
```
phabricator/ $ ./bin/worker priority --priority 5000 --container R123
phorge/ $ ./bin/worker priority --priority 5000 --container R123
```
This means: set all tasks associated with container `R123` (in this example,
@ -75,7 +75,7 @@ schedule tasks to execute at night or over the weekend. For example, to
pause an import for 6 hours, run a command like this:
```
phabricator/ $ ./bin/worker delay --until "6 hours" --container R123
phorge/ $ ./bin/worker delay --until "6 hours" --container R123
```
The selected tasks will not execute until 6 hours from the time this command

4
src/docs/user/field/xhprof.diviner
View file

@ -7,7 +7,7 @@ Overview
========
XHProf is a profiling tool which will let you understand application
performance in Phabricator.
performance in Phorge.
After you install XHProf, you can use it from the web UI and the CLI to
generate detailed performance profiles. It is the most powerful tool available
@ -60,7 +60,7 @@ Using XHProf: CLI
From the command line, use the `--xprofile <filename>` flag to generate a
profile of any script.
You can then upload this file to Phabricator (using `arc upload` may be easiest)
You can then upload this file to Phorge (using `arc upload` may be easiest)
and view it in the web UI.

52
src/docs/user/installation_guide.diviner
View file

@ -1,18 +1,18 @@
@title Installation Guide
@group intro
This document contains basic install instructions to get Phabricator up and
This document contains basic install instructions to get Phorge up and
running.
Overview
========
Phabricator is a LAMP (Linux, Apache, MySQL, PHP) application. To install
Phabricator, you will need:
Phorge is a LAMP (Linux, Apache, MySQL, PHP) application. To install
Phorge, you will need:
- a normal computer to install it on (shared hosts and unusual environments
are not supported) running some flavor of Linux or a similar OS;
- a domain name (like `phabricator.mycompany.com`);
- a domain name (like `phorge.example.com`);
- basic sysadmin skills;
- Apache, nginx, or another webserver;
- PHP, MySQL, and Git.
@ -25,32 +25,32 @@ Installation Requirements
You will need **a computer**. Options include:
- **A Normal Computer**: This is strongly recommended. Many installs use a VM
in EC2. Phabricator installs properly and works well on a normal computer.
in EC2. Phorge installs properly and works well on a normal computer.
- **A Shared Host**: This may work, but is not recommended. Many shared
hosting environments have restrictions which prevent some of Phabricator's
hosting environments have restrictions which prevent some of Phorge's
features from working. Consider using a normal computer instead. We do not
support shared hosts.
- **A SAN Appliance, Network Router, Gaming Console, Raspberry Pi, etc.**:
Although you may be able to install Phabricator on specialized hardware, it
Although you may be able to install Phorge on specialized hardware, it
is unlikely to work well and will be difficult for us to support. Strongly
consider using a normal computer instead. We do not support specialized
hardware.
- **A Toaster, Car, Firearm, Thermostat, etc.**: Yes, many modern devices now
have embedded computing capability. We live in interesting times. However,
you should not install Phabricator on these devices. Instead, install it on
you should not install Phorge on these devices. Instead, install it on
a normal computer. We do not support installing on noncomputing devices.
To install the Phabricator server software, you will need an **operating
To install the Phorge server software, you will need an **operating
system** on your normal computer which is **not Windows**. Note that the
command line interface //does// work on Windows, and you can //use//
Phabricator from any operating system with a web browser. However, the server
Phorge from any operating system with a web browser. However, the server
software does not run on Windows. It does run on most other operating systems,
so choose one of these instead:
- **Linux**: Most installs use Linux.
- **Mac OS X**: Mac OS X is an acceptable flavor of Linux.
- **FreeBSD**: While FreeBSD is certainly not a flavor of Linux, it is a fine
operating system possessed of many desirable qualities, and Phabricator will
operating system possessed of many desirable qualities, and Phorge will
install and run properly on FreeBSD.
- **Solaris, etc.**: Other systems which look like Linux and quack like Linux
will generally work fine, although we may suffer a reduced ability to
@ -64,8 +64,8 @@ Beyond an operating system, you will need **a webserver**.
works fine.
- **Other**: Other webservers which can run PHP are also likely to work fine,
although these installation instructions will not cover how to set them up.
- **PHP Builtin Server**: Phabricator will not work with the builtin
webserver because Phabricator depends on making requests to itself on some
- **PHP Builtin Server**: Phorge will not work with the builtin
webserver because Phorge depends on making requests to itself on some
workflows, and the builtin webserver is single-threaded.
You will also need:
@ -76,14 +76,14 @@ You will also need:
You'll probably also need a **domain name**. In particular, you should read this
note:
NOTE: Phabricator must be installed on an entire domain. You can not install it
to a path on an existing domain, like `example.com/phabricator/`. Instead,
install it to an entire domain or subdomain, like `phabricator.example.com`.
NOTE: Phorge must be installed on an entire domain. You can not install it
to a path on an existing domain, like `example.com/phorge/`. Instead,
install it to an entire domain or subdomain, like `phorge.example.com`.
Level Requirements
==================
To install and administrate Phabricator, you'll need to be comfortable with
To install and administrate Phorge, you'll need to be comfortable with
common system administration skills. For example, you should be familiar with
using the command line, installing software on your operating system of choice,
working with the filesystem, managing processes, dealing with permissions,
@ -95,7 +95,7 @@ need to know. However, if you aren't very familiar or comfortable with using
this set of skills to troubleshoot and resolve problems, you may encounter
issues which you have substantial difficulty working through.
We assume users installing and administrating Phabricator are comfortable with
We assume users installing and administrating Phorge are comfortable with
common system administration skills and concepts. If you aren't, proceed at
your own risk and expect that your skills may be tested.
@ -107,10 +107,10 @@ scripts available which should handle most of the things discussed in this
document for you:
- **RedHat Derivatives**:
[[ https://secure.phabricator.com/diffusion/P/browse/master/scripts/install/install_rhel-derivs.sh
[[ https://we.phorge.it/diffusion/P/browse/master/scripts/install/install_rhel-derivs.sh
| install_rhel-derivs.sh ]]
- **Ubuntu**:
[[ https://secure.phabricator.com/diffusion/P/browse/master/scripts/install/install_ubuntu.sh
[[ https://we.phorge.it/diffusion/P/browse/master/scripts/install/install_ubuntu.sh
| install_ubuntu.sh ]]
If those work for you, you can skip directly to the
@ -131,18 +131,18 @@ If you already have LAMP setup, you've probably already got everything you need.
It may also be helpful to refer to the install scripts above, even if they don't
work for your system.
Now that you have all that stuff installed, grab Phabricator and its
Now that you have all that stuff installed, grab Phorge and its
dependencies:
$ cd somewhere/ # pick some install directory
somewhere/ $ git clone https://github.com/phacility/arcanist.git
somewhere/ $ git clone https://github.com/phacility/phabricator.git
somewhere/ $ git clone https://we.phorge.it/source/arcanist.git
somewhere/ $ git clone https://we.phorge.it/source/phorge.git
Next Steps
==========
Continue by:
- configuring Phabricator with the @{article:Configuration Guide}; or
- learning how to keep Phabricator up to date with
@{article:Upgrading Phabricator}.
- configuring Phorge with the @{article:Configuration Guide}; or
- learning how to keep Phorge up to date with
@{article:Upgrading Phorge}.

25
src/docs/user/introduction.diviner
View file

@ -1,33 +1,34 @@
@title Introduction
@group intro
This document provides a high-level overview of the Phabricator project.
This document provides a high-level overview of the Phorge project.
= What is Phabricator? =
= What is Phorge? =
**Phabricator** (pronounced like the word //fabricator//) is a suite of web
**Phorge** (pronounced like the word //forge//) is a suite of web
applications which make it easier to build software, particularly when working
with teams. Phabricator is largely based on Facebook's internal tools.
with teams. Phorge is a fork of Phabricator, which in turn is largely based on
Facebook's internal tools.
The major components of Phabricator are:
The major components of Phorge are:
- **Differential**, a code review tool; and
- **Diffusion**, a repository browser; and
- **Maniphest**, a bug tracker; and
- **Phriction**, a wiki.
Phabricator also includes a number of smaller tools.
Phorge also includes a number of smaller tools.
= Why use Phabricator? =
= Why use Phorge? =
Phabricator gives you a box of solid tools for a comparatively small setup cost.
Phorge gives you a box of solid tools for a comparatively small setup cost.
The tools all work together and are richly integrated. The whole thing is free
and open source. You own all your data. Phabricator is extremely fast and proven
and open source. You own all your data. Phorge is extremely fast and proven
to scale both to large datasets (Facebook has 500,000+ commits across many
repositories) and large organizations (Facebook has 500+ fulltime engineers).
Phabricator's tools are easy to learn, understand, and use.
Phorge's tools are easy to learn, understand, and use.
However, Phabricator may also not be a good solution for you:
However, Phorge may also not be a good solution for you:
- If you develop primarily on Windows, you are likely to find integration
with the toolsets you use lacking.
@ -40,4 +41,4 @@ However, Phabricator may also not be a good solution for you:
Continue by:
- installing Phabricator with the @{article:Installation Guide}.
- installing Phorge with the @{article:Installation Guide}.

35
src/docs/user/reporting_security.diviner
View file

@ -1,36 +1,17 @@
@title Reporting Security Vulnerabilities
@group intro
Describes how to report security vulnerabilities in Phabricator.
Describes how to report security vulnerabilities in Phorge.
Overview
========
Phabricator runs a disclosure and award program through
[[ https://www.hackerone.com/ | HackerOne ]]. This program is the best way to
submit security issues to us, and awards responsible disclosure of
vulnerabilities with cash bounties. You can find our project page
here:
Phorge accepts bug reports on the upstream install. Please use the
[[https://we.phorge.it/maniphest/task/edit/form/1/ | security reporting form]]
to report security vulnerabilities.
(NOTE) https://hackerone.com/phabricator
If you aren't sure if something qualifies, you can submit the issue as a normal
bug report. For instructions, see @{article:Contributing Bug Reports}.
The project page has detailed information about the scope of the program and
how to participate.
We have a 24 hour response timeline, and are usually able to respond to (and,
very often, fix) issues more quickly than that.
Other Channels
==============
If you aren't sure if something qualifies or don't want to report via
HackerOne, you can submit the issue as a normal bug report. For instructions,
see @{article:Contributing Bug Reports}.
Get Updated
===========
General information about security changes is reported weekly in the
[[ https://secure.phabricator.com/w/changelog/ | Changelog ]].
General information about security changes is reported in the
[[ https://we.phorge.it/w/changelog/ | Changelog ]].

33
src/docs/user/support.diviner
View file

@ -2,4 +2,35 @@
@short Support
@group intro
Effective June 1, 2021: Phabricator is no longer actively supported.
Resources for reporting bugs, requesting features, and getting support.
Overview
========
The upstream provides free support for a range of problems.
Reporting Security Vulnerabilities
==================================
The upstream accepts, fixes, and awards bounties for reports of material
security issues with the software.
To report security issues, see @{article:Reporting Security Vulnerabilities}.
Reporting Bugs
==============
The upstream will accept **reproducible** bug reports in modern, first-party
production code running in reasonable environments. Before submitting a bug
report you **must update** to the latest version of Phorge.
To report bugs, see @{article:Contributing Bug Reports}.
Contributing
============
If you'd like to contribute to Phorge, start with
@{article:Contributor Introduction}.

65
src/docs/user/upgrading.diviner
View file

@ -1,12 +1,12 @@
@title Upgrading Phabricator
@title Upgrading Phorge
@group intro
This document contains instructions for keeping Phabricator up to date.
This document contains instructions for keeping Phorge up to date.
Overview
========
Phabricator is under active development, and new features are released
Phorge is under active development, and new features are released
continuously. Staying up to date will keep your install secure.
We recommend installs upgrade regularly (every 1-2 weeks). Upgrades usually go
@ -18,8 +18,8 @@ to a useful new feature or an important security change.
Staying On Top of Changes
=========================
We release a weekly [[https://secure.phabricator.com/w/changelog | Changelog]],
which describes changes in the previous week. You can look at the changelogs
We release a [[https://we.phorge.it/w/changelog | Changelog]],
which describes changes over time. You can look at the changelogs
for an idea of what new features are available, upcoming changes, security
information, and warnings about compatibility issues or migrations.
@ -27,21 +27,18 @@ information, and warnings about compatibility issues or migrations.
Stable Branch
=============
You can either run the `master` or `stable` branch of Phabricator. The `stable`
branch is run in the [[ https://phacility.com | Phacility Cluster ]], and lags
about a week behind `master`.
You can either run the `master` or `stable` branch of Phorge. The `stable`
branch is a little more stable than `master`, and may be helpful if you
administrate a larger install.
The `stable` branch is a little more stable than `master`, and may be helpful
if you administrate a larger install.
We promote `master` to `stable` about once a week, then publish the changelog
and deploy the cluster. During the week, major bugfixes are cherry-picked to
the `stable` branch. The changelog lists the `stable` hashes for that week,
as well as any fixes which were cherry-picked.
We promote `master` to `stable` frequently, then publish the changelog. During
the week, major bugfixes are cherry-picked to the `stable` branch. The changelog
lists the `stable` hashes for that week, as well as any fixes which were
cherry-picked.
To switch to `stable`, check the branch out in each working copy:
phabricator/ $ git checkout stable
phorge/ $ git checkout stable
arcanist/ $ git checkout stable
You can now follow the upgrade process normally.
@ -50,26 +47,26 @@ You can now follow the upgrade process normally.
Upgrade Process
===============
IMPORTANT: You **MUST** restart Phabricator after upgrading. For help, see
@{article:Restarting Phabricator}.
IMPORTANT: You **MUST** restart Phorge after upgrading. For help, see
@{article:Restarting Phorge}.
IMPORTANT: You **MUST** upgrade `arcanist` and `phabricator` at the same time.
IMPORTANT: You **MUST** upgrade `arcanist` and `phorge` at the same time.
Phabricator runs on many different systems, with many different webservers.
Phorge runs on many different systems, with many different webservers.
Given this diversity, we don't currently maintain a comprehensive upgrade
script which can work on any system. However, the general steps are the same
on every system:
- Stop the webserver (including `php-fpm`, if you use it).
- Stop the daemons, with `phabricator/bin/phd stop`.
- Run `git pull` in `arcanist/` and `phabricator/`.
- Run `phabricator/bin/storage upgrade`.
- Start the daemons, with `phabricator/bin/phd start`.
- Stop the daemons, with `phorge/bin/phd stop`.
- Run `git pull` in `arcanist/` and `phorge/`.
- Run `phorge/bin/storage upgrade`.
- Start the daemons, with `phorge/bin/phd start`.
- Restart the webserver (and `php-fpm`, if you stopped it earlier).
For some more discussion details, see @{article:Configuration Guide}.
This template script roughly outlines the steps required to upgrade Phabricator.
This template script roughly outlines the steps required to upgrade Phorge.
You'll need to adjust paths and commands a bit for your particular system:
```lang=sh
@ -78,23 +75,23 @@ You'll need to adjust paths and commands a bit for your particular system:
set -e
set -x
# This is an example script for updating Phabricator, similar to the one used to
# update <https://secure.phabricator.com/>. It might not work perfectly on your
# This is an example script for updating Phorge, similar to the one used to
# update <https://we.phorge.it/>. It might not work perfectly on your
# system, but hopefully it should be easy to adapt. This script is not intended
# to work without modifications.
# NOTE: This script assumes you are running it from a directory which contains
# arcanist/, and phabricator/.
# arcanist/, and phorge/.
ROOT=`pwd` # You can hard-code the path here instead.
### STOP WEB SERVER AND DAEMONS ###############################################
# Stop daemons.
$ROOT/phabricator/bin/phd stop
$ROOT/phorge/bin/phd stop
# If running the notification server, stop it.
# $ROOT/phabricator/bin/aphlict stop
# $ROOT/phorge/bin/aphlict stop
# Stop the webserver (apache, nginx, lighttpd, etc). This command will differ
# depending on which system and webserver you are running: replace it with an
@ -108,20 +105,20 @@ sudo /etc/init.d/httpd stop
cd $ROOT/arcanist
git pull
cd $ROOT/phabricator
cd $ROOT/phorge
git pull
# Upgrade the database schema. You may want to add the "--force" flag to allow
# this script to run noninteractively.
$ROOT/phabricator/bin/storage upgrade
$ROOT/phorge/bin/storage upgrade
# Restart the webserver. As above, this depends on your system and webserver.
# NOTE: If you're running php-fpm, restart it here too.
sudo /etc/init.d/httpd start
# Restart daemons.
$ROOT/phabricator/bin/phd start
$ROOT/phorge/bin/phd start
# If running the notification server, start it.
# $ROOT/phabricator/bin/aphlict start
# $ROOT/phorge/bin/aphlict start
```

6
src/docs/user/userguide/almanac.diviner
View file

@ -11,7 +11,7 @@ lists of //devices// and //services// that humans and other applications can
use to keep track of what is running where.
Almanac is an infrastructure application that will normally be used by
administrators to configure advanced Phabricator features. In most cases,
administrators to configure advanced Phorge features. In most cases,
normal users will very rarely interact with Almanac directly.
At a very high level, Almanac can be thought of as a bit like a DNS server.
@ -19,11 +19,11 @@ Callers ask it for information about services, and it responds with details
about which devices host those services. However, it can respond to a broader
range of queries and provide more detailed responses than DNS alone can.
Today, the primary use cases for Almanac are internal to Phabricator:
Today, the primary use cases for Almanac are internal to Phorge:
- Providing a list of build servers to Drydock so it can run build and
integration tasks.
- Configuring Phabricator to operate in a cluster setup.
- Configuring Phorge to operate in a cluster setup.
Beyond internal uses, Almanac is a general-purpose service and device inventory
application and can be used to configure and manage other types of service and

2
src/docs/user/userguide/amazon_rds.diviner
View file

@ -6,7 +6,7 @@ Discusses using Amazon RDS as a database.
Overview
========
Phabricator works with Amazon RDS. However, most of our documentation and setup
Phorge works with Amazon RDS. However, most of our documentation and setup
checks assume you are using local MySQL, and upstream support is less available
for RDS.

8
src/docs/user/userguide/arcanist.diviner
View file

@ -1,9 +1,9 @@
@title Arcanist User Guide
@group userguide
Guide to Arcanist, a command-line interface to Phabricator.
Guide to Arcanist, a command-line interface to Phorge.
Arcanist provides command-line access to many Phabricator tools (like
Arcanist provides command-line access to many Phorge tools (like
Differential, Files, and Paste), integrates with static analysis ("lint") and
unit tests, and manages common workflows like getting changes into Differential
for review.
@ -12,7 +12,7 @@ A detailed command reference is available by running `arc help`. This
document provides an overview of common workflows and installation.
Arcanist has technical, contributor-focused documentation here:
<https://secure.phabricator.com/book/arcanist/>
<https://we.phorge.it/book/arcanist/>
= Quick Start =
@ -143,7 +143,7 @@ three sources, in order:
# User configuration is read from `~/.arcconfig`. This file is JSON, and can
be updated using `arc set-config`.
# Host configuration is read from `/etc/arcconfig` (on Windows, the path
is `C:\ProgramData\Phabricator\Arcanist\config`).
is `C:\ProgramData\Phorge\Arcanist\config`).
Arcanist uses the first definition it encounters as the runtime setting.

6
src/docs/user/userguide/arcanist_coverage.diviner
View file

@ -1,7 +1,7 @@
@title Arcanist User Guide: Code Coverage
@group userguide
Explains code coverage features in Arcanist and Phabricator.
Explains code coverage features in Arcanist and Phorge.
This is a configuration guide that helps you set up advanced features. If you're
just getting started, you don't need to look at this yet. Instead, start with
@ -27,9 +27,9 @@ to `src/some/file.php` and give you a detailed coverage report.
If the test engine enables coverage by default, it will be uploaded to
Differential and displayed in the right gutter when viewing diffs.
= Enabling Coverage for Arcanist and Phabricator =
= Enabling Coverage for Arcanist and Phorge =
If you're contributing, Arcanist and Phabricator support coverage if
If you're contributing, Arcanist and Phorge support coverage if
you install Xdebug:
http://xdebug.org/

4
src/docs/user/userguide/arcanist_diff.diviner
View file

@ -14,7 +14,7 @@ information.
= Overview =
While `arc` has a large number of commands that interface with various
Phabricator applications, the primary use of `arc` is to send changes for
Phorge applications, the primary use of `arc` is to send changes for
review in Differential (for more information on Differential, see
@{article:Differential User Guide}). If you aren't familiar with Differential,
it may be instructive to read that article first to understand the big picture
@ -167,7 +167,7 @@ You can use `arc help <command>` for detailed help with any of these.
Differential will make a guess about a next step on accepted revisions, but it
may not be the best next step for your workflow.
Phabricator will also automatically close revisions if the changes are pushed
Phorge will also automatically close revisions if the changes are pushed
to a repository that is tracked in Diffusion. Specifically, it will close
revisions based on commit and tree hashes, and `Differential Revision`
identifiers in commit messages.

2
src/docs/user/userguide/arcanist_lint_unit.diviner
View file

@ -38,7 +38,7 @@ make this work, you need to do three things:
If you haven't created a library for the class to live in yet, you need to do
that first. Follow the instructions in
@{article@phabcontrib:Adding New Classes}, then make the library loadable by
@{article@contrib:Adding New Classes}, then make the library loadable by
adding it to your `.arcconfig` like this:
{

14
src/docs/user/userguide/arcanist_new_project.diviner
View file

@ -15,11 +15,11 @@ An `.arcconfig` file is a JSON file which you check into your project's root.
Arcanist uses `.arcconfig` files to customize a number of things about its
behavior. The first thing you're likely to want to configure is the URI
for your Phabricator install. A simple, valid file looks something like this:
for your Phorge install. A simple, valid file looks something like this:
name=.arcconfig
{
"phabricator.uri" : "https://phabricator.example.com/"
"phabricator.uri" : "https://phorge.example.com/"
}
For details on available options, see below.
@ -31,7 +31,7 @@ configuration, not user configuration.
Common options are:
- **phabricator.uri**: the URI for the Phabricator install that `arc` should
- **phabricator.uri**: the URI for the Phorge install that `arc` should
connect to when run in this project. This option was previously called
`conduit_uri`.
- **repository.callsign**: The callsign of this repository in Diffusion.
@ -47,7 +47,7 @@ Other options include:
- **load**: list of additional Phutil libraries to load at startup.
See below for details about path resolution, or see
@{article@phabcontrib:Adding New Classes} for a general introduction to
@{article@contrib:Adding New Classes} for a general introduction to
libphutil libraries.
- **https.cabundle**: specifies the path to an alternate certificate bundle
for use when making HTTPS connections.
@ -62,9 +62,9 @@ Other options include:
These options are supported, but their use is discouraged:
- **http.basicauth.user**: specify an HTTP basic auth username for use when
connecting to Phabricator.
connecting to Phorge.
- **http.basicauth.pass**: specify an HTTP basic auth password for use when
connecting to Phabricator.
connecting to Phorge.
- **https.blindly-trust-domains**: a list of domains to trust blindly over
HTTPS, even if their certificates are invalid. This is a brute force
solution to certificate validity problems, and is discouraged. Instead,
@ -182,7 +182,7 @@ some features won't work unless you set up an `.arcconfig` file.
Without `.arcconfig`:
- You will need to set a default Phabricator URI with
- You will need to set a default Phorge URI with
`arc set-config default <uri>`, or specify an explicit URI
with `--conduit-uri` each time you run a command.
- You will not be able to run linters through arc unless you pass `--engine`

8
src/docs/user/userguide/arcanist_quick_start.diviner
View file

@ -40,17 +40,17 @@ Create a `.arcconfig` file in your project's working copy:
yourproject/ $ $EDITOR .arcconfig
yourproject/ $ cat .arcconfig
{
"phabricator.uri" : "https://phabricator.example.com/"
"phabricator.uri" : "https://phorge.example.com/"
}
Set `phabricator.uri` to the URI for your Phabricator install (where `arc`
Set `phabricator.uri` to the URI for your Phorge install (where `arc`
should send changes to).
NOTE: You should **commit this file** to the repository.
= Install Arcanist Credentials =
Credentials allow you to authenticate. You must have an account on Phabricator
Credentials allow you to authenticate. You must have an account on Phorge
before you can perform this step.
$ cd yourproject/
@ -58,7 +58,7 @@ before you can perform this step.
...
Follow the instructions. This will link your user account on your local machine
to your Phabricator account.
to your Phorge account.
= Send Changes For Review =

10
src/docs/user/userguide/audit.diviner
View file

@ -1,13 +1,13 @@
@title Audit User Guide
@group userguide
Guide to using Phabricator to audit published commits.
Guide to using Phorge to audit published commits.
Overview
========
Phabricator supports two code review workflows, "review" (pre-publish) and
Phorge supports two code review workflows, "review" (pre-publish) and
"audit" (post-publish). To understand the differences between the two, see
@{article:User Guide: Review vs Audit}.
@ -59,14 +59,14 @@ a typical audit workflow:
- Alice publishes a commit containing some Javascript.
- This triggers an audit request to Bailey, the Javascript technical
lead on the project (see below for a description of trigger mechanisms).
- Later, Bailey logs into Phabricator and sees the audit request. She ignores
- Later, Bailey logs into Phorge and sees the audit request. She ignores
it for the moment, since it isn't blocking anything. At the end of the
week she looks through her open requests to see what the team has been
up to.
- Bailey notices a few minor problems with Alice's commit. She leaves
comments describing improvements and uses "Raise Concern" to send the
commit back into Alice's queue.
- Later, Alice logs into Phabricator and sees that Bailey has raised a
- Later, Alice logs into Phorge and sees that Bailey has raised a
concern (usually, Alice will also get an email). She resolves the issue
somehow, maybe by making a followup commit with fixes.
- After the issues have been dealt with, she uses "Request Verification" to
@ -163,7 +163,7 @@ The `bin/audit` command allows you to perform several maintenance operations.
Get more information about a command by running:
```
phabricator/ $ ./bin/audit help <command>
phorge/ $ ./bin/audit help <command>
```
Supported operations are:

2
src/docs/user/userguide/calendar.diviner
View file

@ -29,7 +29,7 @@ Reminders are sent 15 minutes before events begin.
Availability
============
Across all applications, Phabricator shows a red dot next to usernames if the
Across all applications, Phorge shows a red dot next to usernames if the
user is currently attending an event. This provides a hint that they may be in
a meeting (or on vacation) and could take a while to get back to you about a
revision or task.

8
src/docs/user/userguide/calendar_exports.diviner
View file

@ -9,15 +9,15 @@ Overview
IMPORTANT: Calendar is a prototype application. See
@{article:User Guide: Prototype Applications}.
You can export events from Phabricator to other calendar applications like
You can export events from Phorge to other calendar applications like
**Google Calendar** or **Calendar.app**. This document will guide you through
how to export event data from Phabricator.
how to export event data from Phorge.
When you export events into another application, they generally will not be
editable from that application. Exporting events allows you to create one
calendar that shows all the events you care about in whatever application you
prefer (so you can keep track of everything you need to do), but does not let
you edit Phabricator events from another application.
you edit Phorge events from another application.
When exporting events, you can either export individual events one at a time
or export an entire group of events (for example, all events you are attending).
@ -75,7 +75,7 @@ The **policy modes** for exports are:
information, as though they were logged in with your account.
WARNING: Anyone who learns the URI for an export can see the data you choose
to export, even if they don't have a Phabricator account! Be careful about how
to export, even if they don't have a Phorge account! Be careful about how
much data you export and treat the URI as a secret. If you accidentally share
a URI, you can disable the export.

24
src/docs/user/userguide/calendar_imports.diviner
View file

@ -9,14 +9,14 @@ Overview
IMPORTANT: Calendar is a prototype application. See
@{article:User Guide: Prototype Applications}.
You can import events into Phabricator to other calendar applications or from
You can import events into Phorge to other calendar applications or from
`.ics` files. This document will guide you through how to import event data
into Phabricator.
into Phorge.
When you import events from another application, they can not be edited in
Phabricator. Importing events allows you to share events or keep track of
Phorge. Importing events allows you to share events or keep track of
events from different sources, but does not let you edit events from other
applications in Phabricator.
applications in Phorge.
Import Policies
@ -36,18 +36,18 @@ Importing `.ics` Files
event or an entire event calendar.
If you have an event or calendar in `.ics` format, you can import it into
Phabricator in two ways:
Phorge in two ways:
- Navigate to {nav Calendar > Imports > Import Events > Import .ics File}.
- Drag and drop the file onto a Calendar.
This will create a copy of the event in Phabricator.
This will create a copy of the event in Phorge.
If you want to update an imported event later, just repeat this process. The
event will be updated with the latest information.
Many applications send `.ics` files as email attachments. You can import these
into Phabricator.
into Phorge.
.ics Files: Google Calendar
@ -68,9 +68,9 @@ saving the calendar as a `.ics` file.
You can also convert an individual event into an `.ics` file by dragging it
from the calendar to your desktop (or any other folder).
When you import an event using an `.ics` file, Phabricator can not
When you import an event using an `.ics` file, Phorge can not
automatically keep the event up to date. You'll need to repeat the process if
there are changes to the event or calendar later, so Phabricator can learn
there are changes to the event or calendar later, so Phorge can learn
about the updates.
@ -78,7 +78,7 @@ Importing .ics URIs
=====================
If you have a calendar in another application that supports publishing a
`.ics` URI, you can subscribe to it in Phabricator. This will import the entire
`.ics` URI, you can subscribe to it in Phorge. This will import the entire
calendar, and can be configured to automatically keep it up to date and in sync
with the external calendar.
@ -87,7 +87,7 @@ below for some guidance on popular calendar applications). Then, browse to
{nav Calendar > Imports > Import Events > Import .ics URI}.
When you import a URI, you can choose to enable automatic updates. If you do,
Phabricator will periodically update the events it imports from this source.
Phorge will periodically update the events it imports from this source.
You can stop this later by turning off the automatic updates or disabling
the import.
@ -121,7 +121,7 @@ shared.
**Calendar.app** does not support subscriptions via `.ics` URIs.
You can export a calendar as an `.ics` file by following the steps above, but
Phabricator can not automatically keep events imported in this way up to date.
Phorge can not automatically keep events imported in this way up to date.
Next Steps

4
src/docs/user/userguide/conduit.diviner
View file

@ -6,7 +6,7 @@ Overview of the Conduit API.
Overview
========
Conduit is the HTTP API for Phabricator. It is roughly JSON-RPC: you usually
Conduit is the HTTP API for Phorge. It is roughly JSON-RPC: you usually
pass a JSON blob, and usually get a JSON blob back, although both call and
result formats are flexible in some cases.
@ -30,7 +30,7 @@ in another language without needing a real client.
includes examples which show how to format calls.
**Other Clients**: There are also clients available in other languages. You
can check the [[ https://secure.phabricator.com/w/community_resources/ |
can check the [[ https://we.phorge.it/w/community_resources/ |
Community Resources ]] page for links.
API Console

4
src/docs/user/userguide/differential.diviner
View file

@ -5,7 +5,7 @@ Guide to the Differential (pre-push code review) tool and workflow.
= Overview =
Phabricator supports two code review workflows, "review" (pre-push) and
Phorge supports two code review workflows, "review" (pre-push) and
"audit" (post-push). To understand the differences between the two, see
@{article:User Guide: Review vs Audit}.
@ -14,7 +14,7 @@ This document summarizes the pre-push "review" workflow implemented by the tool
= How Review Works =
Code review in Phabricator is a lightweight, asynchronous web-based process. If
Code review in Phorge is a lightweight, asynchronous web-based process. If
you are familiar with GitHub, it is similar to how pull requests work:
- An author prepares a change to a codebase, then sends it for review. They

4
src/docs/user/userguide/differential_land.diviner
View file

@ -1,7 +1,7 @@
@title Differential User Guide: Automated Landing
@group userguide
Configuring Phabricator so you can "Land Revision" from the web UI.
Configuring Phorge so you can "Land Revision" from the web UI.
Overview
@ -9,7 +9,7 @@ Overview
IMPORTANT: This feature is a prototype and has substantial limitations.
Phabricator can be configured so that approved revisions may be published
Phorge can be configured so that approved revisions may be published
directly from the web interface. This can make publishing changes more
convenient, particularly for open source projects where authors may not have
commit access to the repository. This document explains the workflow and how to

8
src/docs/user/userguide/diffusion.diviner
View file

@ -1,7 +1,7 @@
@title Diffusion User Guide
@group userguide
Guide to Diffusion, the Phabricator application for hosting and browsing
Guide to Diffusion, the Phorge application for hosting and browsing
repositories.
Overview
@ -16,7 +16,7 @@ other existing hosting). Both types of repositories can be browsed and
interacted with, but hosted repositories support some additional triggers
and access controls which are not available for observed repositories.
Diffusion is integrated with the other tools in the Phabricator suite. For
Diffusion is integrated with the other tools in the Phorge suite. For
instance:
- when you commit Differential revisions to a tracked repository, they are
@ -61,7 +61,7 @@ API to create and edit repositories, see
Repository Clustering
=====================
Phabricator repository hosts can be set up in a cluster configuration so you
Phorge repository hosts can be set up in a cluster configuration so you
can lose hosts with minimal downtime and data loss. This is an advanced feature
which most installs do not need to pursue.
@ -88,7 +88,7 @@ helpful:
- get details about automatically taking actions in response to commits in
@{article:Diffusion User Guide: Permanent Refs}; or
- understand how Phabricator updates repositories with
- understand how Phorge updates repositories with
@{article:Diffusion User Guide: Repository Updates}; or
- fix issues with repository imports with
@{article:Troubleshooting Repository Imports}.

Some files were not shown because too many files have changed in this diff Show more