mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-09 16:32:39 +01:00
Update Diviner documentation to reference Phorge instead of Phabricator.
Summary: This commit also removes references to support pacts and updates links to point to the new upstream. Test Plan: Generated Diviner documentation on a local install and verified that the changes look good. Reviewers: O1 Blessed Committers, chris Reviewed By: O1 Blessed Committers, chris Subscribers: chris, speck, tobiaswiese Maniphest Tasks: T15012 Differential Revision: https://we.phorge.it/D25007
This commit is contained in:
parent
7157dd96b3
commit
1ddb953b9f
138 changed files with 1712 additions and 1399 deletions
|
@ -1,11 +1,11 @@
|
||||||
{
|
{
|
||||||
"name": "phabcontrib",
|
"name": "contrib",
|
||||||
"title": "Phabricator Contributor Documentation",
|
"title": "Phorge Contributor Documentation",
|
||||||
"short": "Phabricator Contributor Docs",
|
"short": "Contributor Docs",
|
||||||
"preface": "Information for Phabricator contributors and developers.",
|
"preface": "Information for Phorge contributors and developers.",
|
||||||
"root": "../../../",
|
"root": "../../../",
|
||||||
"uri.source":
|
"uri.source":
|
||||||
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
|
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
|
||||||
"rules": {
|
"rules": {
|
||||||
"(\\.diviner$)": "DivinerArticleAtomizer"
|
"(\\.diviner$)": "DivinerArticleAtomizer"
|
||||||
},
|
},
|
||||||
|
|
|
@ -1,11 +1,11 @@
|
||||||
{
|
{
|
||||||
"name": "phabflavor",
|
"name": "flavor",
|
||||||
"title": "Phabricator Flavor Text",
|
"title": "Phorge Flavor Text",
|
||||||
"short": "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": "../../../",
|
"root": "../../../",
|
||||||
"uri.source":
|
"uri.source":
|
||||||
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
|
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
|
||||||
"rules": {
|
"rules": {
|
||||||
"(\\.diviner$)": "DivinerArticleAtomizer"
|
"(\\.diviner$)": "DivinerArticleAtomizer"
|
||||||
},
|
},
|
||||||
|
@ -20,14 +20,11 @@
|
||||||
"(^webroot/rsrc/externals/)"
|
"(^webroot/rsrc/externals/)"
|
||||||
],
|
],
|
||||||
"groups": {
|
"groups": {
|
||||||
"overview": {
|
|
||||||
"name": "Overview"
|
|
||||||
},
|
|
||||||
"javascript": {
|
"javascript": {
|
||||||
"name": "Javascript"
|
"name": "Javascript"
|
||||||
},
|
},
|
||||||
"lore": {
|
"lore": {
|
||||||
"name": "Phabricator Lore"
|
"name": "Phorge Lore"
|
||||||
},
|
},
|
||||||
"php": {
|
"php": {
|
||||||
"name": "PHP"
|
"name": "PHP"
|
||||||
|
|
|
@ -1,11 +1,11 @@
|
||||||
{
|
{
|
||||||
"name": "phabdev",
|
"name": "dev",
|
||||||
"title": "Phabricator Technical Documentation",
|
"title": "Phorge Technical Documentation",
|
||||||
"short": "Phabricator Tech Docs",
|
"short": "Tech Docs",
|
||||||
"preface": "Technical reference material for Phabricator developers.",
|
"preface": "Technical reference material for Phorge developers.",
|
||||||
"root": "../../../",
|
"root": "../../../",
|
||||||
"uri.source":
|
"uri.source":
|
||||||
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
|
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
|
||||||
"rules": {
|
"rules": {
|
||||||
"(\\.diviner$)": "DivinerArticleAtomizer",
|
"(\\.diviner$)": "DivinerArticleAtomizer",
|
||||||
"(\\.php$)": "DivinerPHPAtomizer"
|
"(\\.php$)": "DivinerPHPAtomizer"
|
|
@ -1,11 +1,11 @@
|
||||||
{
|
{
|
||||||
"name": "phabricator",
|
"name": "phorge",
|
||||||
"title": "Phabricator User Documentation",
|
"title": "Phorge User Documentation",
|
||||||
"short": "Phabricator User Docs",
|
"short": "User Docs",
|
||||||
"preface": "Instructions for installing, configuring, and using Phabricator.",
|
"preface": "Instructions for installing, configuring, and using Phorge.",
|
||||||
"root": "../../../",
|
"root": "../../../",
|
||||||
"uri.source":
|
"uri.source":
|
||||||
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
|
"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
|
||||||
"rules": {
|
"rules": {
|
||||||
"(\\.diviner$)": "DivinerArticleAtomizer"
|
"(\\.diviner$)": "DivinerArticleAtomizer"
|
||||||
},
|
},
|
||||||
|
@ -37,9 +37,6 @@
|
||||||
},
|
},
|
||||||
"fieldmanual": {
|
"fieldmanual": {
|
||||||
"name": "Field Manuals"
|
"name": "Field Manuals"
|
||||||
},
|
|
||||||
"cellar": {
|
|
||||||
"name": "Musty Cellar"
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
@ -1,22 +1,22 @@
|
||||||
@title Adding New Classes
|
@title Adding New Classes
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
Guide to adding new classes to extend Phabricator.
|
Guide to adding new classes to extend Phorge.
|
||||||
|
|
||||||
Overview
|
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
|
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
|
Fundamentals
|
||||||
============
|
============
|
||||||
|
|
||||||
Phabricator primarily discovers functionality by looking at concrete subclasses
|
Phorge primarily discovers functionality by looking at concrete subclasses
|
||||||
of some base class. For example, Phabricator determines which applications are
|
of some base class. For example, Phorge determines which applications are
|
||||||
available by looking at all of the subclasses of
|
available by looking at all of the subclasses of
|
||||||
@{class@phabricator:PhabricatorApplication}. It
|
@{class@phabricator:PhabricatorApplication}. It
|
||||||
discovers available workflows in `arc` by looking at all of the subclasses of
|
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}.
|
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
|
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.
|
integrate the new capabilities or features at runtime.
|
||||||
|
|
||||||
There are two main ways to add classes:
|
There are two main ways to add classes:
|
||||||
|
@ -42,20 +42,20 @@ The next sections walk through these approaches in greater detail.
|
||||||
Extensions Directory
|
Extensions Directory
|
||||||
====================
|
====================
|
||||||
|
|
||||||
The easiest way to extend Phabricator by adding new classes is to drop them
|
The easiest way to extend Phorge by adding new classes is to drop them
|
||||||
into the extensions directory, at `phabricator/src/extensions/`.
|
into the extensions directory, at `pohrge/src/extensions/`.
|
||||||
|
|
||||||
This is intended as a quick way to add small pieces of functionality, test new
|
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.
|
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/`.
|
directory in `arcanist/src/extensions/`.
|
||||||
|
|
||||||
For example, to add a new application, create a file like this one and add it
|
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
|
<?php
|
||||||
|
|
||||||
final class ExampleApplication extends PhabricatorApplication {
|
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
|
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
|
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.
|
extensions.
|
||||||
|
|
||||||
|
|
||||||
Creating Libraries
|
Creating Libraries
|
||||||
==================
|
==================
|
||||||
|
|
||||||
A more powerful (but more complicated) way to extend Phabricator is to create
|
A more powerful (but more complicated) way to extend Phorge is to create
|
||||||
a libphutil library. Libraries can organize a larger amount of code, are easier
|
a library. Libraries can organize a larger amount of code, are easier
|
||||||
to work with and distribute, and have slightly better performance than loose
|
to work with and distribute, and have slightly better performance than loose
|
||||||
source files in the extensions directory.
|
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.
|
- Create a new directory.
|
||||||
- Use `arc liberate` to initialize and name the library.
|
- 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:
|
Then, to add new code, you do this:
|
||||||
|
|
||||||
|
@ -95,7 +95,7 @@ Then, to add new code, you do this:
|
||||||
Initializing a Library
|
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
|
`arc liberate` on the directory. This documentation will use a conventional
|
||||||
directory layout, which is recommended, but you are free to deviate from this.
|
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
|
(functions and classes) in the library, which allows them to be autoloaded
|
||||||
at runtime and dependencies to be statically managed by `arc liberate`.
|
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
|
(NOTE) If you aren't using this library with Phorge (e.g., you are only using it
|
||||||
with Arcanist or are building something else on libphutil) you can skip this
|
with Arcanist or are building something else) you can skip this
|
||||||
step.
|
step.
|
||||||
|
|
||||||
But, if you intend to use this library with Phabricator, you need to define its
|
But, if you intend to use this library with Phorge, you need to define its
|
||||||
dependency on Phabricator by creating a `.arcconfig` file which points at
|
dependency on Phorge by creating a `.arcconfig` file which points at
|
||||||
Phabricator. For example, you might write this file to
|
Phorge. For example, you might write this file to
|
||||||
`libcustom/.arcconfig`:
|
`libcustom/.arcconfig`:
|
||||||
|
|
||||||
```lang=json
|
```lang=json
|
||||||
{
|
{
|
||||||
"load": [
|
"load": [
|
||||||
"phabricator/src/"
|
"phorge/src/"
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
For details on creating a `.arcconfig`, see
|
For details on creating a `.arcconfig`, see
|
||||||
@{article:Arcanist User Guide: Configuring a New Project}. In general, this
|
@{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.
|
performing static analysis.
|
||||||
|
|
||||||
NOTE: If Phabricator isn't located next to your custom library, specify a
|
NOTE: If Phorge isn't located next to your custom library, specify a
|
||||||
path which actually points to the `phabricator/` directory.
|
path which actually points to the `phorge/` directory.
|
||||||
|
|
||||||
You do not need to declare dependencies on `arcanist`, since `arc liberate`
|
You do not need to declare dependencies on `arcanist`, since `arc liberate`
|
||||||
automatically loads them.
|
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`:
|
runtime, by adding it to `load-libraries`:
|
||||||
|
|
||||||
```lang=json
|
```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
|
Writing Classes
|
||||||
|
@ -206,20 +206,20 @@ This will automatically regenerate the static map of the library.
|
||||||
What You Can Extend And Invoke
|
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
|
visibility of methods and properties. Most classes are marked `final`, and
|
||||||
methods have the minimum required visibility (protected or private). The goal
|
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
|
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.
|
invoke, so your code will keep working as the upstream changes.
|
||||||
|
|
||||||
IMPORTANT: We'll still break APIs frequently. The upstream does not support
|
IMPORTANT: We'll still break APIs frequently. The upstream offers limited
|
||||||
extension development, and none of these APIs are stable.
|
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.
|
respect method and property visibility.
|
||||||
|
|
||||||
If you want to add features but can't figure out how to do it without changing
|
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
|
- {icon check, color=green} **Use Composition**: If possible, use composition
|
||||||
rather than extension to build your feature.
|
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
|
- {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
|
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
|
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
|
why we don't let you do it.
|
||||||
development so you may have mixed luck with this one.
|
|
||||||
|
|
||||||
These approaches are **discouraged**, but also possible:
|
These approaches are **discouraged**, but also possible:
|
||||||
|
|
||||||
|
@ -252,5 +251,5 @@ Next Steps
|
||||||
|
|
||||||
Continue by:
|
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.
|
Community Resources ]] page to find or share extensions and libraries.
|
||||||
|
|
|
@ -1,21 +1,19 @@
|
||||||
@title Adding New CSS and JS
|
@title Adding New CSS and JS
|
||||||
@group developer
|
@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 =
|
= Overview =
|
||||||
|
|
||||||
Phabricator uses a system called **Celerity** to manage static resources. If you
|
Phorge uses a system called **Celerity** to manage static resources.
|
||||||
are a current or former Facebook employee, Celerity is based on the Haste system
|
|
||||||
used at Facebook and generally behaves similarly.
|
|
||||||
|
|
||||||
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.
|
process will not work correctly for third-party code, plugins, or extensions.
|
||||||
|
|
||||||
= Adding a New File =
|
= Adding a New File =
|
||||||
|
|
||||||
To add a new CSS or JS file, create it in an appropriate location in
|
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.
|
directory.
|
||||||
|
|
||||||
Each file must `@provides` itself as a component, declared in a header comment:
|
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
|
When you add, move or remove a file, or change the contents of existing JS or
|
||||||
CSS file, you should rebuild the Celerity map:
|
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
|
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
|
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
|
quite often. They can be resolved by running the Celerity mapper. You can
|
||||||
automate this process by running:
|
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
|
This will install Git merge driver which will run when a conflict in this file
|
||||||
occurs.
|
occurs.
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Assistive Technologies
|
@title Assistive Technologies
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
Information about making Phabricator accessible to assistive technologies.
|
Information about making Phorge accessible to assistive technologies.
|
||||||
|
|
||||||
Overview
|
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
|
screen readers can assist people with limited or no eyesight by reading the
|
||||||
contents of pages aloud.
|
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
|
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
|
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
|
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.
|
mute visual-only elements.
|
||||||
|
|
|
@ -1,5 +1,156 @@
|
||||||
@title Contributing Bug Reports
|
@title Contributing Bug Reports
|
||||||
@group detail
|
@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}.
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
@title Celerity Technical Documentation
|
@title Celerity Technical Documentation
|
||||||
@group celerity
|
@group developer
|
||||||
|
|
||||||
Technical overview of the Celerity system.
|
Technical overview of the Celerity system.
|
||||||
|
|
|
@ -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.
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Contributor Introduction
|
@title Contributor Introduction
|
||||||
@group contrib
|
@group contrib
|
||||||
|
|
||||||
Introduction to contributing to Phabricator and Arcanist.
|
Introduction to contributing to Phorge and Arcanist.
|
||||||
|
|
||||||
Overview
|
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.
|
ways you can help improve the project.
|
||||||
|
|
||||||
Writing code is valuable, but often isn't the best or easiest way to contribute.
|
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
|
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
|
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
|
- Recommend Phorge to people who you think might find it useful. Our
|
||||||
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
|
|
||||||
most powerful growth channel is word of mouth, and mentioning or tweeting
|
most powerful growth channel is word of mouth, and mentioning or tweeting
|
||||||
about Phabricator helps the project grow. If writing a tweet sounds like
|
about Phorge helps the project grow.
|
||||||
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.
|
|
||||||
|
|
||||||
- Submit high-quality bug reports by carefully following the guide in
|
- Submit high-quality bug reports by carefully following the guide in
|
||||||
@{article:Contributing Bug Reports}.
|
@{article:Contributing Bug Reports}.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,197 @@
|
||||||
@title Contributing Code
|
@title Contributing Code
|
||||||
@group detail
|
@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}.
|
||||||
|
|
|
@ -1,14 +1,14 @@
|
||||||
@title CSS Coding Standards
|
@title CSS Coding Standards
|
||||||
@group standards
|
@group standards
|
||||||
|
|
||||||
This document describes CSS features and coding standards for Phabricator.
|
This document describes CSS features and coding standards for Phorge.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
This document describes technical and style guidelines for writing CSS in
|
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.
|
it makes available.
|
||||||
|
|
||||||
= Z-Indexes =
|
= Z-Indexes =
|
||||||
|
@ -19,7 +19,7 @@ Great Z-Index War where all indexes grow without bound in an endless arms race.
|
||||||
|
|
||||||
= Color Variables =
|
= 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:
|
reference these with `{$color}`. For example:
|
||||||
|
|
||||||
lang=css
|
lang=css
|
||||||
|
@ -60,7 +60,7 @@ by the media query.
|
||||||
|
|
||||||
= Device Rules =
|
= 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:
|
adjust behavior responsively. In particular:
|
||||||
|
|
||||||
lang=css
|
lang=css
|
||||||
|
@ -86,6 +86,6 @@ either tablets or phones:
|
||||||
|
|
||||||
= Image Inlining =
|
= 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
|
32KB using `data:` URIs. This is primarily useful for gradients or textures
|
||||||
which are small and difficult to sprite.
|
which are small and difficult to sprite.
|
||||||
|
|
|
@ -7,10 +7,10 @@ questions like how to store new types of data.
|
||||||
Database System
|
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).
|
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
|
`search_documentfield` table which uses MyISAM because MySQL doesn't support
|
||||||
fulltext search in InnoDB (recent versions do, but we haven't added support
|
fulltext search in InnoDB (recent versions do, but we haven't added support
|
||||||
yet).
|
yet).
|
||||||
|
@ -21,22 +21,22 @@ SQLite.
|
||||||
PHP Drivers
|
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.
|
[[ http://www.php.net/book.mysqli | MySQLi ]] PHP extensions.
|
||||||
|
|
||||||
Databases
|
Databases
|
||||||
=========
|
=========
|
||||||
|
|
||||||
Each Phabricator application has its own database. The names are prefixed by
|
Each Phorge application has its own database. The names are prefixed by
|
||||||
`phabricator_` (this is configurable).
|
`phorge_` (this is configurable).
|
||||||
|
|
||||||
Phabricator uses a separate database for each application. To understand why,
|
Phorge uses a separate database for each application. To understand why,
|
||||||
see @{article:Why does Phabricator need so many databases?}.
|
see @{article:Why does Phorge need so many databases?}.
|
||||||
|
|
||||||
Connections
|
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
|
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
|
connections to a replica in primary/replica setups (which are not actually
|
||||||
supported yet).
|
supported yet).
|
||||||
|
@ -45,7 +45,7 @@ Tables
|
||||||
======
|
======
|
||||||
|
|
||||||
Most table names are prefixed by their application names. For example,
|
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
|
table `differential_revision`. This generally makes queries easier to recognize
|
||||||
and understand.
|
and understand.
|
||||||
|
|
||||||
|
@ -57,7 +57,7 @@ We use lower-case table names with words separated by underscores.
|
||||||
Column Names
|
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.
|
directly map to properties in PHP classes.
|
||||||
|
|
||||||
Don't use MySQL reserved words (such as `order`) for column names.
|
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
|
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
|
`phid`) which map to MySQL column types. The mapping depends on the MySQL
|
||||||
version.
|
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
|
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
|
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
|
is more widely available, does not support them). On newer MySQL, we use
|
||||||
`utf8mb4` to take advantage of improved collation rules.
|
`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
|
`int unsigned`. Although this makes dates less readable when browsing the
|
||||||
database, it makes date and time manipulation more consistent and
|
database, it makes date and time manipulation more consistent and
|
||||||
straightforward in the application.
|
straightforward in the application.
|
||||||
|
@ -134,8 +134,8 @@ eventually, but there isn't a strong case for them at the present time.
|
||||||
PHIDs
|
PHIDs
|
||||||
=====
|
=====
|
||||||
|
|
||||||
Each globally referencable object in Phabricator has an associated PHID
|
Each globally referencable object in Phorge has an associated PHID
|
||||||
("Phabricator ID") which serves as a global identifier, similar to a GUID.
|
("Phorge ID") which serves as a global identifier, similar to a GUID.
|
||||||
We use PHIDs for referencing data in different databases.
|
We use PHIDs for referencing data in different databases.
|
||||||
|
|
||||||
We use both auto-incrementing IDs and global PHIDs because each is useful in
|
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;
|
etc). Without PHIDs, we would need to add a "type" column to avoid ID collision;
|
||||||
using PHIDs makes implementing features like this simpler.
|
using PHIDs makes implementing features like this simpler.
|
||||||
|
|
||||||
|
For more information, see @{article:Handles Technical Documentation}
|
||||||
|
|
||||||
Transactions
|
Transactions
|
||||||
============
|
============
|
||||||
|
|
||||||
|
@ -169,7 +171,7 @@ update, and understand than application code.
|
||||||
Schema Denormalization
|
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.
|
there is a compelling reason (usually, performance) to denormalize.
|
||||||
|
|
||||||
Schema Changes and Migrations
|
Schema Changes and Migrations
|
||||||
|
|
|
@ -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:
|
Here are some examples of good ways to start a problem description:
|
||||||
|
|
||||||
> My company does contracting work for government agencies. Because of the
|
(NOTE) My company does contracting work for government agencies. Because of the
|
||||||
> nature of our customers, deadlines are critical and it's very important
|
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
|
for us to keep track of where we are on a timeline. We're using Maniphest
|
||||||
> to track tasks...
|
to track tasks...
|
||||||
|
|
||||||
> I have poor eyesight, and use a screenreader to help me use software like
|
(NOTE) 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...
|
Phorge in my job as a developer. I'm having difficulty...
|
||||||
|
|
||||||
> We work on a large server program which has very long compile times.
|
(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
|
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
|
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, ...
|
`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
|
(NOTE) I triage manual test failures from our offshore QA team. Here's how our
|
||||||
> workflow works...
|
workflow works...
|
||||||
|
|
||||||
All of these descriptions are helpful: the provide context about what goals
|
All of these descriptions are helpful: the provide context about what goals
|
||||||
you're trying to accomplish and why.
|
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
|
Here are some examples of ways to start a problem description that probably
|
||||||
are not very good:
|
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
|
(IMPORTANT) I have a problem: there is no way to download
|
||||||
> .tar archives of repositories.
|
.tar archives of repositories.
|
||||||
|
|
||||||
> {icon times color=red} I want an RSS feed of my tokens. My root problem is
|
(IMPORTANT) I want an RSS feed of my tokens. My root problem is
|
||||||
> that I do not have an RSS feed of my tokens.
|
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.
|
(IMPORTANT) There is no way to see other users' email addresses.
|
||||||
> That is a problem.
|
That is a problem.
|
||||||
|
|
||||||
> {icon times color=red} I've used some other software that has a cool
|
(IMPORTANT) I've used some other software that has a cool
|
||||||
> feature. Phabricator should have that feature too.
|
feature. Phorge should have that feature too.
|
||||||
|
|
||||||
These problem descriptions are not helpful. They do not describe goals or
|
These problem descriptions are not helpful. They do not describe goals or
|
||||||
provide context.
|
provide context.
|
||||||
|
|
|
@ -1,19 +1,19 @@
|
||||||
@title Developer Setup
|
@title Developer Setup
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
How to configure a Phabricator development environment.
|
How to configure a Phorge development environment.
|
||||||
|
|
||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
There are some options and workflows that may be useful if you are developing
|
There are some options and workflows that may be useful if you are developing
|
||||||
or debugging Phabricator.
|
or debugging Phorge.
|
||||||
|
|
||||||
|
|
||||||
Configuration
|
Configuration
|
||||||
=============
|
=============
|
||||||
|
|
||||||
To adjust Phabricator for development:
|
To adjust Phorge for development:
|
||||||
|
|
||||||
- Enable `phabricator.developer-mode` to enable some options and show
|
- Enable `phabricator.developer-mode` to enable some options and show
|
||||||
more debugging information.
|
more debugging information.
|
||||||
|
@ -48,17 +48,17 @@ After adding, renaming, or moving classes, run `arc liberate` to rebuild
|
||||||
the class map:
|
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.
|
classes. You do not need to run this after modifying an existing class.
|
||||||
|
|
||||||
After any modifications to static resources (CSS / JS) but before sending
|
After any modifications to static resources (CSS / JS) but before sending
|
||||||
changes for review or pushing them to the remote, run `bin/celerity map`:
|
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.
|
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
|
configuration that look exactly like the primary entry (or expanding the
|
||||||
primary entry to match more domains).
|
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.
|
do not normally need any kind of special configuration.
|
||||||
|
|
||||||
You may also need to add `/etc/hosts` entries for the domains themselves.
|
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:
|
You can create test objects with the "Lipsum" utility:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/lipsum help generate
|
phorge/ $ ./bin/lipsum help generate
|
||||||
phabricator/ $ ./bin/lipsum generate ...
|
phorge/ $ ./bin/lipsum generate ...
|
||||||
```
|
```
|
||||||
|
|
||||||
Test data can make your local install feel a little more realistic. With
|
Test data can make your local install feel a little more realistic. With
|
||||||
|
|
|
@ -1,4 +1,211 @@
|
||||||
@title Contributing Feature Requests
|
@title Contributing Feature Requests
|
||||||
@group detail
|
@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}.
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title General Coding Standards
|
@title General Coding Standards
|
||||||
@group 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.
|
Arcanist, and Diviner.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
@ -60,7 +60,7 @@ And, obviously, don't do this sort of thing:
|
||||||
determine if code is fast or slow by measuring it.
|
determine if code is fast or slow by measuring it.
|
||||||
- Reject performance discussions that aren't rooted in concrete data.
|
- 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.
|
gather concrete performance data.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Handles Technical Documentation
|
@title Handles Technical Documentation
|
||||||
@group handles
|
@group developer
|
||||||
|
|
||||||
Technical overview of Handles.
|
Technical overview of Handles.
|
||||||
|
|
||||||
Overview
|
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
|
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
|
object, you can load a **handle** for that object to get more information
|
||||||
about it.
|
about it.
|
|
@ -1,12 +1,12 @@
|
||||||
@title Internationalization
|
@title Internationalization
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
Describes Phabricator translation and localization.
|
Describes Phorge translation and localization.
|
||||||
|
|
||||||
Overview
|
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.
|
are missing or in a prototype state.
|
||||||
|
|
||||||
This document describes what tools exist today, how to add new translations,
|
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.
|
locale.
|
||||||
|
|
||||||
For instructions on adding new classes, see
|
For instructions on adding new classes, see
|
||||||
@{article@phabcontrib:Adding New Classes}.
|
@{article@contrib:Adding New Classes}.
|
||||||
|
|
||||||
|
|
||||||
Adding Translations to Locale
|
Adding Translations to Locale
|
||||||
|
@ -38,7 +38,7 @@ provide translations into different locales without needing to define those
|
||||||
locales themselves.
|
locales themselves.
|
||||||
|
|
||||||
For instructions on adding new classes, see
|
For instructions on adding new classes, see
|
||||||
@{article@phabcontrib:Adding New Classes}.
|
@{article@contrib:Adding New Classes}.
|
||||||
|
|
||||||
|
|
||||||
Writing Translatable Code
|
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
|
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.
|
languages and a translation is available.
|
||||||
|
|
||||||
Using `pht()` properly so that strings are translatable can be tricky. Briefly,
|
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
|
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
|
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
|
```lang=php
|
||||||
'This will take %s hour(s).' => array(
|
'This will take %s hour(s).' => array(
|
||||||
|
@ -378,4 +378,4 @@ Next Steps
|
||||||
Continue by:
|
Continue by:
|
||||||
|
|
||||||
- adding a new locale or translation file with
|
- adding a new locale or translation file with
|
||||||
@{article@phabcontrib:Adding New Classes}.
|
@{article@contrib:Adding New Classes}.
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Javascript Coding Standards
|
@title Javascript Coding Standards
|
||||||
@group standards
|
@group standards
|
||||||
|
|
||||||
This document describes Javascript coding standards for Phabricator and Javelin.
|
This document describes Javascript coding standards for Phorge and Javelin.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
This document outlines technical and style guidelines which are followed in
|
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.
|
of these guidelines are automatically enforced by lint.
|
||||||
|
|
||||||
These guidelines are essentially identical to the Facebook guidelines, since I
|
These guidelines are essentially identical to the Facebook guidelines, since I
|
||||||
|
|
|
@ -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
|
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
|
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
|
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 =
|
= Batching Queries =
|
||||||
|
|
||||||
|
|
|
@ -1,19 +1,19 @@
|
||||||
@title Phabricator Code Layout
|
@title Phorge Code Layout
|
||||||
@group developer
|
@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.
|
application class and subdirectory organization best practices.
|
||||||
|
|
||||||
= URI Mapping =
|
= URI Mapping =
|
||||||
|
|
||||||
When a user visits a Phabricator URI, the Phabricator infrastructure parses
|
When a user visits a Phorge URI, the Phorge infrastructure parses that URI with
|
||||||
that URI with a regular expression to determine what controller class to load.
|
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
|
disk from a cache file the Arcanist phutil mapper generates. This mapping
|
||||||
should be updated whenever new classes or files are added:
|
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
|
Finally, a given controller class will map to an application which will have
|
||||||
most of its code in standardized subdirectories and classes.
|
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`.
|
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:
|
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
|
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
|
If `Derp` were (relatively) complex, one could reasonably expect to see
|
||||||
the following directory layout:
|
the following directory layout:
|
||||||
|
|
||||||
phabricator/src/applications/derp/conduit/
|
phorge/src/applications/derp/conduit/
|
||||||
phabricator/src/applications/derp/constants/
|
phorge/src/applications/derp/constants/
|
||||||
phabricator/src/applications/derp/controller/
|
phorge/src/applications/derp/controller/
|
||||||
phabricator/src/applications/derp/editor/
|
phorge/src/applications/derp/editor/
|
||||||
phabricator/src/applications/derp/exception/
|
phorge/src/applications/derp/exception/
|
||||||
phabricator/src/applications/derp/query/
|
phorge/src/applications/derp/query/
|
||||||
phabricator/src/applications/derp/replyhandler/
|
phorge/src/applications/derp/replyhandler/
|
||||||
phabricator/src/applications/derp/storage/
|
phorge/src/applications/derp/storage/
|
||||||
phabricator/src/applications/derp/view/
|
phorge/src/applications/derp/view/
|
||||||
|
|
||||||
(The following two folders are also likely to be included for JavaScript and
|
(The following two folders are also likely to be included for JavaScript and
|
||||||
CSS respectively. However, static resources are largely outside the scope of
|
CSS respectively. However, static resources are largely outside the scope of
|
||||||
this document. See @{article:Adding New CSS and JS}.)
|
this document. See @{article:Adding New CSS and JS}.)
|
||||||
|
|
||||||
phabricator/webroot/rsrc/js/application/derp/
|
phorge/webroot/rsrc/js/application/derp/
|
||||||
phabricator/webroot/rsrc/css/application/derp/
|
phorge/webroot/rsrc/css/application/derp/
|
||||||
|
|
||||||
These directories under `phabricator/src/applications/derp/` represent
|
These directories under `phorge/src/applications/derp/` represent
|
||||||
the basic set of class types from which most Phabricator applications are
|
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
|
assembled. Each would contain a class file. For `Derp`, these classes could be
|
||||||
something like:
|
something like:
|
||||||
|
|
|
@ -1,13 +1,13 @@
|
||||||
@title PHP Coding Standards
|
@title PHP Coding Standards
|
||||||
@group 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).
|
projects (like Arcanist).
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
This document outlines technical and style guidelines which are followed in
|
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.
|
Many of these guidelines are automatically enforced by lint.
|
||||||
|
|
||||||
These guidelines are essentially identical to the Facebook guidelines, since I
|
These guidelines are essentially identical to the Facebook guidelines, since I
|
||||||
|
|
|
@ -1,11 +1,11 @@
|
||||||
@title Rendering HTML
|
@title Rendering HTML
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
Rendering HTML in the Phabricator environment.
|
Rendering HTML in the Phorge environment.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
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
|
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.
|
pipeline, and the browser will treat it as plain text, not HTML.
|
||||||
|
@ -51,7 +51,7 @@ content correctly (without double-escaping):
|
||||||
array(),
|
array(),
|
||||||
$content));
|
$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
|
@{function@arcanist:phutil_tag}, but provides special handling for the
|
||||||
`sigil` and `meta` attributes.
|
`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 =
|
= 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
|
@{class@arcanist:PhutilSafeHTML} object. The easiest way to do this is to
|
||||||
return `phutil_tag()` or `javelin_tag()`:
|
return `phutil_tag()` or `javelin_tag()`:
|
||||||
|
|
||||||
|
|
|
@ -6,7 +6,7 @@ Describes how to provide reproduction steps.
|
||||||
Overview
|
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
|
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
|
will not accept reports which omit reproduction steps or have incomplete or
|
||||||
insufficient instructions.
|
insufficient instructions.
|
||||||
|
@ -15,7 +15,7 @@ This document explains what we're looking for in good reproduction steps.
|
||||||
Briefly:
|
Briefly:
|
||||||
|
|
||||||
- Reproduction steps must allow us to reproduce the problem locally on a
|
- 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.
|
- Reproduction should be as simple as possible.
|
||||||
|
|
||||||
Good reproduction steps can take time to write out clearly, simplify, and
|
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
|
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
|
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).
|
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.
|
follow these steps, or can't reproduce issues by following them.
|
||||||
|
|
||||||
Reproduction steps must be complete and self-contained, and must allow
|
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
|
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.
|
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
|
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
|
reproduce the issue, follow them yourself on a new, empty, up-to-date instance
|
||||||
of Phabricator.
|
of Phorge.
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
If you can follow your steps and reproduce the issue on a clean instance,
|
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.
|
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.
|
"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
|
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
|
issues are tremendously time consuming for us to pursue and rarely benefit
|
||||||
more than one install.
|
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
|
Next Steps
|
||||||
==========
|
==========
|
||||||
|
|
|
@ -3,7 +3,7 @@
|
||||||
|
|
||||||
As of version 5.4.0, the PHP command line interface provides a built-in web
|
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
|
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:
|
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
|
||||||
|
|
|
@ -1,11 +1,11 @@
|
||||||
@title Writing Unit Tests
|
@title Writing Unit Tests
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
Simple guide to Arcanist and Phabricator unit tests.
|
Simple guide to Arcanist and Phorge unit tests.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
document is aimed at project contributors and describes how to use it to add
|
||||||
and run tests in these projects or other libphutil libraries.
|
and run tests in these projects or other libphutil libraries.
|
||||||
|
|
||||||
|
@ -16,11 +16,11 @@ for information on customizing engines.
|
||||||
|
|
||||||
= Adding Tests =
|
= 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.
|
- Create a `__tests__/` directory in the module if it doesn't exist yet.
|
||||||
- Add classes to the `__tests__/` directory which extend from
|
- Add classes to the `__tests__/` directory which extend from
|
||||||
@{class:PhabricatorTestCase} (in Phabricator) or
|
@{class:PhabricatorTestCase} (in Phorge) or
|
||||||
@{class@arcanist:PhutilTestCase} (elsewhere).
|
@{class@arcanist:PhutilTestCase} (elsewhere).
|
||||||
- Run `arc liberate` on the library root so your classes are loadable.
|
- 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:
|
Here's a simple example test:
|
||||||
|
|
||||||
lang=php
|
lang=php
|
||||||
class PhabricatorTrivialTestCase extends PhabricatorTestCase {
|
class PhorgeTrivialTestCase extends PhabricatorTestCase {
|
||||||
|
|
||||||
private $two;
|
private $two;
|
||||||
|
|
||||||
|
@ -56,7 +56,7 @@ Here's a simple example test:
|
||||||
|
|
||||||
You can see this class at @{class:PhabricatorTrivialTestCase} and run it with:
|
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
|
PASS <1ms* testAllIsRightWithTheWorld
|
||||||
|
|
||||||
For more information on writing tests, see
|
For more information on writing tests, see
|
||||||
|
@ -64,7 +64,7 @@ For more information on writing tests, see
|
||||||
|
|
||||||
= Database Isolation =
|
= 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
|
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
|
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
|
about isolation. In general, isolation is good, but this can make certain types
|
||||||
|
|
|
@ -6,8 +6,7 @@ Guide to the Edges infrastructure.
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
Edges are a generic way of storing a relationship between two objects (like a
|
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
|
Task and its attached files).
|
||||||
framework, Phabricator Edges are substantially similar.
|
|
||||||
|
|
||||||
An edge is defined by a source PHID (the edge origin), a destination PHID
|
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,
|
(the edge destination) and an edge type (which describes the relationship,
|
||||||
|
|
|
@ -1,19 +1,19 @@
|
||||||
@title Using the Phabricator OAuth Server
|
@title Using the Phorge OAuth Server
|
||||||
@group developer
|
@group developer
|
||||||
|
|
||||||
How to use the Phabricator OAuth Server.
|
How to use the Phorge OAuth Server.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
`Authorization Code Grant` flow as described in the OAuth 2.0
|
||||||
specification:
|
specification:
|
||||||
|
|
||||||
http://tools.ietf.org/html/draft-ietf-oauth-v2-23
|
http://tools.ietf.org/html/draft-ietf-oauth-v2-23
|
||||||
|
|
||||||
This functionality can allow clients to integrate with a given
|
This functionality can allow clients to integrate with a given
|
||||||
Phabricator instance in a secure way with granular data access.
|
Phorge instance in a secure way with granular data access.
|
||||||
For example, Phabricator can be used as a central identity store for any
|
For example, Phorge can be used as a central identity store for any
|
||||||
clients that implement OAuth 2.0.
|
clients that implement OAuth 2.0.
|
||||||
|
|
||||||
= Vocabulary =
|
= Vocabulary =
|
||||||
|
@ -41,7 +41,7 @@ clients that implement OAuth 2.0.
|
||||||
|
|
||||||
= Obtaining an Authorization Code =
|
= 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:
|
following parameters:
|
||||||
|
|
||||||
- Required - **client_id** - the id of the newly registered client.
|
- 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
|
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
|
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.
|
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
|
Otherwise, the OAuth Server will redirect to the pertinent redirect_uri
|
||||||
and include the pertinent error information.
|
and include the pertinent error information.
|
||||||
|
|
||||||
= Obtaining an Access Token =
|
= 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:
|
with the following parameters:
|
||||||
|
|
||||||
- Required - **client_id** - the id of the client
|
- 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
|
Simply include a query param with the key of "access_token" and the value
|
||||||
as the earlier obtained access token. For example:
|
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
|
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
|
an error indicating as such. In these cases, the client should re-initiate
|
||||||
|
|
|
@ -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.
|
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
|
- 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
|
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?
|
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
|
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.
|
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
|
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.
|
continue. You can get help faster by doing this //before// reporting an issue.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -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.
|
|
|
@ -1,30 +1,27 @@
|
||||||
@title Phabricator Project History
|
@title Phorge Project History
|
||||||
@group lore
|
@group lore
|
||||||
|
|
||||||
A riveting tale of adventure. In this document, I refer to worldly and
|
A riveting tale of adventure.
|
||||||
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.
|
|
||||||
|
|
||||||
= In The Beginning =
|
= In The Beginning =
|
||||||
|
|
||||||
I wrote the original version of Differential in one night at a Facebook
|
Evan Priestley wrote the original version of Differential in one night at a
|
||||||
Hackathon in April or May 2007, along with Luke Shepard. I joined the company in
|
Facebook Hackathon in April or May 2007, along with Luke Shepard. He joined the
|
||||||
April and code review was already an established and mostly-mandatory part of
|
company in April and code review was already an established and mostly-mandatory
|
||||||
the culture, but it happened over email and was inefficient and hard to keep
|
part of the culture, but it happened over email and was inefficient and hard to
|
||||||
track of. I remember feeling like I was spending a lot of time waiting for code
|
keep track of. Evan remembers feeling like he was spending a lot of time waiting
|
||||||
review to happen, which was a major motivator for building the tool.
|
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
|
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
|
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
|
Trac and Basecamp called "Traccamp". Since they were writing the code review tool
|
||||||
at the height of the brief popularity Traccamp enjoyed, we integrated and called
|
at the height of the brief popularity Traccamp enjoyed, Evan and Luke integrated
|
||||||
the new tool Diffcamp even though it had no relation to Basecamp. Traccamp fell
|
and called the new tool Diffcamp even though it had no relation to Basecamp.
|
||||||
by the wayside shortly thereafter and was eventually removed.
|
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
|
However, Diffcamp didn't share its fate. Evan and Luke spent some more time
|
||||||
and got good enough to win hearts and minds over emailing diffs around and was
|
working on it and got good enough to win hearts and minds over emailing diffs
|
||||||
soon the de facto method of code review at Facebook.
|
around and was soon the de facto method of code review at Facebook.
|
||||||
|
|
||||||
= The Long Bloat =
|
= 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,
|
SVN bridging by 2010). As these patches were contributed pretty much randomly,
|
||||||
it also gained a lot of performance problems, usability issues, and bugs.
|
it also gained a lot of performance problems, usability issues, and bugs.
|
||||||
|
|
||||||
Through 2007 and 2008 I worked mostly on frontend and support infrastructure;
|
Through 2007 and 2008 Evan worked mostly on frontend and support infrastructure;
|
||||||
among other things, I wrote a static resource management system called Haste. In
|
among other things, he wrote a static resource management system called Haste.
|
||||||
2009 I worked on the Facebook Lite site, where I built the Javelin Javascript
|
In 2009 Evan worked on the Facebook Lite site, where he built the Javelin
|
||||||
library and an MVC-flavored framework called Alite.
|
Javascript library and an MVC-flavored framework called Alite.
|
||||||
|
|
||||||
But by early 2010, Diffcamp was in pretty bad shape. Two years of having random
|
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
|
features grafted onto it without real direction had left it slow and difficult
|
||||||
|
@ -49,12 +46,18 @@ problems.
|
||||||
|
|
||||||
= Differential =
|
= Differential =
|
||||||
|
|
||||||
I joined the new Dev Tools team around February 2010 and took over Diffcamp. I
|
Evan joined the new Dev Tools team around February 2010 and took over Diffcamp.
|
||||||
renamed it to Differential, moved it to a new Alite-based infrastructure with
|
He renamed it to Differential, moved it to a new Alite-based infrastructure with
|
||||||
Javelin, and started making it somewhat less terrible. I eventually wrote
|
Javelin, and started making it somewhat less terrible. He eventually wrote
|
||||||
Diffusion and built Herald to replace a very difficult-to-use predecessor. These
|
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
|
tools were less negatively received than the older versions. By December 2010,
|
||||||
started open sourcing them; Haste became //Celerity// and Alite became
|
Evan started open sourcing them; Haste became //Celerity// and Alite became
|
||||||
//Aphront//. I wrote Maniphest to track open issues with the project in January
|
//Aphront//. He wrote Maniphest to track open issues with the project in January
|
||||||
or February, left Facebook in April, and shortly after, we open sourced
|
or February, left Facebook in April, and shortly after, open sourced
|
||||||
Phabricator.
|
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.
|
||||||
|
|
|
@ -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
|
development and release management, not the use of local branches in Git or
|
||||||
queues or bookmarks in Mercurial.
|
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
|
strategies, and diverging from the recommendations in this document
|
||||||
will not impact your ability to use it for code review and source management.
|
will not impact your ability to use it for code review and source management.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
develop software. It scales well and removes the pain associated with most
|
||||||
branching strategies. This strategy is most applicable to web applications, and
|
branching strategies. This strategy is most applicable to web applications, and
|
||||||
may be less applicable to other types of software. The basics are:
|
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:
|
- Martin Fowler discusses these systems in a 2010 blog post here:
|
||||||
[[http://martinfowler.com/bliki/FeatureToggle.html |
|
[[http://martinfowler.com/bliki/FeatureToggle.html |
|
||||||
Martin Fowler's FeatureToggle]].
|
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
|
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,
|
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
|
and sometimes get away with simply not linking new features in the UI until
|
||||||
|
|
|
@ -3,12 +3,12 @@
|
||||||
|
|
||||||
Project recommendations on how to organize revision control.
|
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
|
control strategies, and diverging from the recommendations in this document
|
||||||
will not impact your ability to use it for code review and source management.
|
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
|
This is Evan's personal take on the issue and not necessarily
|
||||||
representative of the views of the Phabricator team as a whole.
|
representative of the views of the Phorge team as a whole.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
|
|
|
@ -1,19 +1,19 @@
|
||||||
@title Why does Phabricator need so many databases?
|
@title Why does Phorge need so many databases?
|
||||||
@group lore
|
@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
|
read this document). This sometimes comes as a surprise, since you might assume
|
||||||
it would only use one database.
|
it would only use one database.
|
||||||
|
|
||||||
The approach we use is designed to work at scale for huge installs with many
|
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
|
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
|
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.
|
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
|
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
|
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
|
recommend installing it on a shared host. The install documentation explicitly
|
||||||
discourages installing on shared hosts.
|
discourages installing on shared hosts.
|
||||||
|
@ -26,11 +26,11 @@ operating at scale.
|
||||||
Listing Databases
|
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:
|
databases`. It will look something like this:
|
||||||
|
|
||||||
```
|
```
|
||||||
$ /core/lib/phabricator/bin/storage databases
|
$ /core/lib/phorge/bin/storage databases
|
||||||
secure_audit
|
secure_audit
|
||||||
secure_calendar
|
secure_calendar
|
||||||
secure_chatlog
|
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
|
easier to work with a large project if you organize source files into
|
||||||
directories.
|
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
|
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
|
easier to find what you're looking for and work with the tables when they're
|
||||||
organized by application.
|
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,
|
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
|
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.
|
using shared hosts, and recommend against them in the install guide.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -121,6 +121,6 @@ version of CSS and JS into the database.
|
||||||
|
|
||||||
= Reference Implementation: Celerity =
|
= 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
|
system, which is essentially a simplified version of the //Haste// system used
|
||||||
by Facebook.
|
by Facebook.
|
||||||
|
|
|
@ -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
|
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
|
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.
|
similar to Facebook's system and was successful there.
|
||||||
|
|
|
@ -3,14 +3,14 @@
|
||||||
|
|
||||||
Project recommendations on how to structure changes.
|
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
|
control strategies, and diverging from the recommendations in this document
|
||||||
will not impact your ability to use it for code review and source management.
|
will not impact your ability to use it for code review and source management.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
This document describes a strategy for structuring changes used successfully at
|
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.
|
- 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
|
- 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
|
is for each change to have minimal complexity, line size is just a proxy that is
|
||||||
often well-correlated with complexity.
|
often well-correlated with complexity.
|
||||||
|
|
||||||
We generally follow these practices in Phabricator. The median change size for
|
We generally follow these practices in Phorge. The median change size for
|
||||||
Phabricator is 35 lines.
|
Phorge is 35 lines.
|
||||||
|
|
||||||
= Write Sensible Commit Messages =
|
= 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.
|
reasons //why// a change is happening into the commit message.
|
||||||
- Although maybe the spelling and grammar shouldn't be egregiously bad?
|
- 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
|
guidelines at your organization if you prefer, but getting the //why// into the
|
||||||
message is the most important part.
|
message is the most important part.
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Clustering Introduction
|
@title Clustering Introduction
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Guide to configuring Phabricator across multiple hosts for availability and
|
Guide to configuring Phorge across multiple hosts for availability and
|
||||||
performance.
|
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
|
adventure when deploying clusters. In the best of times, configuring a
|
||||||
cluster is complex and requires significant operations experience.
|
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
|
to improve its availability and scalability, and make disaster recovery much
|
||||||
easier.
|
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
|
single host, but greatly reduces the cost of recovering from hardware and
|
||||||
network failures.
|
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,
|
configured somewhat independently. Configuring a cluster is inherently complex,
|
||||||
and this is an advanced feature aimed at installs with large userbases and
|
and this is an advanced feature aimed at installs with large userbases and
|
||||||
experienced operations personnel who need this high degree of flexibility.
|
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
|
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.
|
in your configuration.
|
||||||
|
|
||||||
This option should contain a list of network address blocks which are considered
|
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.
|
Whitelist Security" below for discussion.
|
||||||
|
|
||||||
If you are deploying hardware in EC2, a reasonable approach is to launch a
|
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,
|
dedicated Phorge VPC, whitelist the whole VPC as a Phorge cluster,
|
||||||
and then deploy only Phabricator services into that VPC.
|
and then deploy only Phorge services into that VPC.
|
||||||
|
|
||||||
If you have additional auxiliary hosts which run builds and tests via Drydock,
|
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
|
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
|
cluster hosts as small as possible. Hosts on this list gain additional
|
||||||
capabilities, including these:
|
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
|
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
|
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
|
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
|
most important service to make redundant if your focus is on availability and
|
||||||
disaster recovery.
|
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.
|
the master and to quickly promote the replica as a replacement.
|
||||||
|
|
||||||
For details, see @{article:Cluster: Databases}.
|
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.
|
can add multiple daemon or web hosts.
|
||||||
|
|
||||||
Repository replicas are important for availability if you host repositories
|
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).
|
(instead, you should focus on making that service more available).
|
||||||
|
|
||||||
The distributed nature of Git and Mercurial tend to mean that they are
|
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.
|
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
|
multiple database hosts will effectively also deploy multiple fulltext search
|
||||||
hosts.
|
hosts.
|
||||||
|
|
||||||
|
@ -257,7 +257,7 @@ Overlaying Services
|
||||||
===================
|
===================
|
||||||
|
|
||||||
Although hosts can run a single dedicated service type, certain groups of
|
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
|
very large, so deploying a small number of hosts with multiple services is a
|
||||||
good place to start.
|
good place to start.
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Cluster: Daemons
|
@title Cluster: Daemons
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Configuring Phabricator to use multiple daemon hosts.
|
Configuring Phorge to use multiple daemon hosts.
|
||||||
|
|
||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
@ -38,7 +38,7 @@ Dedicated Daemon Hosts
|
||||||
|
|
||||||
You can launch additional daemon hosts without any special configuration.
|
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
|
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.
|
and configuration and start the daemons.
|
||||||
|
|
||||||
Normally, there is little reason to deploy dedicated daemon hosts. They can
|
Normally, there is little reason to deploy dedicated daemon hosts. They can
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Cluster: Databases
|
@title Cluster: Databases
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Configuring Phabricator to use multiple database hosts.
|
Configuring Phorge to use multiple database hosts.
|
||||||
|
|
||||||
Overview
|
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:
|
and a set of replicas. The advantages of doing this are:
|
||||||
|
|
||||||
- faster recovery from disasters by promoting a replica;
|
- 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.
|
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
|
mode and remain available, but can not fully recover without operational
|
||||||
intervention unless the master recovers on its own.
|
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
|
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.
|
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.
|
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,
|
There are no current plans to support multi-master mode or autonomous failover,
|
||||||
although this may change in the future.
|
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
|
masters. This does not provide redundancy and generally does not increase
|
||||||
resilience or resistance to data loss, but can help you scale and operate
|
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}.
|
@{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.
|
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
|
The MySQL documentation is comprehensive and walks through the steps and
|
||||||
options in good detail. You should understand MySQL replication before
|
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.
|
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
|
unsafe if you use the `STATEMENT` binlog format (the default). Instead, use
|
||||||
`MIXED` (recommended) or `ROW` as the `binlog_format`.
|
`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`
|
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.
|
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
|
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
|
consistent and suitable for loading into a replica because MySQL uses different
|
||||||
consistency mechanisms for the different storage engines.
|
consistency mechanisms for the different storage engines.
|
||||||
|
|
||||||
An approach you may want to consider to limit downtime but still produce a
|
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:
|
mode while dumping:
|
||||||
|
|
||||||
- Stop all the daemons.
|
- Stop all the daemons.
|
||||||
- Set `cluster.read-only` to `true` and deploy the new configuration. The
|
- 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`
|
- 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
|
to add the `--master-data` flag to the underlying command and include a
|
||||||
`CHANGE MASTER ...` statement in the dump.
|
`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`,
|
configure this and do not explicitly purge old logs with `PURGE BINARY LOGS`,
|
||||||
the binary logs on disk will grow unboundedly and relatively quickly.
|
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
|
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
|
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.
|
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
|
to interact with: your master and all your replicas. Each entry in the list
|
||||||
should have these keys:
|
should have these keys:
|
||||||
|
|
||||||
|
@ -105,7 +105,7 @@ should have these keys:
|
||||||
host. If omitted, the default from `mysql.user` will be used.
|
host. If omitted, the default from `mysql.user` will be used.
|
||||||
- `pass`: //Optional string.// The password to use to connect to this host.
|
- `pass`: //Optional string.// The password to use to connect to this host.
|
||||||
If omitted, the default from `mysql.pass` will be used.
|
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
|
connect to this host. You can use this to temporarily take a host out
|
||||||
of service.
|
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`,
|
The other MySQL connection configuration options (`mysql.port`, `mysql.user`,
|
||||||
`mysql.pass`) are used only to provide defaults.
|
`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.
|
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
|
may be partial or misleading, and two requests served by different servers may
|
||||||
see different views of the cluster.
|
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
|
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
|
details about the error is shown. If it succeeds, the column shows a rough
|
||||||
measurement of latency from the current webserver to the database.
|
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
|
replicating and no more than a few seconds behind master, and the master
|
||||||
should //not// be replicating from another database.
|
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
|
`REPLICATION CLIENT` privilege (or the `SUPER` privilege) so it can run the
|
||||||
`SHOW SLAVE STATUS` command. The `REPLICATION CLIENT` privilege only enables
|
`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
|
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
|
appear that their data has been lost, even if it is safe and just hasn't
|
||||||
replicated yet.
|
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
|
sometimes sending traffic to a delayed replica is the best available option
|
||||||
(for example, if the master can not be reached).
|
(for example, if the master can not be reached).
|
||||||
|
|
||||||
**Health**: This column shows the result of recent health checks against the
|
**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
|
as unhealthy and stop sending traffic to it until several checks in a row
|
||||||
later succeed.
|
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
|
database. Do this with great ceremony, making a cool explosion sound as you
|
||||||
run the `mysqld stop` command.
|
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
|
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
|
degrade further into a longer-term read-only mode. For details on how this
|
||||||
works internally, see "Unreachable Masters" below.
|
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.
|
should recognize that the master is healthy again and recover fully.
|
||||||
|
|
||||||
Throughout this process, the {nav Database Servers} console will show a
|
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.
|
request. You can use it to monitor state.
|
||||||
|
|
||||||
You can perform a more narrow test by enabling `cluster.read-only` in
|
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.
|
without turning off any databases.
|
||||||
|
|
||||||
You can use this mode to understand which capabilities will and will not be
|
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.
|
accessible.
|
||||||
|
|
||||||
See the next section, "Degradation to Read Only Mode", for more details about
|
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
|
If you run custom code or extensions, they may not accommodate read-only mode
|
||||||
properly. You should specifically test that they function correctly in
|
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
|
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 turn it on explicitly;
|
||||||
- you configure cluster mode, but don't set up any masters;
|
- you configure cluster mode, but don't set up any masters;
|
||||||
- the master can not be reached while handling a request; or
|
- the master can not be reached while handling a request; or
|
||||||
- recent attempts to connect to the master have consistently failed.
|
- 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
|
browse and clone repositories, but they can not edit, update, or push new
|
||||||
changes. For example, users can still read disaster recovery information on
|
changes. For example, users can still read disaster recovery information on
|
||||||
the wiki or emergency contact information on user profiles.
|
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 test that the mode works like you expect it to;
|
||||||
- to make sure that information you need will be available;
|
- to make sure that information you need will be available;
|
||||||
- to prevent new writes while performing database maintenance; or
|
- 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`
|
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
|
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
|
be more convenient than turning it on explicitly during the course of
|
||||||
operations work.
|
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
|
read-only mode automatically. See "Unreachable Masters" below for details on
|
||||||
how this process works.
|
how this process works.
|
||||||
|
|
||||||
|
@ -258,12 +258,12 @@ the new master. See the next section, "Promoting a Replica", for details.
|
||||||
Promoting a Replica
|
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.
|
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.
|
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,
|
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
|
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.
|
master quickly, you can promote a replica to become the new master instead.
|
||||||
|
@ -295,16 +295,16 @@ redundancy.
|
||||||
Unreachable Masters
|
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.
|
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
|
briefly in response to a single connection failure, or more permanently in
|
||||||
response to a series of connection failures.
|
response to a series of connection failures.
|
||||||
|
|
||||||
In the first case, if a request needs to connect to the master but is not able
|
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
|
to, Phorge will temporarily degrade into read-only mode for the remainder
|
||||||
of that request. The alternative is to fail abruptly, but Phabricator can
|
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
|
sometimes degrade successfully and still respond to the user's request, so it
|
||||||
makes an effort to finish serving the request from replicas.
|
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
|
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
|
interruptions in service (a few seconds), like a server being restarted, a
|
||||||
network link becoming temporarily unavailable, or brief periods of load-related
|
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).
|
(on the next request once service is restored).
|
||||||
|
|
||||||
This mode can be slow for users (they need to wait on connection attempts to
|
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
|
the master which fail) and does not reduce load on the master (requests still
|
||||||
attempt to connect to it).
|
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
|
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
|
of time. This mechanism is very similar to the health checks that most HTTP
|
||||||
load balancers perform against web servers.
|
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.
|
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
|
This improves performance during a service interruption and reduces load on the
|
||||||
master, which may help it recover from load problems.
|
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.
|
how many have succeeded.
|
||||||
|
|
||||||
Health checks run every 3 seconds, and 5 checks in a row must fail or succeed
|
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
|
generally take about 15 seconds for a database to change state after it goes
|
||||||
down or comes up.
|
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
|
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.
|
until it recovers.
|
||||||
|
|
||||||
This mode only attempts to connect to the unhealthy database once every few
|
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
|
(users rarely need to wait for bad connections to fail or time out) and the
|
||||||
database will receive less load.
|
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.
|
healthy again and continue sending traffic to it.
|
||||||
|
|
||||||
Health checks are tracked individually for each web server, so some web servers
|
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
|
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
|
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
|
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.
|
send traffic to it, and does not need to know about it.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -6,7 +6,7 @@ Guide to configuring hosts to act as cluster devices.
|
||||||
Cluster Context
|
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
|
multiple hosts in a cluster configuration. This is an advanced feature. For
|
||||||
more information on clustering, see @{article:Clustering Introduction}.
|
more information on clustering, see @{article:Clustering Introduction}.
|
||||||
|
|
||||||
|
@ -38,7 +38,7 @@ Today, this is primarily necessary when configuring repository clusters.
|
||||||
Using Almanac
|
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
|
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.
|
UI. If you are not familiar with it, see @{article:Almanac User Guide} first.
|
||||||
This document assumes you are familiar with Almanac concepts.
|
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.
|
- Create an Almanac device record for each device.
|
||||||
- Generate, add, and trust SSH keys if necessary.
|
- 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.
|
- Use `bin/almanac register` from the host to register it as a device.
|
||||||
|
|
||||||
See below for guidance on each of these steps.
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
{nav Almanac} application and create a **device** record. For guidance on this
|
||||||
application, see @{article:Almanac User Guide}.
|
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
|
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:
|
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`
|
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
|
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.
|
port.
|
||||||
|
|
||||||
If you're using **unique** SSH keys for each device, continue to the next step.
|
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:
|
each key as trusted:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/almanac trust-key --id <key-id-1>
|
phorge/ $ ./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-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`:
|
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.
|
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
|
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
|
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
|
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
|
NOTE: Do not start the daemons on the new devices yet. They won't work properly
|
||||||
until you've finished configuring things.
|
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.
|
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.
|
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
|
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
|
that directory. The helper script just catches potential mistakes and makes
|
||||||
sure the process is completed correctly.
|
sure the process is completed correctly.
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Cluster: Notifications
|
@title Cluster: Notifications
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Configuring Phabricator to use multiple notification servers.
|
Configuring Phorge to use multiple notification servers.
|
||||||
|
|
||||||
Overview
|
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
|
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.
|
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.
|
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
|
To configure clustering on the client side, add every service you run to
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Cluster: Partitioning and Advanced Configuration
|
@title Cluster: Partitioning and Advanced Configuration
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Guide to partitioning Phabricator applications across multiple database hosts.
|
Guide to partitioning Phorge applications across multiple database hosts.
|
||||||
|
|
||||||
Overview
|
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
|
example, you can move an application like Files or Maniphest to a dedicated
|
||||||
database host.
|
database host.
|
||||||
|
|
||||||
|
@ -18,7 +18,7 @@ The advantages of doing this are:
|
||||||
operating the cluster easier.
|
operating the cluster easier.
|
||||||
|
|
||||||
This configuration is complex, and very few installs will benefit from pursuing
|
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.
|
even for large organizations.
|
||||||
|
|
||||||
Partitioning generally does not do much to increase resilience or make it
|
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
|
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
|
applications (like Maniphest) to a new master database host. This is possible
|
||||||
because Phabricator stores data for each application in its own logical
|
because Phorge stores data for each application in its own logical
|
||||||
database (like `phabricator_maniphest`) and performs no joins between databases.
|
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
|
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
|
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",
|
"host": "db001.corporation.com",
|
||||||
"role": "master",
|
"role": "master",
|
||||||
"user": "phabricator",
|
"user": "phorge",
|
||||||
"pass": "hunter2!trustno1",
|
"pass": "hunter2!trustno1",
|
||||||
"port": 3306,
|
"port": 3306,
|
||||||
"partition": [
|
"partition": [
|
||||||
|
@ -88,7 +88,7 @@ each `replica` database follows. Here's a simple example config:
|
||||||
{
|
{
|
||||||
"host": "db002.corporation.com",
|
"host": "db002.corporation.com",
|
||||||
"role": "replica",
|
"role": "replica",
|
||||||
"user": "phabricator",
|
"user": "phorge",
|
||||||
"pass": "hunter2!trustno1",
|
"pass": "hunter2!trustno1",
|
||||||
"port": 3306,
|
"port": 3306,
|
||||||
"master": "db001.corporation.com:3306"
|
"master": "db001.corporation.com:3306"
|
||||||
|
@ -96,7 +96,7 @@ each `replica` database follows. Here's a simple example config:
|
||||||
{
|
{
|
||||||
"host": "db003.corporation.com",
|
"host": "db003.corporation.com",
|
||||||
"role": "master",
|
"role": "master",
|
||||||
"user": "phabricator",
|
"user": "phorge",
|
||||||
"pass": "hunter2!trustno1",
|
"pass": "hunter2!trustno1",
|
||||||
"port": 3306,
|
"port": 3306,
|
||||||
"partition": [
|
"partition": [
|
||||||
|
@ -108,7 +108,7 @@ each `replica` database follows. Here's a simple example config:
|
||||||
{
|
{
|
||||||
"host": "db004.corporation.com",
|
"host": "db004.corporation.com",
|
||||||
"role": "replica",
|
"role": "replica",
|
||||||
"user": "phabricator",
|
"user": "phorge",
|
||||||
"pass": "hunter2!trustno1",
|
"pass": "hunter2!trustno1",
|
||||||
"port": 3306,
|
"port": 3306,
|
||||||
"master": "db003.corporation.com:3306"
|
"master": "db003.corporation.com:3306"
|
||||||
|
@ -137,7 +137,7 @@ configuration.
|
||||||
To commit the configuration, run this command:
|
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
|
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"
|
- Add the new database to `cluster.databases`, but keep its "partition"
|
||||||
configuration empty (just an empty list). If this is the first time you
|
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
|
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.
|
any traffic to it yet.
|
||||||
- Run `bin/storage partition`.
|
- Run `bin/storage partition`.
|
||||||
- Run `bin/storage upgrade` to initialize the schemata on the new hosts.
|
- 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
|
in read-only mode, or shutting down the webserver and daemons, or telling
|
||||||
everyone not to touch anything.
|
everyone not to touch anything.
|
||||||
- Dump the data from the application databases on the old master.
|
- Dump the data from the application databases on the old master.
|
||||||
- Load the data into the application databases on the new 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.
|
have moved.
|
||||||
- Run `bin/storage partition`.
|
- Run `bin/storage partition`.
|
||||||
- While still in read-only mode, check that all the data appears to be
|
- 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
|
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
|
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
|
management commands, they generally affect all masters (if they do not, they
|
||||||
will prompt you to be more specific).
|
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
|
of which patches have been applied to that particular master so that
|
||||||
`bin/storage upgrade` can upgrade hosts correctly.
|
`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
|
meaningful differences in runtime behavior if two applications are on the same
|
||||||
physical host or different physical hosts.
|
physical host or different physical hosts.
|
||||||
|
|
||||||
|
@ -212,7 +212,7 @@ only one master.
|
||||||
|
|
||||||
`persistent` //(bool)// Enables persistent connections. Defaults to off.
|
`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
|
connections open between web requests and reuse them when serving subsequent
|
||||||
requests.
|
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.
|
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
|
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
|
connections, the connections it does make will be longer-lived. Raising this
|
||||||
setting will increase MySQL memory requirements and may run into other limits,
|
setting will increase MySQL memory requirements and may run into other limits,
|
||||||
like `open_files_limit`, which may also need to be raised.
|
like `open_files_limit`, which may also need to be raised.
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Cluster: Repositories
|
@title Cluster: Repositories
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Configuring Phabricator to use multiple repository hosts.
|
Configuring Phorge to use multiple repository hosts.
|
||||||
|
|
||||||
Overview
|
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
|
configured so that each host is readable and writable. The advantages of doing
|
||||||
this are:
|
this are:
|
||||||
|
|
||||||
|
@ -22,11 +22,11 @@ This configuration is not currently supported with Subversion or Mercurial.
|
||||||
How Reads and Writes Work
|
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
|
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.
|
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.
|
it when the repository is mutated.
|
||||||
|
|
||||||
Before responding to a read, replicas make sure their version of the repository
|
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
|
||||||
================
|
================
|
||||||
|
|
||||||
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`.
|
including a webserver. They must also run a properly configured `sshd`.
|
||||||
|
|
||||||
If you are converting existing hosts into cluster hosts, you may need to
|
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
|
- First, register at least one device according to the device clustering
|
||||||
instructions.
|
instructions.
|
||||||
- Create a new service of type **Phabricator Cluster: Repository** in
|
- Create a new service of type **Phorge Cluster: Repository** in
|
||||||
Almanac.
|
Almanac.
|
||||||
- Bind this service to all the interfaces on the device or devices.
|
- Bind this service to all the interfaces on the device or devices.
|
||||||
- For each binding, add a `protocol` key with one of these values:
|
- 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
|
$ ./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.
|
not move any data or make any complex structural changes.
|
||||||
|
|
||||||
When Phabricator needs information about a non-clustered repository, it just
|
When Phorge needs information about a non-clustered repository, it just
|
||||||
runs a command like `git log` directly on disk. When Phabricator needs
|
runs a command like `git log` directly on disk. When Phorge needs
|
||||||
information about a clustered repository, it instead makes a service call to
|
information about a clustered repository, it instead makes a service call to
|
||||||
another server, asking that server to run `git log` instead.
|
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
|
For instructions on configuring and registering devices, see
|
||||||
@{article:Cluster: Devices}.
|
@{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
|
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.
|
synchronize it.
|
||||||
|
|
||||||
If you have a large amount of repository data, you may want to help this
|
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
|
This screen shows all the configured devices which are hosting the repository
|
||||||
and the available version on that device.
|
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
|
an internal version number for the repository. This column shows which version
|
||||||
is on disk on the corresponding device.
|
is on disk on the corresponding device.
|
||||||
|
|
||||||
|
@ -335,9 +335,9 @@ There are three major cluster failure modes:
|
||||||
are reachable.
|
are reachable.
|
||||||
- **Ambiguous Leaders**: The internal state of the repository is unclear.
|
- **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
|
(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
|
errs on the side of caution and requires decisions which may result in data
|
||||||
loss to be confirmed by a human.
|
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
|
- During or immediately after the write, lightning strikes the server
|
||||||
and destroys it.
|
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
|
the global state (stored in a database) atomically, so there is necessarily a
|
||||||
narrow window between committing these two different states when some tragedy
|
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
|
can befall a server, leaving the global and local views of the repository state
|
||||||
possibly divergent.
|
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
|
are not permitted until the failure is investigated and resolved. When a
|
||||||
repository is frozen in this way it remains readable.
|
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:
|
command:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/repository thaw <repository> --demote <device>
|
phorge/ $ ./bin/repository thaw <repository> --demote <device>
|
||||||
```
|
```
|
||||||
|
|
||||||
{icon exclamation-triangle, color="yellow"} Any committed but unacknowledged
|
{icon exclamation-triangle, color="yellow"} Any committed but unacknowledged
|
||||||
|
@ -411,7 +411,7 @@ this:
|
||||||
and destroys it.
|
and destroys it.
|
||||||
|
|
||||||
Here, all of the "leader" devices with the most up-to-date copy of the
|
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
|
serve requests because it can not serve reads consistently and can not accept
|
||||||
new writes without data loss.
|
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
|
present on the leaders but not present on the followers by examining the
|
||||||
push logs.
|
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:
|
that it can forget about the leaders by doing this:
|
||||||
|
|
||||||
- Disable the service bindings to all of the leader devices so they are no
|
- 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:
|
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
|
{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.**
|
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
|
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
|
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
|
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.
|
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
|
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
|
have more, and if it chooses a leader arbitrarily it may destroy some data
|
||||||
which you would prefer to retain.
|
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
|
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.
|
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:
|
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
|
{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.
|
will propagate to the replicas.
|
||||||
|
|
||||||
You may be able to manually restore the branches by using tools like the
|
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
|
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
|
data to be lost permanently, especially if you don't notice the problem for
|
||||||
some time.
|
some time.
|
||||||
|
@ -543,8 +543,8 @@ changes may either encounter conflicts or encounter problems with change
|
||||||
propagation.
|
propagation.
|
||||||
|
|
||||||
You can encounter conflicts because directly modifying the working copy on disk
|
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
|
won't prevent users or Phorge itself from performing writes to the same
|
||||||
working copy at the same time. Phabricator does not compromise the lower-level
|
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
|
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
|
causes any significant problems in practice -- but doesn't make things any
|
||||||
simpler or easier.
|
simpler or easier.
|
||||||
|
|
|
@ -4,10 +4,10 @@
|
||||||
Overview
|
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.
|
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.
|
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.
|
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.
|
in order until it is able to execute the query successfully.
|
||||||
|
|
||||||
These options are supported by all service types:
|
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:
|
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.
|
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:
|
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
|
This initiates an exhaustive rebuild of the document indexes. To get a more
|
||||||
detailed list of indexing options available, run:
|
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
|
This is a more advanced example which shows a configuration with multiple
|
||||||
different services in different roles. In this example:
|
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.
|
service.
|
||||||
- An Elasticsearch 5 service is online, but only receiving writes.
|
- An Elasticsearch 5 service is online, but only receiving writes.
|
||||||
- The MySQL service is serving as a backup if Elasticsearch fails.
|
- The MySQL service is serving as a backup if Elasticsearch fails.
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Cluster: SSH Servers
|
@title Cluster: SSH Servers
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Configuring Phabricator to use multiple SSH servers.
|
Configuring Phorge to use multiple SSH servers.
|
||||||
|
|
||||||
Overview
|
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:
|
are:
|
||||||
|
|
||||||
- you can completely survive the loss of multiple SSH hosts.
|
- 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
|
After configuring repositories in cluster mode, you can add more web hosts
|
||||||
at any time.
|
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
|
register the host as a cluster device if it is not already registered (for
|
||||||
help, see @{article:Cluster: Devices}.)
|
help, see @{article:Cluster: Devices}.)
|
||||||
|
|
||||||
Once the host is registered, start the SSH server, and then add the host to the
|
Once the host is registered, start the SSH server, and then add the host to the
|
||||||
SSH load balancer pool.
|
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.
|
production freely.
|
||||||
|
|
||||||
You may also want to run web services on these hosts, since the service is very
|
You may also want to run web services on these hosts, since the service is very
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Cluster: Web Servers
|
@title Cluster: Web Servers
|
||||||
@group cluster
|
@group cluster
|
||||||
|
|
||||||
Configuring Phabricator to use multiple web servers.
|
Configuring Phorge to use multiple web servers.
|
||||||
|
|
||||||
Overview
|
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:
|
are:
|
||||||
|
|
||||||
- you can completely survive the loss of multiple web hosts; and
|
- 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
|
After configuring repositories in cluster mode, you can add more web hosts
|
||||||
at any time.
|
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
|
register the host as a cluster device if it is not already registered (for
|
||||||
help, see @{article:Cluster: Devices}.)
|
help, see @{article:Cluster: Devices}.)
|
||||||
|
|
||||||
Once the host is registered, start the web server, and then add the host to the
|
Once the host is registered, start the web server, and then add the host to the
|
||||||
load balancer pool.
|
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.
|
production freely.
|
||||||
|
|
||||||
You may also want to run SSH services on these hosts, since the service is very
|
You may also want to run SSH services on these hosts, since the service is very
|
||||||
|
|
|
@ -1,21 +1,21 @@
|
||||||
@title Configuration User Guide: Advanced Configuration
|
@title Configuration User Guide: Advanced Configuration
|
||||||
@group config
|
@group config
|
||||||
|
|
||||||
Configuring Phabricator for multiple environments.
|
Configuring Phorge for multiple environments.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
the configuration stack and how to set up advanced configuration sources, which
|
||||||
may be useful for deployments with multiple environments (e.g., development and
|
may be useful for deployments with multiple environments (e.g., development and
|
||||||
production).
|
production).
|
||||||
|
|
||||||
This is a complicated topic for advanced users. You do not need to understand
|
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 =
|
= Configuration Sources =
|
||||||
|
|
||||||
Phabricator supports the following configuration sources, from highest priority
|
Phorge supports the following configuration sources, from highest priority
|
||||||
to lowest priority:
|
to lowest priority:
|
||||||
|
|
||||||
- **Database**: Values are stored in the database and edited from the web UI
|
- **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
|
- **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
|
to use is selected by writing to `conf/local/ENVIRONMENT`, or setting the
|
||||||
`PHABRICATOR_ENV` configuration variable. See below for more information.
|
`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
|
be edited. They have the lowest priority, and all other settings override
|
||||||
them.
|
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
|
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
|
MySQL username, password, and hostname), then use the web interface to further
|
||||||
configure Phabricator.
|
configure Phorge.
|
||||||
|
|
||||||
= Configuration Files =
|
= Configuration Files =
|
||||||
|
|
||||||
|
@ -52,7 +52,7 @@ examples below.
|
||||||
First, write an `exampleconfig.conf.php` file here (rename it according to the
|
First, write an `exampleconfig.conf.php` file here (rename it according to the
|
||||||
name you chose):
|
name you chose):
|
||||||
|
|
||||||
phabricator/conf/custom/exampleconfig.conf.php
|
phorge/conf/custom/exampleconfig.conf.php
|
||||||
|
|
||||||
Its contents should look like this:
|
Its contents should look like this:
|
||||||
|
|
||||||
|
@ -77,14 +77,14 @@ a config like this:
|
||||||
== Selecting a Configuration File ==
|
== Selecting a Configuration File ==
|
||||||
|
|
||||||
To select a configuration file, write the name of the file (relative to
|
To select a configuration file, write the name of the file (relative to
|
||||||
`phabricator/conf/`) to `phabricator/conf/local/ENVIRONMENT`. For example, to
|
`phorge/conf/`) to `phorge/conf/local/ENVIRONMENT`. For example, to
|
||||||
select `phabricator/conf/custom/exampleconfig.conf.php`, you would write
|
select `phorge/conf/custom/exampleconfig.conf.php`, you would write
|
||||||
"custom/exampleconfig" to `phabricator/conf/local/ENVIRONMENT`:
|
"custom/exampleconfig" to `phorge/conf/local/ENVIRONMENT`:
|
||||||
|
|
||||||
phabricator/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
|
phorge/ $ echo custom/exampleconfig > conf/local/ENVIRONMENT
|
||||||
phabricator/ $ cat conf/local/ENVIRONMENT
|
phorge/ $ cat conf/local/ENVIRONMENT
|
||||||
custom/exampleconfig
|
custom/exampleconfig
|
||||||
phabricator/ $
|
phorge/ $
|
||||||
|
|
||||||
You can also set the environmental variable `PHABRICATOR_ENV`. This is more
|
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
|
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
|
After creating and selecting a configuration file, restart Phorge (for
|
||||||
help, see @{article:Restarting Phabricator}). Any configuration you set should
|
help, see @{article:Restarting Phorge}). Any configuration you set should
|
||||||
take effect immediately, and your file should be visible in the Config
|
take effect immediately, and your file should be visible in the Config
|
||||||
application when examining configuration.
|
application when examining configuration.
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Configuration Guide
|
@title Configuration Guide
|
||||||
@group config
|
@group config
|
||||||
|
|
||||||
This document contains basic configuration instructions for Phabricator.
|
This document contains basic configuration instructions for Phorge.
|
||||||
|
|
||||||
= Prerequisites =
|
= Prerequisites =
|
||||||
|
|
||||||
|
@ -11,7 +11,7 @@ If you haven't, see @{article:Installation Guide}.
|
||||||
The next steps are:
|
The next steps are:
|
||||||
|
|
||||||
- Configure your webserver (Apache, nginx, or lighttpd).
|
- Configure your webserver (Apache, nginx, or lighttpd).
|
||||||
- Access Phabricator with your browser.
|
- Access Phorge with your browser.
|
||||||
- Follow the instructions to complete setup.
|
- Follow the instructions to complete setup.
|
||||||
|
|
||||||
= Webserver: Configuring Apache =
|
= 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.
|
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
|
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
|
installing on. You can either install Phorge on a subdomain (like
|
||||||
phabricator.example.com) or an entire domain, but you can not install it in
|
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
|
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
|
going to use and make sure Apache serves you something to verify that DNS
|
||||||
is correctly configured.
|
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
|
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.
|
'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:
|
this:
|
||||||
|
|
||||||
name=httpd.conf
|
name=httpd.conf
|
||||||
<VirtualHost *>
|
<VirtualHost *>
|
||||||
# Change this to the domain which points to your host.
|
# 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
|
# Change this to the path where you put 'phorge' when you checked it
|
||||||
# out from GitHub when following the Installation Guide.
|
# out from the upstream when following the Installation Guide.
|
||||||
#
|
#
|
||||||
# Make sure you include "/webroot" at the end!
|
# Make sure you include "/webroot" at the end!
|
||||||
DocumentRoot /path/to/phabricator/webroot
|
DocumentRoot /path/to/phorge/webroot
|
||||||
|
|
||||||
RewriteEngine on
|
RewriteEngine on
|
||||||
RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
|
RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
|
||||||
</VirtualHost>
|
</VirtualHost>
|
||||||
|
|
||||||
If Apache isn't currently configured to serve documents out of the directory
|
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.
|
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`.)
|
(If you don't know, you can usually figure this out by running `httpd -v`.)
|
||||||
For Apache versions older than 2.4, use this:
|
For Apache versions older than 2.4, use this:
|
||||||
|
|
||||||
name="Apache Older Than 2.4"
|
name="Apache Older Than 2.4"
|
||||||
<Directory "/path/to/phabricator/webroot">
|
<Directory "/path/to/phorge/webroot">
|
||||||
Order allow,deny
|
Order allow,deny
|
||||||
Allow from all
|
Allow from all
|
||||||
</Directory>
|
</Directory>
|
||||||
|
@ -66,7 +66,7 @@ For Apache versions older than 2.4, use this:
|
||||||
For Apache versions 2.4 and newer, use this:
|
For Apache versions 2.4 and newer, use this:
|
||||||
|
|
||||||
name="Apache 2.4 and Newer"
|
name="Apache 2.4 and Newer"
|
||||||
<Directory "/path/to/phabricator/webroot">
|
<Directory "/path/to/phorge/webroot">
|
||||||
Require all granted
|
Require all granted
|
||||||
</Directory>
|
</Directory>
|
||||||
|
|
||||||
|
@ -81,8 +81,8 @@ For nginx, use a configuration like this:
|
||||||
|
|
||||||
name=nginx.conf
|
name=nginx.conf
|
||||||
server {
|
server {
|
||||||
server_name phabricator.example.com;
|
server_name phorge.example.com;
|
||||||
root /path/to/phabricator/webroot;
|
root /path/to/phorge/webroot;
|
||||||
|
|
||||||
location / {
|
location / {
|
||||||
index index.php;
|
index index.php;
|
||||||
|
@ -121,8 +121,8 @@ up to their sections.
|
||||||
|
|
||||||
For lighttpd, add a section like this to your lighttpd.conf:
|
For lighttpd, add a section like this to your lighttpd.conf:
|
||||||
|
|
||||||
$HTTP["host"] =~ "phabricator(\.example\.com)?" {
|
$HTTP["host"] =~ "phorge(\.example\.com)?" {
|
||||||
server.document-root = "/path/to/phabricator/webroot"
|
server.document-root = "/path/to/phorge/webroot"
|
||||||
url.rewrite-once = (
|
url.rewrite-once = (
|
||||||
# This simulates QSA ("query string append") mode in apache
|
# This simulates QSA ("query string append") mode in apache
|
||||||
"^(/[^?]*)\?(.*)" => "/index.php?__path__=$1&$2",
|
"^(/[^?]*)\?(.*)" => "/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
|
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
|
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
|
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
|
may have to override the default user so the schema changes can be applied with
|
||||||
root or some other admin user:
|
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
|
You can avoid the prompt the script issues by passing the `--force` flag (for
|
||||||
example, if you are scripting the upgrade process).
|
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.
|
new updates.
|
||||||
|
|
||||||
= Next Steps =
|
= Next Steps =
|
||||||
|
@ -200,7 +200,7 @@ Continue by:
|
||||||
@{article:Configuring a Preamble Script}; or
|
@{article:Configuring a Preamble Script}; or
|
||||||
- configuring where uploaded files and attachments will be stored with
|
- configuring where uploaded files and attachments will be stored with
|
||||||
@{article:Configuring File Storage}; or
|
@{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
|
@{article:Configuring Outbound Email}; or
|
||||||
- configuring inbound mail with @{article:Configuring Inbound Email}; or
|
- configuring inbound mail with @{article:Configuring Inbound Email}; or
|
||||||
- importing repositories with @{article:Diffusion User Guide}; or
|
- importing repositories with @{article:Diffusion User Guide}; or
|
||||||
|
@ -209,4 +209,4 @@ Continue by:
|
||||||
@{article:Notifications User Guide: Setup and Configuration}; or
|
@{article:Notifications User Guide: Setup and Configuration}; or
|
||||||
- configuring backups with
|
- configuring backups with
|
||||||
@{article:Configuring Backups and Performing Migrations}; or
|
@{article:Configuring Backups and Performing Migrations}; or
|
||||||
- contributing to Phabricator with @{article:Contributor Introduction}.
|
- contributing to Phorge with @{article:Contributor Introduction}.
|
||||||
|
|
|
@ -24,7 +24,7 @@ Locked Configuration
|
||||||
can edit it from the CLI instead, with `bin/config`:
|
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
|
Some configuration options take complicated values which can be difficult
|
||||||
|
@ -42,7 +42,7 @@ file:
|
||||||
Then, set it with `--stdin` like this:
|
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
|
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
|
**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.
|
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
|
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
|
**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.
|
greater access.
|
||||||
|
|
||||||
For example, an attacker who could modify `cluster.mailers` (and other
|
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
|
through an evil server they controlled, then trigger password resets on other
|
||||||
user accounts to compromise them.
|
user accounts to compromise them.
|
||||||
|
|
||||||
|
@ -105,8 +105,8 @@ administrator accounts) from reading them.
|
||||||
You can review (and edit) hidden configuration from the CLI:
|
You can review (and edit) hidden configuration from the CLI:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/config get <key>
|
phorge/ $ ./bin/config get <key>
|
||||||
phabricator/ $ ./bin/config set <key> <value>
|
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
|
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:
|
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
|
- In the past, you or some other administrator used the web UI to set a
|
||||||
value. This value was written to the database.
|
value. This value was written to the database.
|
||||||
- In a later version of the software, the value became locked.
|
- 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
|
exist. Locked configuration was introduced later, and then configuration options
|
||||||
were gradually locked for a long time after that.
|
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
|
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
|
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
|
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
|
At time of writing (February 2019), Phorge currently respects these old
|
||||||
database values. However, some future version of Phabricator will refuse to
|
database values. However, some future version of Phorge will refuse to
|
||||||
read locked configuration from the database, because this improves security if
|
read locked configuration from the database, because this improves security if
|
||||||
an attacker manages to find a way to bypass restrictions on editing locked
|
an attacker manages to find a way to bypass restrictions on editing locked
|
||||||
configuration from the web UI.
|
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:
|
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:
|
...into local configuration:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/config set <key> <value>
|
phorge/ $ ./bin/config set <key> <value>
|
||||||
```
|
```
|
||||||
|
|
||||||
...and then removing the database 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
|
See @{Configuration User Guide: Advanced Configuration} for some more detailed
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Configuring Accounts and Registration
|
@title Configuring Accounts and Registration
|
||||||
@group config
|
@group config
|
||||||
|
|
||||||
Describes how to configure user access to Phabricator.
|
Describes how to configure user access to Phorge.
|
||||||
|
|
||||||
Overview
|
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
|
systems to configure who can register for and access your install, and how users
|
||||||
with existing accounts can login.
|
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.
|
- **LDAP:** Users use LDAP credentials to log in or register.
|
||||||
- **OAuth:** Users use accounts on a supported OAuth2 provider (like
|
- **OAuth:** Users use accounts on a supported OAuth2 provider (like
|
||||||
GitHub, Facebook, or Google) to log in or register.
|
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
|
can be extended with custom providers. See the "Auth" application for
|
||||||
a list of available providers.
|
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.
|
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,
|
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).
|
can use it to register new accounts (assuming you enable these options).
|
||||||
|
|
||||||
|
|
||||||
Recovering Inaccessible Accounts
|
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"
|
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
|
action from the login screen to email yourself a login link and regain access
|
||||||
to your account.
|
to your account.
|
||||||
|
@ -43,7 +43,7 @@ can use the `bin/auth` script to recover access to an account. To recover
|
||||||
access, run:
|
access, run:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/auth recover <username>
|
phorge/ $ ./bin/auth recover <username>
|
||||||
```
|
```
|
||||||
|
|
||||||
...where `<username>` is the account username you want to recover access
|
...where `<username>` is the account username you want to recover access
|
||||||
|
|
|
@ -1,21 +1,21 @@
|
||||||
@title Configuring Backups and Performing Migrations
|
@title Configuring Backups and Performing Migrations
|
||||||
@group config
|
@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
|
Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
Phabricator does not currently have a comprehensive backup system, but creating
|
Phorge does not currently have a comprehensive backup system, but creating
|
||||||
backups is not particularly difficult and Phabricator does have a few basic
|
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
|
tools which can help you set up a reasonable process. In particular, the things
|
||||||
which needs to be backed up are:
|
which needs to be backed up are:
|
||||||
|
|
||||||
- the MySQL databases;
|
- the MySQL databases;
|
||||||
- hosted repositories;
|
- hosted repositories;
|
||||||
- uploaded files; and
|
- uploaded files; and
|
||||||
- your Phabricator configuration files.
|
- your Phorge configuration files.
|
||||||
|
|
||||||
This document discusses approaches for backing up this data.
|
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
|
will just backup the old machine and then restore the data onto the new
|
||||||
machine.
|
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
|
flushed properly. For complete instructions, see
|
||||||
@{article:Restarting Phabricator}.
|
@{article:Restarting Phorge}.
|
||||||
|
|
||||||
|
|
||||||
Backup: MySQL Databases
|
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
|
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`,
|
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
|
Since most of this data is compressible, it may be helpful to run it through
|
||||||
gzip prior to storage. For example:
|
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
|
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.
|
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
|
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
|
`bin/repository list-paths` to show the local paths on disk for each
|
||||||
repository. To back them up, copy them elsewhere.
|
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
|
**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
|
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
|
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
|
**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
|
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).
|
setting).
|
||||||
|
|
||||||
For more information about configuring how files are stored, see
|
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
|
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
|
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
|
whatever backup process you already have in place for repositories. Just copying
|
||||||
them somewhere will work fine too, of course.
|
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:
|
creates:
|
||||||
|
|
||||||
phabricator/conf/local/local.json
|
phorge/conf/local/local.json
|
||||||
|
|
||||||
This file contains all of the configuration settings that have been adjusted
|
This file contains all of the configuration settings that have been adjusted
|
||||||
by using `bin/config set <key> <value>`.
|
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
|
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
|
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
|
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:
|
has the backups can:
|
||||||
|
|
||||||
- read data that policies do not permit them to see;
|
- 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.
|
- 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
|
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.
|
should also restrict access to the backups.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -6,14 +6,14 @@ Setup guide for configuring encryption.
|
||||||
Overview
|
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.
|
"Files" application.
|
||||||
|
|
||||||
Configuring at-rest file data encryption does not encrypt any other data or
|
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
|
resources. In particular, it does not encrypt the database and does not encrypt
|
||||||
Passphrase credentials.
|
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
|
the data. In most configurations, this does not represent a significant
|
||||||
barrier above and beyond accessing the file data. Thus, configuring at-rest
|
barrier above and beyond accessing the file data. Thus, configuring at-rest
|
||||||
encryption is primarily useful for two types of installs:
|
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
|
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
|
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.
|
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:
|
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
|
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:
|
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.
|
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:
|
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
|
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:
|
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.
|
Once all files have been cycled, remove the old master key from the keyring.
|
||||||
|
|
|
@ -6,7 +6,7 @@ Setup guide for an alternate file domain or CDN.
|
||||||
Overview
|
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.
|
is a security risk.
|
||||||
|
|
||||||
In general, doing this creates a risk that users who have permission to upload
|
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.
|
executing the file and gain access to their session.
|
||||||
|
|
||||||
The best way to mitigate this threat is to serve files from a separate domain.
|
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/`.
|
you can serve files from `https://files.exampleusercontent.com/`.
|
||||||
|
|
||||||
The alternate file domain should be a completely different domain from your
|
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.
|
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
|
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
|
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.
|
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`.
|
`GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`.
|
||||||
|
|
||||||
Once configured, accessing the distribution's domain name should return a
|
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.
|
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
|
Approach: CloudFlare
|
||||||
========
|
========
|
||||||
|
@ -68,7 +68,7 @@ Approach: CloudFlare
|
||||||
WARNING: You should review all your CloudFlare settings, and be very
|
WARNING: You should review all your CloudFlare settings, and be very
|
||||||
sure to turn off all JavaScript, HTML, CSS minification and
|
sure to turn off all JavaScript, HTML, CSS minification and
|
||||||
optimization features, including systems like "Rocket Loader". These
|
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
|
are unpredictable. Only allow CloudFlare to cache files, and never
|
||||||
optimize them.
|
optimize them.
|
||||||
|
|
||||||
|
@ -76,23 +76,23 @@ optimize them.
|
||||||
|
|
||||||
To set up CloudFlare, you'll need to register a second domain and go through
|
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
|
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,
|
CloudFlare will automatically generate SSL certificates for hosted domains,
|
||||||
which can significantly reduce the cost and complexity of setup.
|
which can significantly reduce the cost and complexity of setup.
|
||||||
|
|
||||||
Once configured, accessing the CNAME-forwarded subdomain should return a
|
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.
|
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
|
Approach: Self Hosted
|
||||||
========
|
========
|
||||||
|
|
||||||
To do this, just set up a second domain exactly like your primary domain is
|
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
|
set up. When setup is complete, visiting the domain should return a Phorge
|
||||||
error page indicating that Phabricator does not recognize the domain. This
|
error page indicating that Phorge does not recognize the domain. This
|
||||||
means that you've configured things correctly.
|
means that you've configured things correctly.
|
||||||
|
|
||||||
Note that if you use SSL (which you should), you'll also need to get a
|
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
|
to provide some of the performance benefits of a CDN, but this is advanced and
|
||||||
outside the scope of this documentation.
|
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
|
recognize the domain. Run this command, providing the domain you have
|
||||||
configured in place of the `<domain>` token. You should include the protocol,
|
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
|
content through the file domain. You can verify this with "View Source" or
|
||||||
by downloading a file and checking the URL.
|
by downloading a file and checking the URL.
|
||||||
|
|
|
@ -6,8 +6,8 @@ Setup file storage and support for large files.
|
||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
This document describes how to configure Phabricator to support large file
|
This document describes how to configure Phorge to support large file
|
||||||
uploads, and how to choose where Phabricator stores files.
|
uploads, and how to choose where Phorge stores files.
|
||||||
|
|
||||||
There are two major things to configure:
|
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.
|
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
|
that implement access to some storage system (like MySQL, the filesystem, or
|
||||||
a cloud storage service like Amazon S3).
|
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.
|
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.
|
more flexibility in managing file data.
|
||||||
|
|
||||||
The first section of this document discusses configuring your install so that
|
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.
|
one.
|
||||||
|
|
||||||
To upload large files, you need to increase all the limits to at least
|
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.
|
store arbitrarily large files.
|
||||||
|
|
||||||
The settings which limit file uploads are:
|
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
|
- **lighttpd**: lighttpd limits requests with the lighttpd
|
||||||
`server.max-request-size` directive.
|
`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.
|
settings, so it can not raise setup warnings if they are misconfigured.
|
||||||
|
|
||||||
**PHP**: PHP has several directives which limit uploads. These directives are
|
**PHP**: PHP has several directives which limit uploads. These directives are
|
||||||
found in `php.ini`.
|
found in `php.ini`.
|
||||||
|
|
||||||
- **post_max_size**: Maximum POST request size PHP will accept. If you
|
- **post_max_size**: Maximum POST request size PHP will accept. If you
|
||||||
exceed this, Phabricator will give you a useful error. This often defaults
|
exceed this, Phorge will give you a useful error. This often defaults
|
||||||
to `8M`. Set this to at least `32MB`. Phabricator will give you a setup
|
to `8M`. Set this to at least `32MB`. Phorge will give you a setup
|
||||||
warning about this if it is set too low.
|
warning about this if it is set too low.
|
||||||
- **memory_limit**: For some uploads, file data will be read into memory
|
- **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
|
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.
|
give you a setup warning about this if it is set too low.
|
||||||
|
|
||||||
You may also want to configure these PHP options:
|
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_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,
|
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,
|
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`.
|
this to at least `32MB`.
|
||||||
|
|
||||||
Once you've adjusted all this configuration, your server will be able to
|
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
|
Storage Engines
|
||||||
===============
|
===============
|
||||||
|
|
||||||
Phabricator supports several different file storage engines:
|
Phorge supports several different file storage engines:
|
||||||
|
|
||||||
| Engine | Setup | Cost | Notes |
|
| 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
|
You can review available storage engines and their configuration by navigating
|
||||||
to {nav Applications > Files > Help/Options > Storage Engines} in the web UI.
|
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:
|
reject files larger than 1MB. To store larger files, you can either:
|
||||||
|
|
||||||
- increase the MySQL limit to at least 8MB; or
|
- 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
|
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.
|
properly, the file should upload.
|
||||||
|
|
||||||
Migrating Files Between Engines
|
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
|
recently set up S3 and want to migrate all your files there. First, migrate one
|
||||||
file to make sure things work:
|
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:
|
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
|
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.
|
taking any action. Run `bin/files help` for more options and information.
|
||||||
|
|
|
@ -2,15 +2,15 @@
|
||||||
@group config
|
@group config
|
||||||
|
|
||||||
This document contains instructions for configuring inbound email, so users
|
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
|
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,
|
**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`
|
**Creating Objects**: You can configure an address like `bugs@yourcompany.com`
|
||||||
to create new objects (like tasks) when users send email.
|
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:
|
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
|
- For handling replies, set `metamta.reply-handler-domain` in your
|
||||||
configuration.
|
configuration.
|
||||||
- For handling email that creates objects, configure inbound addresses in the
|
- 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
|
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
|
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 Phabricator via
|
you use a third-party mail service which can submit mail to Phorge via
|
||||||
webhooks.
|
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 |
|
| Receive Mail With | Setup | Cost | Notes |
|
||||||
|--------|-------|------|-------|
|
|--------|-------|------|-------|
|
||||||
|
@ -47,37 +47,37 @@ Some available approaches for delivering mail to Phabricator are:
|
||||||
| SendGrid | Easy | Cheap | |
|
| SendGrid | Easy | Cheap | |
|
||||||
| Local MTA | Difficult | Free | Discouraged |
|
| 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
|
receive mail, and then configuring your chosen transport to deliver mail
|
||||||
to Phabricator.
|
to Phorge.
|
||||||
|
|
||||||
|
|
||||||
Configuring "Reply" Email
|
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
|
as the "From" address when it sends mail. The exact address it uses can be
|
||||||
configured with `metamta.default-address`.
|
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
|
"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
|
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 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
|
over email, change the configuration key `metamta.reply-handler-domain` to some
|
||||||
domain you configure according to the instructions below, e.g.
|
domain you configure according to the instructions below, e.g.
|
||||||
`phabricator.example.com`. Once you set this key, email will use a
|
`phorge.example.com`. Once you set this key, email will use a
|
||||||
"Reply-To" like `T123+273+af310f9220ad@phabricator.example.com`, which -- when
|
"Reply-To" like `T123+273+af310f9220ad@phorge.example.com`, which -- when
|
||||||
configured correctly, according to the instructions below -- will parse incoming
|
configured correctly, according to the instructions below -- will parse incoming
|
||||||
email and allow users to interact with Differential revisions, Maniphest tasks,
|
email and allow users to interact with Differential revisions, Maniphest tasks,
|
||||||
etc. over email.
|
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
|
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
|
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) '+'
|
mail address. This works because everything up to the first (optional) '+'
|
||||||
character in an email address is considered the receiver, and everything
|
character in an email address is considered the receiver, and everything
|
||||||
after is essentially ignored.
|
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
|
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.
|
create a Maniphest task out of any email which is sent to it.
|
||||||
|
|
||||||
You can find application email settings for each application at:
|
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.
|
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
|
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
|
any address as an application address, but can only process mail which is
|
||||||
actually delivered to it.
|
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
|
project and need to interact with users whose email accounts you have no control
|
||||||
over).
|
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
|
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
|
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
|
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
|
If you enable application email addresses, those addresses also use the weaker
|
||||||
"From" authentication mechanism.
|
"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,
|
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
|
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
|
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
|
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.
|
phorge/ $ ./bin/mail list-inbound # List inbound messages.
|
||||||
phabricator/ $ ./bin/mail show-inbound # Show details about a message.
|
phorge/ $ ./bin/mail show-inbound # Show details about a message.
|
||||||
|
|
||||||
You can also test receiving mail, but note that this just simulates receiving
|
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
|
the mail and doesn't send any information over the network. It is
|
||||||
primarily aimed at developing email handlers: it will still work properly
|
primarily aimed at developing email handlers: it will still work properly
|
||||||
if your inbound email configuration is incorrect or even disabled.
|
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.
|
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.
|
- Configure a mail domain according to Mailgun's instructions.
|
||||||
- Add a Mailgun route with a `catch_all()` rule which takes the action
|
- 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.
|
example domain with your actual domain.
|
||||||
- Configure a mailer in `cluster.mailers` with your Mailgun API key.
|
- 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:
|
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
|
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:
|
inbound email. Provided you have such an account, configure it like this:
|
||||||
|
|
||||||
- Configure an MX record according to SendGrid's instructions, i.e. add
|
- 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
|
- Go to the "Parse Incoming Emails" page on SendGrid
|
||||||
(<http://sendgrid.com/developer/reply>) and add the domain as the
|
(<http://sendgrid.com/developer/reply>) and add the domain as the
|
||||||
"Hostname".
|
"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
|
using your domain (and HTTP instead of HTTPS if you are not configured with
|
||||||
SSL).
|
SSL).
|
||||||
- If you get an error that the hostname "can't be located or verified", it
|
- 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
|
means your MX record is either incorrectly configured or hasn't propagated
|
||||||
yet.
|
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).
|
(whatever you configured the MX record for).
|
||||||
|
|
||||||
That's it! If everything is working properly you should be able to send email
|
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.
|
`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
|
- add your host to /etc/mail/local-host-names; and
|
||||||
- restart sendmail.
|
- 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:
|
`/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
|
If you use the `PHABRICATOR_ENV` environmental variable to select a
|
||||||
configuration, you can pass the value to the script as an argument:
|
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
|
After making this change, run `sudo newaliases`. Now you likely need to symlink
|
||||||
this script into `/etc/smrsh/`:
|
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:
|
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
|
script. Run `sudo /etc/mail/make` or similar and then restart sendmail with
|
||||||
`sudo /etc/init.d/sendmail restart`.
|
`sudo /etc/init.d/sendmail restart`.
|
||||||
|
|
|
@ -1,17 +1,17 @@
|
||||||
@title Configuring Outbound Email
|
@title Configuring Outbound Email
|
||||||
@group config
|
@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.
|
messages, like text messages.
|
||||||
|
|
||||||
Overview
|
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
|
email and most messages are email messages, but mailers may also send other
|
||||||
types of messages (like text messages).
|
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:
|
including a local mailer or various third-party services. Options include:
|
||||||
|
|
||||||
| Send Mail With | Setup | Cost | Inbound | Media | Notes |
|
| 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
|
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.
|
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
|
it to be able to deliver mail. You should receive setup warnings if they are
|
||||||
not. For more information on using daemons, see
|
not. For more information on using daemons, see
|
||||||
@{article:Managing Daemons with phd}.
|
@{article:Managing Daemons with phd}.
|
||||||
|
@ -50,10 +50,10 @@ not. For more information on using daemons, see
|
||||||
Outbound "From" and "To" Addresses
|
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.
|
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
|
since some mailers require this and some users write mail rules that depend
|
||||||
on whether they appear in the "To" or "CC" line.
|
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.
|
of mail they probably don't want.
|
||||||
|
|
||||||
If you plan to configure //inbound// mail later, you usually don't need to do
|
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
|
works the right way (accepts and discards all mail it receives) and
|
||||||
automatically use it when generating addresses.
|
automatically use it when generating addresses.
|
||||||
|
|
||||||
If you don't plan to configure inbound mail, you may need to configure an
|
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`.
|
`metamta.default-address`.
|
||||||
|
|
||||||
|
|
||||||
|
@ -131,7 +131,7 @@ It also supports these local mailers:
|
||||||
- `smtp`: Connect directly to an SMTP server.
|
- `smtp`: Connect directly to an SMTP server.
|
||||||
- `test`: Internal mailer for testing. Does not send mail.
|
- `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:
|
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:
|
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
|
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/>.
|
<https://sendgrid.com/>.
|
||||||
|
|
||||||
You can configure SendGrid in two ways: you can send via SMTP or via the REST
|
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
|
To use the REST API mailer, set `type` to `sendgrid`, then configure
|
||||||
these `options`:
|
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`:
|
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
|
able to select a custom "Message-ID" header when sending mail via this
|
||||||
mailer. See "Message-ID Headers" below.
|
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.
|
- `password`: Optional string. Password for authentication.
|
||||||
- `protocol`: Optional string. Set to `tls` or `ssl` if necessary. Use
|
- `protocol`: Optional string. Set to `tls` or `ssl` if necessary. Use
|
||||||
`ssl` for Gmail.
|
`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
|
able to select a custom "Message-ID" header when sending mail via this
|
||||||
mailer. See "Message-ID Headers" below.
|
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
|
You can use the `bin/mail` utility to test, debug, and examine outbound mail. In
|
||||||
particular:
|
particular:
|
||||||
|
|
||||||
phabricator/ $ ./bin/mail list-outbound # List outbound mail.
|
phorge/ $ ./bin/mail list-outbound # List outbound mail.
|
||||||
phabricator/ $ ./bin/mail show-outbound # Show details about messages.
|
phorge/ $ ./bin/mail show-outbound # Show details about messages.
|
||||||
phabricator/ $ ./bin/mail send-test # Send test messages.
|
phorge/ $ ./bin/mail send-test # Send test messages.
|
||||||
|
|
||||||
Run `bin/mail help <command>` for more help on using these commands.
|
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
|
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
|
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.
|
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
|
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
|
highest priority group and go through them randomly, then fall back to the
|
||||||
next group.
|
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
|
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.
|
`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.
|
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
|
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.
|
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
|
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.
|
"Message-ID" header values for mail it sends.
|
||||||
|
|
||||||
However, some mailers (including Amazon SES) do not allow selection of custom
|
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
|
"Message-ID" values and will ignore or replace the "Message-ID" in mail that
|
||||||
is submitted through them.
|
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
|
"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
|
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
|
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"
|
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
|
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
|
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
|
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`.
|
specify `"message-id": false`.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -6,14 +6,14 @@ Adjust environmental settings (SSL, remote IPs) using a preamble script.
|
||||||
Overview
|
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
|
(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)
|
some environmental features (like the client's IP, or the presence of SSL)
|
||||||
correctly.
|
correctly.
|
||||||
|
|
||||||
You can use a special preamble script to make arbitrary adjustments to the
|
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
|
environment and some parts of Phorge's configuration in order to fix these
|
||||||
problems and set up the environment which Phabricator expects.
|
problems and set up the environment which Phorge expects.
|
||||||
|
|
||||||
|
|
||||||
Creating a Preamble Script
|
Creating a Preamble Script
|
||||||
|
@ -21,15 +21,15 @@ Creating a Preamble Script
|
||||||
|
|
||||||
To create a preamble script, write a file to:
|
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.)
|
colliding with `git` or interacting with updates.)
|
||||||
|
|
||||||
This file should be a valid PHP script. If you aren't very familiar with PHP,
|
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`:
|
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
|
No syntax errors detected in support/preamble.php
|
||||||
|
|
||||||
If present, this script will be executed at the very beginning of each web
|
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
|
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
|
all requests as originating from the load balancer, rather than from the
|
||||||
correct client IPs.
|
correct client IPs.
|
||||||
|
|
||||||
In common cases where networks are configured like this, the `X-Forwarded-For`
|
In common cases where networks are configured like this, the `X-Forwarded-For`
|
||||||
header will have trustworthy information about the real client IP. You
|
header will have trustworthy information about the real client IP. You
|
||||||
can use the function `preamble_trust_x_forwarded_for_header()` in your
|
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:
|
load balancer or proxy which modifies this header:
|
||||||
|
|
||||||
```name="Trust X-Forwarded-For Header", lang=php
|
```name="Trust X-Forwarded-For Header", lang=php
|
||||||
|
@ -89,9 +89,9 @@ if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) {
|
||||||
Adjusting SSL
|
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
|
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.
|
the SSL-only flag, or reject requests outright.
|
||||||
|
|
||||||
To fix this, you can set `$_SERVER['HTTPS']` explicitly:
|
To fix this, you can set `$_SERVER['HTTPS']` explicitly:
|
||||||
|
@ -103,7 +103,7 @@ name=Explicitly Configure SSL Availability
|
||||||
$_SERVER['HTTPS'] = true;
|
$_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.
|
request is not an SSL request.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -5,7 +5,7 @@ How to add custom fields to applications which support them.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
fields allow you to add more information to objects, and in some cases reorder
|
||||||
or remove builtin fields.
|
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.default** Text for the search interface, defaults to "(Any)".
|
||||||
- **search.require** Text for the search interface, defaults to "Require".
|
- **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
|
options. These are not intended for general use and are subject to abrupt
|
||||||
change, but are documented here for completeness:
|
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,
|
If you want custom fields to have advanced behaviors (sophisticated rendering,
|
||||||
advanced validation, complicated controls, interaction with other systems, etc),
|
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
|
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.
|
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} |
|
| Projects | @{class:PhabricatorProjectCustomField} |
|
||||||
|
|
||||||
The easiest way to get started is to drop your subclass into
|
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
|
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:
|
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:
|
Continue by:
|
||||||
|
|
||||||
- learning more about extending Phabricator with custom code in
|
- learning more about extending Phorge with custom code in
|
||||||
@{article@phabcontrib:Adding New Classes};
|
@{article@contrib:Adding New Classes};
|
||||||
- or returning to the @{article: Configuration Guide}.
|
- or returning to the @{article: Configuration Guide}.
|
||||||
|
|
|
@ -1,17 +1,17 @@
|
||||||
@title Managing Caches
|
@title Managing Caches
|
||||||
@group config
|
@group config
|
||||||
|
|
||||||
Discusses Phabricator caches and cache management.
|
Discusses Phorge caches and cache management.
|
||||||
|
|
||||||
Overview
|
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.
|
a web browser uses to improve web performance.
|
||||||
|
|
||||||
In particular, blocks of text which are expensive to render (like formatted
|
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
|
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.
|
instead of recomputing the result.
|
||||||
|
|
||||||
Because text is cached, you may continue to see the old result even after you
|
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).
|
eventually (usually within 30 days).
|
||||||
|
|
||||||
If you don't want to wait, you can purge the caches. This will remove any
|
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
|
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:
|
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
|
This tool can purge caches in a granular way, but it's normally easiest to
|
||||||
just purge all of the caches:
|
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
|
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.
|
||||||
|
|
|
@ -1,11 +1,11 @@
|
||||||
@title Managing Daemons with phd
|
@title Managing Daemons with phd
|
||||||
@group config
|
@group config
|
||||||
|
|
||||||
Explains Phabricator daemons and the daemon control program `phd`.
|
Explains Phorge daemons and the daemon control program `phd`.
|
||||||
|
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
Phabricator uses daemons (background processing scripts) to handle a number of
|
Phorge uses daemons (background processing scripts) to handle a number of
|
||||||
tasks:
|
tasks:
|
||||||
|
|
||||||
- tracking repositories, discovering new commits, and importing and parsing
|
- 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
|
Daemons are started and stopped with **phd** (the **Ph**abricator **D**aemon
|
||||||
launcher). Daemons can be monitored via a web console.
|
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
|
features (principally, repository tracking with Diffusion) require them and
|
||||||
several features will benefit in performance or stability if you configure
|
several features will benefit in performance or stability if you configure
|
||||||
daemons.
|
daemons.
|
||||||
|
|
||||||
= phd =
|
= 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`:
|
a list of commands, run `phd help`:
|
||||||
|
|
||||||
phabricator/ $ ./bin/phd help
|
phorge/ $ ./bin/phd help
|
||||||
NAME
|
NAME
|
||||||
phd - phabricator daemon launcher
|
phd - phorge daemon launcher
|
||||||
...
|
...
|
||||||
|
|
||||||
Generally, you will use:
|
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 launch** to launch individual daemons; and
|
||||||
- **phd debug** to debug problems with daemons.
|
- **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`.
|
the daemons by running `phd restart`.
|
||||||
|
|
||||||
= Daemon Console =
|
= Daemon Console =
|
||||||
|
@ -81,12 +81,12 @@ launch custom daemons, or launch special daemons like the IRC bot.
|
||||||
|
|
||||||
To debug a daemon, use `phd debug`:
|
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
|
You can pass arguments like this (normal arguments are passed to the daemon
|
||||||
control mechanism, not to the daemon itself):
|
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
|
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
|
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`:
|
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.
|
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,
|
just those started with `phd start`. If you're writing a restart script,
|
||||||
have it launch any custom daemons explicitly after `phd restart`.
|
have it launch any custom daemons explicitly after `phd restart`.
|
||||||
- You can write your own daemons and manage them with `phd` by extending
|
- 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
|
- See @{article:Diffusion User Guide} for details about tuning the repository
|
||||||
daemon.
|
daemon.
|
||||||
|
|
||||||
|
@ -128,4 +128,4 @@ Continue by:
|
||||||
|
|
||||||
- learning about the repository daemon with @{article:Diffusion User Guide};
|
- learning about the repository daemon with @{article:Diffusion User Guide};
|
||||||
or
|
or
|
||||||
- writing your own daemons with @{article@phabcontrib:Adding New Classes}.
|
- writing your own daemons with @{article@contrib:Adding New Classes}.
|
||||||
|
|
|
@ -6,7 +6,7 @@ Understanding and configuring garbage collection.
|
||||||
Overview
|
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
|
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
|
passed, so they are deleted automatically (often after a month or two) in a
|
||||||
process called "garbage collection".
|
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:
|
`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
|
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`.
|
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
|
By using the `--trace` flag, you can inspect the operation of the collector
|
||||||
|
|
|
@ -6,11 +6,11 @@ Guide to setting up notifications.
|
||||||
Overview
|
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
|
tasks or commenting on code reviews) through email and in-application
|
||||||
notifications.
|
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
|
popping up a message in any open browser windows if something has happened or
|
||||||
an object has been updated.
|
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
|
You will also need to install the `ws` module for Node. This needs to be
|
||||||
installed into the notification server directory:
|
installed into the notification server directory:
|
||||||
|
|
||||||
phabricator/ $ cd support/aphlict/server/
|
phorge/ $ cd support/aphlict/server/
|
||||||
phabricator/support/aphlict/server/ $ npm install ws
|
phorge/support/aphlict/server/ $ npm install ws
|
||||||
|
|
||||||
Once Node.js and the `ws` module are installed, you're ready to start the
|
Once Node.js and the `ws` module are installed, you're ready to start the
|
||||||
server.
|
server.
|
||||||
|
@ -57,21 +57,21 @@ Running the Aphlict Server
|
||||||
After installing Node.js, you can control the notification server with the
|
After installing Node.js, you can control the notification server with the
|
||||||
`bin/aphlict` command. To start the server:
|
`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
|
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
|
a host firewall (like a security group in EC2), make sure traffic can reach the
|
||||||
server.
|
server.
|
||||||
|
|
||||||
The server configuration is controlled by a configuration file, which is
|
The server configuration is controlled by a configuration file, which is
|
||||||
separate from Phabricator's configuration settings. The default file can
|
separate from Phorge's configuration settings. The default file can
|
||||||
be found at `phabricator/conf/aphlict/aphlict.default.json`.
|
be found at `phorge/conf/aphlict/aphlict.default.json`.
|
||||||
|
|
||||||
To make adjustments to the default configuration, either copy this file to
|
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
|
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:
|
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:
|
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
|
The defaults are appropriate for simple cases, but you may need to adjust them
|
||||||
if you are running a more complex configuration.
|
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
|
`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:
|
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",
|
"type": "client",
|
||||||
"host": "phabricator.mycompany.com",
|
"host": "phorge.mycompany.com",
|
||||||
"port": 22280,
|
"port": 22280,
|
||||||
"protocol": "https"
|
"protocol": "https"
|
||||||
},
|
},
|
||||||
|
@ -165,7 +165,7 @@ Troubleshooting
|
||||||
|
|
||||||
You can run `aphlict` in the foreground to get output to your console:
|
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
|
Because the notification server uses WebSockets, your browser error console
|
||||||
may also have information that is useful in figuring out what's wrong.
|
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
|
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.
|
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
|
select an appropriate HTTPS service from `notification.servers` and instruct
|
||||||
the browser to open a websocket connection with `wss://`.
|
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 {
|
||||||
server_name phabricator.example.com;
|
server_name phorge.example.com;
|
||||||
root /path/to/phabricator/webroot;
|
root /path/to/phorge/webroot;
|
||||||
|
|
||||||
// ...
|
// ...
|
||||||
|
|
||||||
|
@ -260,10 +260,10 @@ server {
|
||||||
|
|
||||||
With this approach, you should make these additional adjustments:
|
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:
|
`"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 `port` to the standard HTTPS port (usually `443`).
|
||||||
- Set `protocol` to `"https"`.
|
- Set `protocol` to `"https"`.
|
||||||
- Set `path` to `/ws/`, so it matches the special `location` in your
|
- Set `path` to `/ws/`, so it matches the special `location` in your
|
||||||
|
|
|
@ -6,13 +6,13 @@ Explains how to apply storage adjustments to the MySQL schemata.
|
||||||
Overview
|
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
|
kinds of changes to the MySQL schema. This workflow compliments the //storage
|
||||||
upgrade// workflow, which makes major changes.
|
upgrade// workflow, which makes major changes.
|
||||||
|
|
||||||
You can perform storage adjustment by running:
|
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
|
This document describes what adjustments are, how they relate to storage
|
||||||
upgrades, how to perform them, and how to troubleshoot issues with storage
|
upgrades, how to perform them, and how to troubleshoot issues with storage
|
||||||
|
@ -22,7 +22,7 @@ adjustment.
|
||||||
Understanding Adjustments
|
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
|
improve consistency, unicode handling, and performance. Changes covered by
|
||||||
adjustment include:
|
adjustment include:
|
||||||
|
|
||||||
|
@ -62,7 +62,7 @@ adjustment workflow can resolve.
|
||||||
|
|
||||||
You can also review adjustments from the CLI, by running:
|
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
|
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.
|
available adjustments. You can then make a choice to apply them.
|
||||||
|
@ -73,11 +73,11 @@ Performing Adjustments
|
||||||
|
|
||||||
To perform adjustments, run the `adjust` workflow:
|
To perform adjustments, run the `adjust` workflow:
|
||||||
|
|
||||||
phabricator/ $ ./bin/storage adjust
|
phorge/ $ ./bin/storage adjust
|
||||||
|
|
||||||
For details about flags, use:
|
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
|
You do not normally need to run this workflow manually: it will be run
|
||||||
automatically after you run the `upgrade` workflow.
|
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
|
The adjustment workflow allows us to alter the schema to primarily use
|
||||||
`binary` character sets on older MySQL, and primarily use `utf8mb4` character
|
`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
|
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
|
newer MySQL, we can also take advantage of the better collation rules the
|
||||||
`utf8mb4` character set offers.
|
`utf8mb4` character set offers.
|
||||||
|
@ -143,7 +143,7 @@ upstream.
|
||||||
|
|
||||||
In general, adjustments are not critical. If you run into issues applying
|
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
|
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.
|
be resolved.
|
||||||
|
|
||||||
Surplus Schemata
|
Surplus Schemata
|
||||||
|
@ -154,13 +154,13 @@ After performing adjustment, you may receive an error that a table or column is
|
||||||
|
|
||||||
| Target | Error |
|
| 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
|
to exist. These surpluses usually exist because you (or someone else
|
||||||
with database access) added the table or column manually. Rarely, they can
|
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
|
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
|
column doesn't have anything important in it, it does not delete them
|
||||||
automatically.
|
automatically.
|
||||||
|
|
||||||
|
@ -174,18 +174,18 @@ message):
|
||||||
|
|
||||||
```lang=sql
|
```lang=sql
|
||||||
CREATE DATABASE my_backups;
|
CREATE DATABASE my_backups;
|
||||||
RENAME TABLE phabricator_example.example_table
|
RENAME TABLE phorge_example.example_table
|
||||||
TO my_backups.example_table;
|
TO my_backups.example_table;
|
||||||
```
|
```
|
||||||
|
|
||||||
Phabricator will ignore tables that aren't in databases it owns, so you can
|
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 Phabricator databases.
|
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,
|
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):
|
specifying the correct table name (the one given in the error message):
|
||||||
|
|
||||||
```lang=sql
|
```lang=sql
|
||||||
DROP TABLE phabricator_example.example_table;
|
DROP TABLE phorge_example.example_table;
|
||||||
```
|
```
|
||||||
|
|
||||||
This will destroy the table permanently.
|
This will destroy the table permanently.
|
||||||
|
|
|
@ -5,7 +5,7 @@ Detailed instructions for troubleshooting HTTPS connection problems.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
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
|
connection." error, this document may be able to help you diagnose and resolve
|
||||||
the problem.
|
the problem.
|
||||||
|
@ -17,7 +17,7 @@ Connection negotiation can fail for several reasons. The major ones are:
|
||||||
certificates).
|
certificates).
|
||||||
- The SSL certificate is signed for the wrong domain. For example, a
|
- The SSL certificate is signed for the wrong domain. For example, a
|
||||||
certificate signed for `www.example.com` will not work for
|
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
|
- The server rejects TLSv1 SNI connections for the domain (this is
|
||||||
complicated, see below).
|
complicated, see below).
|
||||||
|
|
||||||
|
@ -50,7 +50,7 @@ with:
|
||||||
$ openssl x509 -text -in <certificate>
|
$ openssl x509 -text -in <certificate>
|
||||||
|
|
||||||
If the certificate was accidentally generated for, e.g. `www.example.com` but
|
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.
|
new certificate for the right domain.
|
||||||
|
|
||||||
= SNI Problems =
|
= 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:
|
/SourceCache/OpenSSL098/OpenSSL098-44/src/ssl/s23_clnt.c:602:
|
||||||
|
|
||||||
...it indicates server is misconfigured. The most common cause of this problem
|
...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.
|
valid VirtualHost.
|
||||||
|
|
||||||
This error occurs only for some versions of the OpenSSL client library
|
This error occurs only for some versions of the OpenSSL client library
|
||||||
|
|
|
@ -1,7 +0,0 @@
|
||||||
@title Give Feedback! Get Support!
|
|
||||||
@short Feedback/Support
|
|
||||||
@group cellar
|
|
||||||
|
|
||||||
Deprecated.
|
|
||||||
|
|
||||||
This article has moved to @{article:Support Resources}.
|
|
|
@ -25,7 +25,7 @@ Methods have one of three statuses:
|
||||||
them before they stabilize.
|
them before they stabilize.
|
||||||
- **Stable**: This is an established method which generally will not change.
|
- **Stable**: This is an established method which generally will not change.
|
||||||
- **Deprecated**: This method will be removed in a future version of
|
- **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
|
Normally, a method is deprecated only when it is obsolete or a new, more
|
||||||
powerful method is available to replace it.
|
powerful method is available to replace it.
|
||||||
|
|
|
@ -6,9 +6,9 @@ Enabling and using the built-in debugging and performance console.
|
||||||
Overview
|
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,
|
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.
|
applications.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Command Line Exit Codes
|
@title Command Line Exit Codes
|
||||||
@group fieldmanual
|
@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
|
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
|
The code `0` means success. Other codes signal some sort of error or status
|
||||||
condition, depending on the system and command.
|
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**.
|
**catastrophic failure**.
|
||||||
|
|
||||||
This is an explicit architectural decision and one we are unlikely to deviate
|
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
|
operational environment. This document explains the reasoning behind our use of
|
||||||
exit codes in more detail.
|
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
|
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
|
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`
|
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
|
scripts. We are willingly trading the small scale away for advantages at larger
|
||||||
scales.
|
scales.
|
||||||
|
@ -56,11 +56,10 @@ operations environment faces different forces than the interactive shell did
|
||||||
in the 1970s, particularly at scale.
|
in the 1970s, particularly at scale.
|
||||||
|
|
||||||
We consider correctness to be very important to modern operations environments.
|
We consider correctness to be very important to modern operations environments.
|
||||||
In particular, we manage a Phabricator cluster (Phacility) and believe that
|
In particular, we believe that having reliable, repeatable processes for
|
||||||
having reliable, repeatable processes for provisioning, configuration and
|
provisioning, configuration and deployment is critical to maintaining and
|
||||||
deployment is critical to maintaining and scaling our operations. Our use of
|
scaling our operations. Our use of exit codes makes it easier to implement
|
||||||
exit codes makes it easier to implement processes that are correct and reliable
|
processes that are correct and reliable on top of Phorge management scripts.
|
||||||
on top of Phabricator management scripts.
|
|
||||||
|
|
||||||
Exit codes as signals for application state are problematic because they are
|
Exit codes as signals for application state are problematic because they are
|
||||||
ambiguous: you can't use them to distinguish between dissimilar failure states
|
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
|
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
|
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
|
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
|
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
|
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.
|
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
|
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.
|
get roughly the same effect that you'd get out of an exit code.
|
||||||
|
|
||||||
|
|
|
@ -23,18 +23,18 @@ Performance and the Upstream
|
||||||
============================
|
============================
|
||||||
|
|
||||||
Performance issues and hangs will often require upstream involvement to fully
|
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
|
not require tuning for different workloads (as long as those workloads are
|
||||||
generally reasonable). Poor performance with a reasonable workload is likely a
|
generally reasonable). Poor performance with a reasonable workload is likely a
|
||||||
bug, not a configuration problem.
|
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,
|
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
|
to download over the network, and your browser will probably not be able to
|
||||||
render it especially quickly.
|
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
|
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
|
is usually to find another way to solve your problem: for example, maybe the
|
||||||
100MB document can be split into several smaller documents.
|
100MB document can be split into several smaller documents.
|
||||||
|
|
|
@ -6,7 +6,7 @@ How to permanently destroy data and manage leaked secrets.
|
||||||
Overview
|
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
|
provides a command-line tool for destroying objects if you're certain that
|
||||||
you want to destroy something.
|
you want to destroy something.
|
||||||
|
|
||||||
|
@ -24,7 +24,7 @@ Destroying Data
|
||||||
To permanently destroy an object, run this command from the command line:
|
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
|
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
|
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
|
permanently destroy data. One major reason for this requirement is that it
|
||||||
limits the reach of an attacker who compromises a privileged account.
|
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
|
like an API key or another credential. For example, an engineer might
|
||||||
accidentally send a change for review which includes a sensitive private key.
|
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
|
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,
|
repository mirroring, CDN caching, and so on. You can try to clean up the mess,
|
||||||
but you're generally already too late.
|
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
|
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.
|
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
|
disclosed, you can revoke them so they no longer function. See
|
||||||
@{article:Revoking Credentials} for more information.
|
@{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
|
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:
|
can make it more difficult to accidentally disclose secrets:
|
||||||
|
|
||||||
**Differential Diff Herald Rules**: You can write "Differential Diff" rules
|
**Differential Diff Herald Rules**: You can write "Differential Diff" rules
|
||||||
|
|
|
@ -6,7 +6,7 @@ Dealing with rewrites of published repositories and other unusual problems.
|
||||||
Overview
|
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.
|
about these commits to improve behavior.
|
||||||
|
|
||||||
Supported hints are:
|
Supported hints are:
|
||||||
|
@ -17,7 +17,7 @@ Supported hints are:
|
||||||
new pages.
|
new pages.
|
||||||
- **Unreadable Commits**: If some commits are not readable (which is rare,
|
- **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)
|
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
|
The remainder of this document explains how to create and remove hints, and how
|
||||||
to specify each type of hint.
|
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`:
|
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:
|
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
|
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
|
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
|
bother trying to read the changes associated with a particular commit. In
|
||||||
some rare cases, repositories can contain commits which aren't readable
|
some rare cases, repositories can contain commits which aren't readable
|
||||||
(for example, if they were created by external tools during an import or
|
(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.
|
with this commit.
|
||||||
|
|
|
@ -7,7 +7,7 @@ Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
When you first import an external source code repository (or push new commits to
|
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
|
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
|
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
|
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,
|
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
|
then creates stub objects for them. These stub objects primarily serve to
|
||||||
assign various internal IDs to each commit.
|
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:
|
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
|
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:
|
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.
|
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:
|
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
|
This command is always safe to run, no matter what the actual root cause of
|
||||||
the problem is.
|
the problem is.
|
||||||
|
|
||||||
If this fails with an error, you've likely identified a problem with
|
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
|
special and file a bug in the upstream by following the instructions in
|
||||||
@{article:Contributing Bug Reports}.
|
@{article:Contributing Bug Reports}.
|
||||||
|
|
||||||
|
@ -132,7 +132,7 @@ wait that long.
|
||||||
|
|
||||||
In the Daemon console, temporarily failures usually look like tasks in the
|
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
|
"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.
|
waiting to retry these tasks.
|
||||||
|
|
||||||
In the daemon log, these temporary failures might have created log entries, but
|
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:
|
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
|
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.
|
extra things they shouldn't have.
|
||||||
|
|
||||||
There is no normal set of conditions under which this should occur, but you can
|
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
|
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
|
"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`:
|
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
|
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
|
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
|
second copy of email about the commit. Other than that, it is safe to run even
|
||||||
if this isn't the problem.
|
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:
|
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
|
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:
|
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
|
In particular, you can use flags with the `repository reparse` command to
|
||||||
|
|
|
@ -1,14 +1,14 @@
|
||||||
@title Restarting Phabricator
|
@title Restarting Phorge
|
||||||
@group fieldmanual
|
@group fieldmanual
|
||||||
|
|
||||||
Instructions on how to restart HTTP and PHP servers to reload configuration
|
Instructions on how to restart HTTP and PHP servers to reload configuration
|
||||||
changes in Phabricator.
|
changes in Phorge.
|
||||||
|
|
||||||
|
|
||||||
Overview
|
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.
|
restart your server processes, particularly after making configuration changes.
|
||||||
This document explains how to restart them properly.
|
This document explains how to restart them properly.
|
||||||
|
|
||||||
|
|
|
@ -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:
|
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.
|
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:
|
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:
|
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:
|
You can revoke these credentials by running these commands:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/auth revoke --type password --everywhere
|
phorge/ $ ./bin/auth revoke --type password --everywhere
|
||||||
phabricator/ $ ./bin/auth revoke --type conduit --everywhere
|
phorge/ $ ./bin/auth revoke --type conduit --everywhere
|
||||||
phabricator/ $ ./bin/auth revoke --type session --everywhere
|
phorge/ $ ./bin/auth revoke --type session --everywhere
|
||||||
phabricator/ $ ./bin/auth revoke --type temporary --everywhere
|
phorge/ $ ./bin/auth revoke --type temporary --everywhere
|
||||||
```
|
```
|
||||||
|
|
||||||
Depending on the nature of the compromise you may also consider revoking `ssh`
|
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:
|
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
|
||||||
```
|
```
|
||||||
|
|
|
@ -6,7 +6,7 @@ Advanced guide to managing the background worker task queue.
|
||||||
Overview
|
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.
|
importing repositories and sending mail) in the background.
|
||||||
|
|
||||||
In most cases, this queue will automatically execute tasks in an appropriate
|
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
|
Reference: Priority Levels
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
Tasks queued by Phabricator use these default priority levels:
|
Tasks queued by Phorge use these default priority levels:
|
||||||
|
|
||||||
| Priority | Name | Tasks |
|
| Priority | Name | Tasks |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
|
@ -33,7 +33,7 @@ with priority 2000).
|
||||||
|
|
||||||
Any positive integer is a valid priority level, and if you adjust the priority
|
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
|
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
|
may adjust tasks to priority `5678`, which will make them execute after all
|
||||||
other types of natural tasks.
|
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
|
behavior of the worker queue is when importing a very large repository like
|
||||||
the Linux kernel.
|
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
|
a lower priority level than all other non-import tasks, you may still run into
|
||||||
issues like these:
|
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:
|
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,
|
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:
|
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
|
The selected tasks will not execute until 6 hours from the time this command
|
||||||
|
|
|
@ -7,7 +7,7 @@ Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
XHProf is a profiling tool which will let you understand application
|
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
|
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
|
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
|
From the command line, use the `--xprofile <filename>` flag to generate a
|
||||||
profile of any script.
|
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.
|
and view it in the web UI.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,18 +1,18 @@
|
||||||
@title Installation Guide
|
@title Installation Guide
|
||||||
@group intro
|
@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.
|
running.
|
||||||
|
|
||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
Phabricator is a LAMP (Linux, Apache, MySQL, PHP) application. To install
|
Phorge is a LAMP (Linux, Apache, MySQL, PHP) application. To install
|
||||||
Phabricator, you will need:
|
Phorge, you will need:
|
||||||
|
|
||||||
- a normal computer to install it on (shared hosts and unusual environments
|
- a normal computer to install it on (shared hosts and unusual environments
|
||||||
are not supported) running some flavor of Linux or a similar OS;
|
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;
|
- basic sysadmin skills;
|
||||||
- Apache, nginx, or another webserver;
|
- Apache, nginx, or another webserver;
|
||||||
- PHP, MySQL, and Git.
|
- PHP, MySQL, and Git.
|
||||||
|
@ -25,32 +25,32 @@ Installation Requirements
|
||||||
You will need **a computer**. Options include:
|
You will need **a computer**. Options include:
|
||||||
|
|
||||||
- **A Normal Computer**: This is strongly recommended. Many installs use a VM
|
- **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
|
- **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
|
features from working. Consider using a normal computer instead. We do not
|
||||||
support shared hosts.
|
support shared hosts.
|
||||||
- **A SAN Appliance, Network Router, Gaming Console, Raspberry Pi, etc.**:
|
- **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
|
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
|
consider using a normal computer instead. We do not support specialized
|
||||||
hardware.
|
hardware.
|
||||||
- **A Toaster, Car, Firearm, Thermostat, etc.**: Yes, many modern devices now
|
- **A Toaster, Car, Firearm, Thermostat, etc.**: Yes, many modern devices now
|
||||||
have embedded computing capability. We live in interesting times. However,
|
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.
|
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
|
system** on your normal computer which is **not Windows**. Note that the
|
||||||
command line interface //does// work on Windows, and you can //use//
|
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,
|
software does not run on Windows. It does run on most other operating systems,
|
||||||
so choose one of these instead:
|
so choose one of these instead:
|
||||||
|
|
||||||
- **Linux**: Most installs use Linux.
|
- **Linux**: Most installs use Linux.
|
||||||
- **Mac OS X**: Mac OS X is an acceptable flavor of 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
|
- **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.
|
install and run properly on FreeBSD.
|
||||||
- **Solaris, etc.**: Other systems which look like Linux and quack like Linux
|
- **Solaris, etc.**: Other systems which look like Linux and quack like Linux
|
||||||
will generally work fine, although we may suffer a reduced ability to
|
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.
|
works fine.
|
||||||
- **Other**: Other webservers which can run PHP are also likely to work 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.
|
although these installation instructions will not cover how to set them up.
|
||||||
- **PHP Builtin Server**: Phabricator will not work with the builtin
|
- **PHP Builtin Server**: Phorge will not work with the builtin
|
||||||
webserver because Phabricator depends on making requests to itself on some
|
webserver because Phorge depends on making requests to itself on some
|
||||||
workflows, and the builtin webserver is single-threaded.
|
workflows, and the builtin webserver is single-threaded.
|
||||||
|
|
||||||
You will also need:
|
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
|
You'll probably also need a **domain name**. In particular, you should read this
|
||||||
note:
|
note:
|
||||||
|
|
||||||
NOTE: Phabricator must be installed on an entire domain. You can not install it
|
NOTE: Phorge must be installed on an entire domain. You can not install it
|
||||||
to a path on an existing domain, like `example.com/phabricator/`. Instead,
|
to a path on an existing domain, like `example.com/phorge/`. Instead,
|
||||||
install it to an entire domain or subdomain, like `phabricator.example.com`.
|
install it to an entire domain or subdomain, like `phorge.example.com`.
|
||||||
|
|
||||||
Level Requirements
|
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
|
common system administration skills. For example, you should be familiar with
|
||||||
using the command line, installing software on your operating system of choice,
|
using the command line, installing software on your operating system of choice,
|
||||||
working with the filesystem, managing processes, dealing with permissions,
|
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
|
this set of skills to troubleshoot and resolve problems, you may encounter
|
||||||
issues which you have substantial difficulty working through.
|
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
|
common system administration skills and concepts. If you aren't, proceed at
|
||||||
your own risk and expect that your skills may be tested.
|
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:
|
document for you:
|
||||||
|
|
||||||
- **RedHat Derivatives**:
|
- **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 ]]
|
| install_rhel-derivs.sh ]]
|
||||||
- **Ubuntu**:
|
- **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 ]]
|
| install_ubuntu.sh ]]
|
||||||
|
|
||||||
If those work for you, you can skip directly to the
|
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
|
It may also be helpful to refer to the install scripts above, even if they don't
|
||||||
work for your system.
|
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:
|
dependencies:
|
||||||
|
|
||||||
$ cd somewhere/ # pick some install directory
|
$ cd somewhere/ # pick some install directory
|
||||||
somewhere/ $ git clone https://github.com/phacility/arcanist.git
|
somewhere/ $ git clone https://we.phorge.it/source/arcanist.git
|
||||||
somewhere/ $ git clone https://github.com/phacility/phabricator.git
|
somewhere/ $ git clone https://we.phorge.it/source/phorge.git
|
||||||
|
|
||||||
Next Steps
|
Next Steps
|
||||||
==========
|
==========
|
||||||
|
|
||||||
Continue by:
|
Continue by:
|
||||||
|
|
||||||
- configuring Phabricator with the @{article:Configuration Guide}; or
|
- configuring Phorge with the @{article:Configuration Guide}; or
|
||||||
- learning how to keep Phabricator up to date with
|
- learning how to keep Phorge up to date with
|
||||||
@{article:Upgrading Phabricator}.
|
@{article:Upgrading Phorge}.
|
||||||
|
|
|
@ -1,33 +1,34 @@
|
||||||
@title Introduction
|
@title Introduction
|
||||||
@group intro
|
@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
|
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
|
- **Differential**, a code review tool; and
|
||||||
- **Diffusion**, a repository browser; and
|
- **Diffusion**, a repository browser; and
|
||||||
- **Maniphest**, a bug tracker; and
|
- **Maniphest**, a bug tracker; and
|
||||||
- **Phriction**, a wiki.
|
- **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
|
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
|
to scale both to large datasets (Facebook has 500,000+ commits across many
|
||||||
repositories) and large organizations (Facebook has 500+ fulltime engineers).
|
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
|
- If you develop primarily on Windows, you are likely to find integration
|
||||||
with the toolsets you use lacking.
|
with the toolsets you use lacking.
|
||||||
|
@ -40,4 +41,4 @@ However, Phabricator may also not be a good solution for you:
|
||||||
|
|
||||||
Continue by:
|
Continue by:
|
||||||
|
|
||||||
- installing Phabricator with the @{article:Installation Guide}.
|
- installing Phorge with the @{article:Installation Guide}.
|
||||||
|
|
|
@ -1,36 +1,17 @@
|
||||||
@title Reporting Security Vulnerabilities
|
@title Reporting Security Vulnerabilities
|
||||||
@group intro
|
@group intro
|
||||||
|
|
||||||
Describes how to report security vulnerabilities in Phabricator.
|
Describes how to report security vulnerabilities in Phorge.
|
||||||
|
|
||||||
Overview
|
Overview
|
||||||
========
|
========
|
||||||
|
|
||||||
Phabricator runs a disclosure and award program through
|
Phorge accepts bug reports on the upstream install. Please use the
|
||||||
[[ https://www.hackerone.com/ | HackerOne ]]. This program is the best way to
|
[[https://we.phorge.it/maniphest/task/edit/form/1/ | security reporting form]]
|
||||||
submit security issues to us, and awards responsible disclosure of
|
to report security vulnerabilities.
|
||||||
vulnerabilities with cash bounties. You can find our project page
|
|
||||||
here:
|
|
||||||
|
|
||||||
(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
|
General information about security changes is reported in the
|
||||||
how to participate.
|
[[ https://we.phorge.it/w/changelog/ | Changelog ]].
|
||||||
|
|
||||||
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 ]].
|
|
||||||
|
|
|
@ -2,4 +2,35 @@
|
||||||
@short Support
|
@short Support
|
||||||
@group intro
|
@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}.
|
||||||
|
|
|
@ -1,12 +1,12 @@
|
||||||
@title Upgrading Phabricator
|
@title Upgrading Phorge
|
||||||
@group intro
|
@group intro
|
||||||
|
|
||||||
This document contains instructions for keeping Phabricator up to date.
|
This document contains instructions for keeping Phorge up to date.
|
||||||
|
|
||||||
Overview
|
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.
|
continuously. Staying up to date will keep your install secure.
|
||||||
|
|
||||||
We recommend installs upgrade regularly (every 1-2 weeks). Upgrades usually go
|
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
|
Staying On Top of Changes
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
We release a weekly [[https://secure.phabricator.com/w/changelog | Changelog]],
|
We release a [[https://we.phorge.it/w/changelog | Changelog]],
|
||||||
which describes changes in the previous week. You can look at the changelogs
|
which describes changes over time. You can look at the changelogs
|
||||||
for an idea of what new features are available, upcoming changes, security
|
for an idea of what new features are available, upcoming changes, security
|
||||||
information, and warnings about compatibility issues or migrations.
|
information, and warnings about compatibility issues or migrations.
|
||||||
|
|
||||||
|
@ -27,21 +27,18 @@ information, and warnings about compatibility issues or migrations.
|
||||||
Stable Branch
|
Stable Branch
|
||||||
=============
|
=============
|
||||||
|
|
||||||
You can either run the `master` or `stable` branch of Phabricator. The `stable`
|
You can either run the `master` or `stable` branch of Phorge. The `stable`
|
||||||
branch is run in the [[ https://phacility.com | Phacility Cluster ]], and lags
|
branch is a little more stable than `master`, and may be helpful if you
|
||||||
about a week behind `master`.
|
administrate a larger install.
|
||||||
|
|
||||||
The `stable` branch is a little more stable than `master`, and may be helpful
|
We promote `master` to `stable` frequently, then publish the changelog. During
|
||||||
if you administrate a larger install.
|
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
|
||||||
We promote `master` to `stable` about once a week, then publish the changelog
|
cherry-picked.
|
||||||
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.
|
|
||||||
|
|
||||||
To switch to `stable`, check the branch out in each working copy:
|
To switch to `stable`, check the branch out in each working copy:
|
||||||
|
|
||||||
phabricator/ $ git checkout stable
|
phorge/ $ git checkout stable
|
||||||
arcanist/ $ git checkout stable
|
arcanist/ $ git checkout stable
|
||||||
|
|
||||||
You can now follow the upgrade process normally.
|
You can now follow the upgrade process normally.
|
||||||
|
@ -50,26 +47,26 @@ You can now follow the upgrade process normally.
|
||||||
Upgrade Process
|
Upgrade Process
|
||||||
===============
|
===============
|
||||||
|
|
||||||
IMPORTANT: You **MUST** restart Phabricator after upgrading. For help, see
|
IMPORTANT: You **MUST** restart Phorge after upgrading. For help, see
|
||||||
@{article:Restarting Phabricator}.
|
@{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
|
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
|
script which can work on any system. However, the general steps are the same
|
||||||
on every system:
|
on every system:
|
||||||
|
|
||||||
- Stop the webserver (including `php-fpm`, if you use it).
|
- Stop the webserver (including `php-fpm`, if you use it).
|
||||||
- Stop the daemons, with `phabricator/bin/phd stop`.
|
- Stop the daemons, with `phorge/bin/phd stop`.
|
||||||
- Run `git pull` in `arcanist/` and `phabricator/`.
|
- Run `git pull` in `arcanist/` and `phorge/`.
|
||||||
- Run `phabricator/bin/storage upgrade`.
|
- Run `phorge/bin/storage upgrade`.
|
||||||
- Start the daemons, with `phabricator/bin/phd start`.
|
- Start the daemons, with `phorge/bin/phd start`.
|
||||||
- Restart the webserver (and `php-fpm`, if you stopped it earlier).
|
- Restart the webserver (and `php-fpm`, if you stopped it earlier).
|
||||||
|
|
||||||
For some more discussion details, see @{article:Configuration Guide}.
|
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:
|
You'll need to adjust paths and commands a bit for your particular system:
|
||||||
|
|
||||||
```lang=sh
|
```lang=sh
|
||||||
|
@ -78,23 +75,23 @@ You'll need to adjust paths and commands a bit for your particular system:
|
||||||
set -e
|
set -e
|
||||||
set -x
|
set -x
|
||||||
|
|
||||||
# This is an example script for updating Phabricator, similar to the one used to
|
# This is an example script for updating Phorge, similar to the one used to
|
||||||
# update <https://secure.phabricator.com/>. It might not work perfectly on your
|
# 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
|
# system, but hopefully it should be easy to adapt. This script is not intended
|
||||||
# to work without modifications.
|
# to work without modifications.
|
||||||
|
|
||||||
# NOTE: This script assumes you are running it from a directory which contains
|
# 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.
|
ROOT=`pwd` # You can hard-code the path here instead.
|
||||||
|
|
||||||
### STOP WEB SERVER AND DAEMONS ###############################################
|
### STOP WEB SERVER AND DAEMONS ###############################################
|
||||||
|
|
||||||
# Stop daemons.
|
# Stop daemons.
|
||||||
$ROOT/phabricator/bin/phd stop
|
$ROOT/phorge/bin/phd stop
|
||||||
|
|
||||||
# If running the notification server, stop it.
|
# 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
|
# Stop the webserver (apache, nginx, lighttpd, etc). This command will differ
|
||||||
# depending on which system and webserver you are running: replace it with an
|
# 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
|
cd $ROOT/arcanist
|
||||||
git pull
|
git pull
|
||||||
|
|
||||||
cd $ROOT/phabricator
|
cd $ROOT/phorge
|
||||||
git pull
|
git pull
|
||||||
|
|
||||||
# Upgrade the database schema. You may want to add the "--force" flag to allow
|
# Upgrade the database schema. You may want to add the "--force" flag to allow
|
||||||
# this script to run noninteractively.
|
# 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.
|
# Restart the webserver. As above, this depends on your system and webserver.
|
||||||
# NOTE: If you're running php-fpm, restart it here too.
|
# NOTE: If you're running php-fpm, restart it here too.
|
||||||
sudo /etc/init.d/httpd start
|
sudo /etc/init.d/httpd start
|
||||||
|
|
||||||
# Restart daemons.
|
# Restart daemons.
|
||||||
$ROOT/phabricator/bin/phd start
|
$ROOT/phorge/bin/phd start
|
||||||
|
|
||||||
# If running the notification server, start it.
|
# If running the notification server, start it.
|
||||||
# $ROOT/phabricator/bin/aphlict start
|
# $ROOT/phorge/bin/aphlict start
|
||||||
```
|
```
|
||||||
|
|
|
@ -11,7 +11,7 @@ lists of //devices// and //services// that humans and other applications can
|
||||||
use to keep track of what is running where.
|
use to keep track of what is running where.
|
||||||
|
|
||||||
Almanac is an infrastructure application that will normally be used by
|
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.
|
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.
|
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
|
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.
|
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
|
- Providing a list of build servers to Drydock so it can run build and
|
||||||
integration tasks.
|
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
|
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
|
application and can be used to configure and manage other types of service and
|
||||||
|
|
|
@ -6,7 +6,7 @@ Discusses using Amazon RDS as a database.
|
||||||
Overview
|
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
|
checks assume you are using local MySQL, and upstream support is less available
|
||||||
for RDS.
|
for RDS.
|
||||||
|
|
||||||
|
|
|
@ -1,9 +1,9 @@
|
||||||
@title Arcanist User Guide
|
@title Arcanist User Guide
|
||||||
@group userguide
|
@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
|
Differential, Files, and Paste), integrates with static analysis ("lint") and
|
||||||
unit tests, and manages common workflows like getting changes into Differential
|
unit tests, and manages common workflows like getting changes into Differential
|
||||||
for review.
|
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.
|
document provides an overview of common workflows and installation.
|
||||||
|
|
||||||
Arcanist has technical, contributor-focused documentation here:
|
Arcanist has technical, contributor-focused documentation here:
|
||||||
<https://secure.phabricator.com/book/arcanist/>
|
<https://we.phorge.it/book/arcanist/>
|
||||||
|
|
||||||
= Quick Start =
|
= Quick Start =
|
||||||
|
|
||||||
|
@ -143,7 +143,7 @@ three sources, in order:
|
||||||
# User configuration is read from `~/.arcconfig`. This file is JSON, and can
|
# User configuration is read from `~/.arcconfig`. This file is JSON, and can
|
||||||
be updated using `arc set-config`.
|
be updated using `arc set-config`.
|
||||||
# Host configuration is read from `/etc/arcconfig` (on Windows, the path
|
# 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.
|
Arcanist uses the first definition it encounters as the runtime setting.
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Arcanist User Guide: Code Coverage
|
@title Arcanist User Guide: Code Coverage
|
||||||
@group userguide
|
@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
|
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
|
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
|
If the test engine enables coverage by default, it will be uploaded to
|
||||||
Differential and displayed in the right gutter when viewing diffs.
|
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:
|
you install Xdebug:
|
||||||
|
|
||||||
http://xdebug.org/
|
http://xdebug.org/
|
||||||
|
|
|
@ -14,7 +14,7 @@ information.
|
||||||
= Overview =
|
= Overview =
|
||||||
|
|
||||||
While `arc` has a large number of commands that interface with various
|
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
|
review in Differential (for more information on Differential, see
|
||||||
@{article:Differential User Guide}). If you aren't familiar with Differential,
|
@{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
|
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
|
Differential will make a guess about a next step on accepted revisions, but it
|
||||||
may not be the best next step for your workflow.
|
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
|
to a repository that is tracked in Diffusion. Specifically, it will close
|
||||||
revisions based on commit and tree hashes, and `Differential Revision`
|
revisions based on commit and tree hashes, and `Differential Revision`
|
||||||
identifiers in commit messages.
|
identifiers in commit messages.
|
||||||
|
|
|
@ -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
|
If you haven't created a library for the class to live in yet, you need to do
|
||||||
that first. Follow the instructions in
|
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:
|
adding it to your `.arcconfig` like this:
|
||||||
|
|
||||||
{
|
{
|
||||||
|
|
|
@ -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
|
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
|
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
|
name=.arcconfig
|
||||||
{
|
{
|
||||||
"phabricator.uri" : "https://phabricator.example.com/"
|
"phabricator.uri" : "https://phorge.example.com/"
|
||||||
}
|
}
|
||||||
|
|
||||||
For details on available options, see below.
|
For details on available options, see below.
|
||||||
|
@ -31,7 +31,7 @@ configuration, not user configuration.
|
||||||
|
|
||||||
Common options are:
|
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
|
connect to when run in this project. This option was previously called
|
||||||
`conduit_uri`.
|
`conduit_uri`.
|
||||||
- **repository.callsign**: The callsign of this repository in Diffusion.
|
- **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.
|
- **load**: list of additional Phutil libraries to load at startup.
|
||||||
See below for details about path resolution, or see
|
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.
|
libphutil libraries.
|
||||||
- **https.cabundle**: specifies the path to an alternate certificate bundle
|
- **https.cabundle**: specifies the path to an alternate certificate bundle
|
||||||
for use when making HTTPS connections.
|
for use when making HTTPS connections.
|
||||||
|
@ -62,9 +62,9 @@ Other options include:
|
||||||
These options are supported, but their use is discouraged:
|
These options are supported, but their use is discouraged:
|
||||||
|
|
||||||
- **http.basicauth.user**: specify an HTTP basic auth username for use when
|
- **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
|
- **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.blindly-trust-domains**: a list of domains to trust blindly over
|
||||||
HTTPS, even if their certificates are invalid. This is a brute force
|
HTTPS, even if their certificates are invalid. This is a brute force
|
||||||
solution to certificate validity problems, and is discouraged. Instead,
|
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`:
|
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
|
`arc set-config default <uri>`, or specify an explicit URI
|
||||||
with `--conduit-uri` each time you run a command.
|
with `--conduit-uri` each time you run a command.
|
||||||
- You will not be able to run linters through arc unless you pass `--engine`
|
- You will not be able to run linters through arc unless you pass `--engine`
|
||||||
|
|
|
@ -40,17 +40,17 @@ Create a `.arcconfig` file in your project's working copy:
|
||||||
yourproject/ $ $EDITOR .arcconfig
|
yourproject/ $ $EDITOR .arcconfig
|
||||||
yourproject/ $ cat .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).
|
should send changes to).
|
||||||
|
|
||||||
NOTE: You should **commit this file** to the repository.
|
NOTE: You should **commit this file** to the repository.
|
||||||
|
|
||||||
= Install Arcanist Credentials =
|
= 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.
|
before you can perform this step.
|
||||||
|
|
||||||
$ cd yourproject/
|
$ 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
|
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 =
|
= Send Changes For Review =
|
||||||
|
|
||||||
|
|
|
@ -1,13 +1,13 @@
|
||||||
@title Audit User Guide
|
@title Audit User Guide
|
||||||
@group userguide
|
@group userguide
|
||||||
|
|
||||||
Guide to using Phabricator to audit published commits.
|
Guide to using Phorge to audit published commits.
|
||||||
|
|
||||||
|
|
||||||
Overview
|
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
|
"audit" (post-publish). To understand the differences between the two, see
|
||||||
@{article:User Guide: Review vs Audit}.
|
@{article:User Guide: Review vs Audit}.
|
||||||
|
|
||||||
|
@ -59,14 +59,14 @@ a typical audit workflow:
|
||||||
- Alice publishes a commit containing some Javascript.
|
- Alice publishes a commit containing some Javascript.
|
||||||
- This triggers an audit request to Bailey, the Javascript technical
|
- This triggers an audit request to Bailey, the Javascript technical
|
||||||
lead on the project (see below for a description of trigger mechanisms).
|
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
|
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
|
week she looks through her open requests to see what the team has been
|
||||||
up to.
|
up to.
|
||||||
- Bailey notices a few minor problems with Alice's commit. She leaves
|
- Bailey notices a few minor problems with Alice's commit. She leaves
|
||||||
comments describing improvements and uses "Raise Concern" to send the
|
comments describing improvements and uses "Raise Concern" to send the
|
||||||
commit back into Alice's queue.
|
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
|
concern (usually, Alice will also get an email). She resolves the issue
|
||||||
somehow, maybe by making a followup commit with fixes.
|
somehow, maybe by making a followup commit with fixes.
|
||||||
- After the issues have been dealt with, she uses "Request Verification" to
|
- 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:
|
Get more information about a command by running:
|
||||||
|
|
||||||
```
|
```
|
||||||
phabricator/ $ ./bin/audit help <command>
|
phorge/ $ ./bin/audit help <command>
|
||||||
```
|
```
|
||||||
|
|
||||||
Supported operations are:
|
Supported operations are:
|
||||||
|
|
|
@ -29,7 +29,7 @@ Reminders are sent 15 minutes before events begin.
|
||||||
Availability
|
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
|
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
|
a meeting (or on vacation) and could take a while to get back to you about a
|
||||||
revision or task.
|
revision or task.
|
||||||
|
|
|
@ -9,15 +9,15 @@ Overview
|
||||||
IMPORTANT: Calendar is a prototype application. See
|
IMPORTANT: Calendar is a prototype application. See
|
||||||
@{article:User Guide: Prototype Applications}.
|
@{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
|
**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
|
When you export events into another application, they generally will not be
|
||||||
editable from that application. Exporting events allows you to create one
|
editable from that application. Exporting events allows you to create one
|
||||||
calendar that shows all the events you care about in whatever application you
|
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
|
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
|
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).
|
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.
|
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
|
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
|
much data you export and treat the URI as a secret. If you accidentally share
|
||||||
a URI, you can disable the export.
|
a URI, you can disable the export.
|
||||||
|
|
||||||
|
|
|
@ -9,14 +9,14 @@ Overview
|
||||||
IMPORTANT: Calendar is a prototype application. See
|
IMPORTANT: Calendar is a prototype application. See
|
||||||
@{article:User Guide: Prototype Applications}.
|
@{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
|
`.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
|
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
|
events from different sources, but does not let you edit events from other
|
||||||
applications in Phabricator.
|
applications in Phorge.
|
||||||
|
|
||||||
|
|
||||||
Import Policies
|
Import Policies
|
||||||
|
@ -36,18 +36,18 @@ Importing `.ics` Files
|
||||||
event or an entire event calendar.
|
event or an entire event calendar.
|
||||||
|
|
||||||
If you have an event or calendar in `.ics` format, you can import it into
|
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}.
|
- Navigate to {nav Calendar > Imports > Import Events > Import .ics File}.
|
||||||
- Drag and drop the file onto a Calendar.
|
- 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
|
If you want to update an imported event later, just repeat this process. The
|
||||||
event will be updated with the latest information.
|
event will be updated with the latest information.
|
||||||
|
|
||||||
Many applications send `.ics` files as email attachments. You can import these
|
Many applications send `.ics` files as email attachments. You can import these
|
||||||
into Phabricator.
|
into Phorge.
|
||||||
|
|
||||||
|
|
||||||
.ics Files: Google Calendar
|
.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
|
You can also convert an individual event into an `.ics` file by dragging it
|
||||||
from the calendar to your desktop (or any other folder).
|
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
|
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.
|
about the updates.
|
||||||
|
|
||||||
|
|
||||||
|
@ -78,7 +78,7 @@ Importing .ics URIs
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
If you have a calendar in another application that supports publishing a
|
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
|
calendar, and can be configured to automatically keep it up to date and in sync
|
||||||
with the external calendar.
|
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}.
|
{nav Calendar > Imports > Import Events > Import .ics URI}.
|
||||||
|
|
||||||
When you import a URI, you can choose to enable automatic updates. If you do,
|
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
|
You can stop this later by turning off the automatic updates or disabling
|
||||||
the import.
|
the import.
|
||||||
|
|
||||||
|
@ -121,7 +121,7 @@ shared.
|
||||||
**Calendar.app** does not support subscriptions via `.ics` URIs.
|
**Calendar.app** does not support subscriptions via `.ics` URIs.
|
||||||
|
|
||||||
You can export a calendar as an `.ics` file by following the steps above, but
|
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
|
Next Steps
|
||||||
|
|
|
@ -6,7 +6,7 @@ Overview of the Conduit API.
|
||||||
Overview
|
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
|
pass a JSON blob, and usually get a JSON blob back, although both call and
|
||||||
result formats are flexible in some cases.
|
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.
|
includes examples which show how to format calls.
|
||||||
|
|
||||||
**Other Clients**: There are also clients available in other languages. You
|
**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.
|
Community Resources ]] page for links.
|
||||||
|
|
||||||
API Console
|
API Console
|
||||||
|
|
|
@ -5,7 +5,7 @@ Guide to the Differential (pre-push code review) tool and workflow.
|
||||||
|
|
||||||
= Overview =
|
= 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
|
"audit" (post-push). To understand the differences between the two, see
|
||||||
@{article:User Guide: Review vs Audit}.
|
@{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 =
|
= 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:
|
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
|
- An author prepares a change to a codebase, then sends it for review. They
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Differential User Guide: Automated Landing
|
@title Differential User Guide: Automated Landing
|
||||||
@group userguide
|
@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
|
Overview
|
||||||
|
@ -9,7 +9,7 @@ Overview
|
||||||
|
|
||||||
IMPORTANT: This feature is a prototype and has substantial limitations.
|
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
|
directly from the web interface. This can make publishing changes more
|
||||||
convenient, particularly for open source projects where authors may not have
|
convenient, particularly for open source projects where authors may not have
|
||||||
commit access to the repository. This document explains the workflow and how to
|
commit access to the repository. This document explains the workflow and how to
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
@title Diffusion User Guide
|
@title Diffusion User Guide
|
||||||
@group userguide
|
@group userguide
|
||||||
|
|
||||||
Guide to Diffusion, the Phabricator application for hosting and browsing
|
Guide to Diffusion, the Phorge application for hosting and browsing
|
||||||
repositories.
|
repositories.
|
||||||
|
|
||||||
Overview
|
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
|
interacted with, but hosted repositories support some additional triggers
|
||||||
and access controls which are not available for observed repositories.
|
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:
|
instance:
|
||||||
|
|
||||||
- when you commit Differential revisions to a tracked repository, they are
|
- when you commit Differential revisions to a tracked repository, they are
|
||||||
|
@ -61,7 +61,7 @@ API to create and edit repositories, see
|
||||||
Repository Clustering
|
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
|
can lose hosts with minimal downtime and data loss. This is an advanced feature
|
||||||
which most installs do not need to pursue.
|
which most installs do not need to pursue.
|
||||||
|
|
||||||
|
@ -88,7 +88,7 @@ helpful:
|
||||||
|
|
||||||
- get details about automatically taking actions in response to commits in
|
- get details about automatically taking actions in response to commits in
|
||||||
@{article:Diffusion User Guide: Permanent Refs}; or
|
@{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
|
@{article:Diffusion User Guide: Repository Updates}; or
|
||||||
- fix issues with repository imports with
|
- fix issues with repository imports with
|
||||||
@{article:Troubleshooting Repository Imports}.
|
@{article:Troubleshooting Repository Imports}.
|
||||||
|
|
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue