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