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,36 +1,36 @@ { - "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" }, "exclude": [ "(^externals/)", "(^resources/)", "(^scripts/)", "(^src/docs/flavor/)", "(^src/docs/tech/)", "(^src/docs/user/)", "(^support/)", "(^webroot/rsrc/externals/)" ], "groups": { "contrib": { "name": "Contributor Overview" }, "detail": { "name": "Contributing in Detail" }, "developer": { "name": "Developer Guides" }, "standards": { "name": "Coding Standards" } } } 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,42 +1,39 @@ { - "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" }, "exclude": [ "(^externals/)", "(^resources/)", "(^scripts/)", "(^src/docs/contributor/)", "(^src/docs/tech/)", "(^src/docs/user/)", "(^support/)", "(^webroot/rsrc/externals/)" ], "groups": { - "overview": { - "name": "Overview" - }, "javascript": { "name": "Javascript" }, "lore": { - "name": "Phabricator Lore" + "name": "Phorge Lore" }, "php": { "name": "PHP" }, "review": { "name": "Revision Control and Code Review" }, "sundry": { "name": "Sundries" } } } 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,343 +1,343 @@ { - "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" }, "exclude": [ "(^externals/)", "(^resources/)", "(^scripts/)", "(^src/docs/contributor/)", "(^src/docs/flavor/)", "(^src/docs/user/)", "(^support/)", "(^webroot/rsrc/externals/)" ], "groups": { "aphront": { "name": "Aphront", "include": "(^src/aphront/)" }, "almanac": { "name": "Almanac", "include": "(^src/applications/almanac/)" }, "aphlict": { "name": "Aphlict", "include": "(^src/applications/aphlict/)" }, "arcanist": { "name": "Arcanist Integration", "include": "(^src/applications/arcanist/)" }, "auth": { "name": "Auth", "include": "(^src/applications/auth/)" }, "baseapp": { "name": "Application Basics", "include": "(^src/applications/base/)" }, "cache": { "name": "Cache", "include": "(^src/applications/cache/)" }, "calendar": { "name": "Calendar", "include": "(^src/applications/calendar/)" }, "celerity": { "name": "Celerity", "include": "(^src/applications/celerity/)" }, "chatlog": { "name": "Chatlog", "include": "(^src/applications/chatlog/)" }, "conduit": { "name": "Conduit", "include": "(^src/applications/conduit/)" }, "config": { "name": "Config", "include": "(^src/applications/config/)" }, "conpherence": { "name": "Conpherence", "include": "(^src/applications/conpherence/)" }, "console": { "name": "Console", "include": "(^src/applications/console/)" }, "countdown": { "name": "Countdown", "include": "(^src/applications/countdown/)" }, "customfield": { "name": "Custom Fields", "include": "(^src/infrastructure/customfield/)" }, "daemon": { "name": "Daemons", "include": [ "(^src/applications/daemon/)", "(^src/infrastructure/daemon/)" ] }, "dashboard": { "name": "Dashboard", "include": "(^src/applications/dashboard/)" }, "differential": { "name": "Differential", "include": "(^src/applications/differential/)" }, "diffusion": { "name": "Diffusion", "include": "(^src/applications/diffusion/)" }, "diviner": { "name": "Diviner", "include": "(^src/applications/diviner/)" }, "doorkeeper": { "name": "Doorkeeper", "include": "(^src/applications/doorkeeper/)" }, "draft": { "name": "Draft", "include": "(^src/applications/draft/)" }, "drydock": { "name": "Drydock", "include": "(^src/applications/drydock/)" }, "edges": { "name": "Edges", "include": "(^src/infrastructure/edges/)" }, "events": { "name": "Events", "include": "(^src/infrastructure/events/)" }, "fact": { "name": "Fact", "include": "(^src/applications/fact/)" }, "feed": { "name": "Feed", "include": "(^src/applications/feed/)" }, "files": { "name": "Files", "include": "(^src/applications/files/)" }, "flag": { "name": "Flags", "include": "(^src/applications/flag/)" }, "fund": { "name": "Fund", "include": "(^src/applications/fund/)" }, "harbormaster": { "name": "Harbormaster", "include": "(^src/applications/harbormaster/)" }, "help": { "name": "Help", "include": "(^src/applications/help/)" }, "herald": { "name": "Herald", "include": "(^src/applications/herald/)" }, "home": { "name": "Home", "include": "(^src/applications/home/)" }, "legalpad": { "name": "Legalpad", "include": "(^src/applications/legalpad/)" }, "lipsum": { "name": "Lipsum", "include": "(^src/applications/lipsum/)" }, "macro": { "name": "Macro", "include": "(^src/applications/macro/)" }, "maniphest": { "name": "Maniphest", "include": "(^src/applications/maniphest/)" }, "meta": { "name": "Applications", "include": "(^src/applications/meta/)" }, "metamta": { "name": "MetaMTA", "include": "(^src/applications/metamta/)" }, "multimeter": { "name": "Multimeter", "include": "(^src/applications/multimeter/)" }, "notification": { "name": "Notifications", "include": "(^src/applications/notification/)" }, "nuance": { "name": "Nuance", "include": "(^src/applications/nuance/)" }, "oauthserver": { "name": "OAuth Server", "include": "(^src/applications/oauthserver/)" }, "owners": { "name": "Owners", "include": "(^src/applications/owners/)" }, "passphrase": { "name": "Passphrase", "include": "(^src/applications/passphrase/)" }, "paste": { "name": "Paste", "include": "(^src/applications/paste/)" }, "people": { "name": "People", "include": "(^src/applications/people/)" }, "phame": { "name": "Phame", "include": "(^src/applications/phame/)" }, "phid": { "name": "PHIDs", "include": "(^src/applications/phid/)" }, "phlux": { "name": "Phlux", "include": "(^src/applications/phlux/)" }, "pholio": { "name": "Pholio", "include": "(^src/applications/pholio/)" }, "phortune": { "name": "Phortune", "include": "(^src/applications/phortune/)" }, "phpast": { "name": "PHPAST", "include": "(^src/applications/phpast/)" }, "phragment": { "name": "Phragment", "include": "(^src/applications/phragment/)" }, "phrequent": { "name": "Phrequent", "include": "(^src/applications/phrequent/)" }, "phriction": { "name": "Phriction", "include": "(^src/applications/phriction/)" }, "phui": { "name": "PHUI", "include": "(^src/view/phui/)" }, "policy": { "name": "Policy", "include": "(^src/applications/policy/)" }, "ponder": { "name": "Ponder", "include": "(^src/applications/ponder/)" }, "project": { "name": "Projects", "include": "(^src/applications/project/)" }, "releeph": { "name": "Releeph", "include": "(^src/applications/releeph/)" }, "remarkup": { "name": "Remarkup", "include": [ "(^src/applications/remarkup/)", "(^src/infrastructure/markup/)" ] }, "repository": { "name": "Repositories", "include": "(^src/applications/repository/)" }, "search": { "name": "Search", "include": "(^src/applications/search/)" }, "settings": { "name": "Settings", "include": "(^src/applications/settings/)" }, "slowvote": { "name": "Slowvote", "include": "(^src/applications/slowvote/)" }, "spaces": { "name": "Spaces", "include": "(^src/applications/spaces/)" }, "storage": { "name": "Storage", "include": "(^src/infrastructure/storage/)" }, "subscriptions": { "name": "Subscriptions", "include": "(^src/applications/subscriptions/)" }, "support": { "name": "Support", "include": "(^src/applications/support/)" }, "system": { "name": "System", "include": "(^src/applications/system/)" }, "tokens": { "name": "Tokens", "include": "(^src/applications/tokens/)" }, "transactions": { "name": "Transactions", "include": "(^src/applications/transactions/)" }, "typeahead": { "name": "Typeahead", "include": "(^src/applications/typeahead/)" }, "uiexample": { "name": "UI Examples", "include": "(^src/applications/uiexample/)" }, "xhprof": { "name": "XHProf", "include": "(^src/applications/xhprof/)" } } } 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,45 +1,42 @@ { - "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" }, "exclude": [ "(^externals/)", "(^resources/)", "(^scripts/)", "(^src/docs/contributor/)", "(^src/docs/flavor/)", "(^src/docs/tech/)", "(^support/)", "(^webroot/rsrc/externals/)" ], "groups": { "intro": { "name": "Introduction" }, "config": { "name": "Configuration" }, "userguide": { "name": "Application User Guides" }, "conduit": { "name": "API Documentation" }, "cluster": { "name": "Cluster Configuration" }, "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,256 +1,255 @@ @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 @{class@arcanist:ArcanistWorkflow}. It discovers available locales 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: - **Extensions Directory**: This is a simple way to add new code. It is less powerful, but takes a lot less work. This is good for quick changes, testing and development, or getting started on a larger project. - **Creating Libraries**: This is a more advanced and powerful way to organize extension code. This is better for larger or longer-lived projects, or any code which you plan to distribute. 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 array( 'libcustom' => 'libcustom/src/', ), ... ``` -Now, Phabricator will be able to load classes from your custom library. +Now, Phorge will be able to load classes from your custom library. Writing Classes =============== To actually write classes, create a new module and put code in it: libcustom/ $ mkdir src/example/ libcustom/ $ nano src/example/ExampleClass.php # Edit some code. Now, run `arc liberate` to regenerate the static resource map: libcustom/ $ arc liberate src/ This will automatically regenerate the static map of the library. What You Can Extend And Invoke ============================== -Arcanist and Phabricator are strict about extensibility of classes and +Arcanist and Pohrge are strict about extensibility of classes and visibility of methods and properties. Most classes are marked `final`, and methods have the minimum required visibility (protected or private). The goal of this strictness is to make it clear what you can safely extend, access, and invoke, so your code will keep working as the upstream changes. -IMPORTANT: We'll still break APIs frequently. The upstream does not support -extension development, and none of these APIs are stable. +IMPORTANT: We'll still break APIs frequently. The upstream offers limited + support for extension development, and none of these APIs are stable. -When developing libraries to work with Arcanist and Phabricator, you should +When developing libraries to work with Arcanist and Phorge, you should respect method and property visibility. If you want to add features but can't figure out how to do it without changing -Phabricator code, here are some approaches you may be able to take: +Phorge code, here are some approaches you may be able to take: - {icon check, color=green} **Use Composition**: If possible, use composition rather than extension to build your feature. - {icon check, color=green} **Find Another Approach**: Check the documentation for a better way to accomplish what you're trying to do. - {icon check, color=green} **File a Feature Request**: Let us know what your use case is so we can make the class tree more flexible or configurable, or point you at the right way to do whatever you're trying to do, or explain - why we don't let you do it. Note that we **do not support** extension - development so you may have mixed luck with this one. + why we don't let you do it. These approaches are **discouraged**, but also possible: - {icon times, color=red} **Fork**: Create an ad-hoc local fork and remove `final` in your copy of the code. This will make it more difficult for you to upgrade in the future, although it may be the only real way forward depending on what you're trying to do. - {icon times, color=red} **Use Reflection**: You can use [[ http://php.net/manual/en/book.reflection.php | Reflection ]] to remove modifiers at runtime. This is fragile and discouraged, but technically possible. - {icon times, color=red} **Remove Modifiers**: Send us a patch removing `final` (or turning `protected` or `private` into `public`). We will almost never accept these patches unless there's a very good reason that the current behavior is wrong. Next Steps ========== Continue by: - - visiting the [[ https://secure.phabricator.com/w/community_resources/ | + - visiting the [[ https://we.phorge.it/w/community_resources/ | Community Resources ]] page to find or share extensions and libraries. diff --git a/src/docs/contributor/adding_new_css_and_js.diviner b/src/docs/contributor/adding_new_css_and_js.diviner index 00a3808fba..16bf5ebe03 100644 --- a/src/docs/contributor/adding_new_css_and_js.diviner +++ b/src/docs/contributor/adding_new_css_and_js.diviner @@ -1,96 +1,94 @@ @title Adding New CSS and JS @group developer -Explains how to add new CSS and JS files to Phabricator. +Explains how to add new CSS and JS files to Phorge. = Overview = -Phabricator uses a system called **Celerity** to manage static resources. If you -are a current or former Facebook employee, Celerity is based on the Haste system -used at Facebook and generally behaves similarly. +Phorge uses a system called **Celerity** to manage static resources. -This document is intended for Phabricator developers and contributors. This +(NOTE) This document is intended for Phorge developers and contributors. This process will not work correctly for third-party code, plugins, or extensions. = Adding a New File = To add a new CSS or JS file, create it in an appropriate location in -`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phabricator/` +`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phorge/` directory. Each file must `@provides` itself as a component, declared in a header comment: LANG=css /** * @provides duck-styles-css */ .duck-header { font-size: 9001px; } Note that this comment must be a Javadoc-style comment, not just any comment. If your component depends on other components (which is common in JS but rare and inadvisable in CSS), declare then with `@requires`: LANG=js /** * @requires javelin-stratcom * @provides duck */ /** * Put class documentation here, NOT in the header block. */ JX.install('Duck', { ... }); Then rebuild the Celerity map (see the next section). = Changing an Existing File = When you add, move or remove a file, or change the contents of existing JS or CSS file, you should rebuild the Celerity map: - phabricator/ $ ./bin/celerity map + phorge/ $ ./bin/celerity map If you've only changed file content things will generally work even if you don't, but they might start not working as well in the future if you skip this step. The generated file `resources/celerity/map.php` causes merge conflicts quite often. They can be resolved by running the Celerity mapper. You can automate this process by running: - phabricator/ $ ./scripts/celerity/install_merge.sh + phorge/ $ ./scripts/celerity/install_merge.sh This will install Git merge driver which will run when a conflict in this file occurs. = Including a File = To include a CSS or JS file in a page, use @{function:require_celerity_resource}: require_celerity_resource('duck-style-css'); require_celerity_resource('duck'); If your map is up to date, the resource should now be included correctly when the page is rendered. You should place this call as close to the code which actually uses the resource as possible, i.e. **not** at the top of your Controller. The idea is that you should @{function:require_celerity_resource} a resource only if you are actually using it on a specific rendering of the page, not just because some views of the page might require it. = Next Steps = Continue by: - reading about Javascript-specific guidelines in @{article:Javascript Coding Standards}; or - reading about CSS-specific guidelines and features in @{article:CSS Coding Standards}. diff --git a/src/docs/contributor/assistive_technologies.diviner b/src/docs/contributor/assistive_technologies.diviner index a519bde881..98113b2a07 100644 --- a/src/docs/contributor/assistive_technologies.diviner +++ b/src/docs/contributor/assistive_technologies.diviner @@ -1,76 +1,76 @@ @title Assistive Technologies @group developer -Information about making Phabricator accessible to assistive technologies. +Information about making Phorge accessible to assistive technologies. Overview ======== Assistive technologies help people with disabilities use the web. For example, screen readers can assist people with limited or no eyesight by reading the contents of pages aloud. -Phabricator has some support for assistive technologies, and we'd like to have +Phorge has some support for assistive technologies, and we'd like to have more support. This document describes how to use the currently available -features to improve the accessibility of Phabricator. +features to improve the accessibility of Phorge. Aural-Only Elements =================== The most common issue assistive technologies encounter is buttons, links, or other elements which only convey information visually (usually through an icon or image). These elements can be made more accessible by providing an aural-only label. This label will not be displayed by visual browsers, but will be read by screen readers. To add an aural-only label to an element, use `javelin_tag()` with the `aural` attribute: javelin_tag( 'span', array( 'aural' => true, ), pht('Aural Label Here')); This label should be placed inside the button or link that you are labeling. You can also use `aural` on a container to provide an entirely different replacement element, but should be cautious about doing this. NOTE: You must use `javelin_tag()`, not `phutil_tag()`, to get support for this attribute. Visual-Only Elements ==================== Occasionally, a visual element should be hidden from screen readers. This should be rare, but some textual elements convey very little information or are otherwise disruptive for aural users. This technique can also be used to offer a visual alternative of an element and a different aural alternative element. However, this should be rare: it is usually better to adapt a single element to work well for both visual and aural users. You can mark an element as visual-only by using `javelin_tag()` with the `aural` attribute: javelin_tag( 'span', array( 'aural' => false, ), $ascii_art); Previewing Aural Pages ====================== To verify aural markup, you can add `?__aural__=1` to any page URI. This will -make Phabricator render the page with styles that reveal aural-only elements and +make Phorge render the page with styles that reveal aural-only elements and mute visual-only elements. diff --git a/src/docs/contributor/bug_reports.diviner b/src/docs/contributor/bug_reports.diviner index e86fc917a5..3ded817a48 100644 --- a/src/docs/contributor/bug_reports.diviner +++ b/src/docs/contributor/bug_reports.diviner @@ -1,5 +1,156 @@ @title Contributing Bug Reports @group detail -Effective June 1, 2021: Phabricator is no longer actively maintained and no longer accepts bug reports. +Describes how to file an effective Phorge bug report. + +Overview +======== + +This article describes how to file an effective Phorge bug report. + +The most important things to do are: + + - check the list of common fixes below; + - make sure Phorge is up to date; + - make sure we support your setup; + - gather debugging information; and + - explain how to reproduce the issue. + +The rest of this article walks through these points in detail. + +For general information on contributing to Phorge, see +@{article:Contributor Introduction}. + + +Common Fixes +============ + +Before you file a report, here are some common solutions to problems: + + - **Update Phorge**: We receive a lot of bug reports about issues we have + already fixed in HEAD. Updating often resolves issues. It is common for + issues to be fixed in less than 24 hours, so even if you've updated recently + you should update again. If you aren't sure how to update, see the next + section. + - **Update Libraries**: Make sure `arcanist/` and `phorge/` are all up + to date. Users often update `phorge/` but forget to update `arcanist/`. + When you update, make sure you update both libraries. + - **Restart Apache or PHP-FPM**: Phorge uses caches which don't get + reset until you restart Apache or PHP-FPM. After updating, make sure you + restart. + + +Update Phorge +============= + +Before filing a bug, make sure you are up to date. We receive many bug reports +for issues we have already fixed, and even if we haven't fixed an issue we'll +be able to resolve it more easily if you file a report based on HEAD. (For +example, an old stack trace may not have the right line numbers, which will +make it more difficult for us to figure out what's going wrong.) + +To update Phorge, use a script like the one described in +@{article:Upgrading Phorge}. + +**If you can not update** for some reason, please include the version of +Phorge and Arcanist you are running when you file a report. + +For help, see @{article:Providing Version Information}. + + +Supported Issues +================ + +Before filing a bug, make sure you're filing an issue against something we +support. + +**We can NOT help you with issues we can not reproduce.** It is critical that +you explain how to reproduce the issue when filing a report. + +For help, see @{article:Providing Reproduction Steps}. + +**We do NOT support prototype applications.** If you're running into an issue +with a prototype application, you're on your own. For more information about +prototype applications, see @{article:User Guide: Prototype Applications}. + +**We do NOT support third-party packages or instructions.** If you installed +Phorge (or configured some aspect of it) using a third-party package or by +following a third-party guide (like a blog post), we can not help you. +Phorge changes quickly and third-party information is unreliable and often +falls out of date. Contact the maintainer of the package or guide you used, +or reinstall following the upstream instructions. + +**We do NOT support custom code development or third-party libraries.** If +you're writing an extension, you're on your own. We provide some documentation, +but can not help you with extension or library development. If you downloaded a +library from somewhere, contact the library maintainer. + +**We do NOT support bizarre environments.** If your issue is specific to an +unusual installation environment, we generally will not help you find a +workaround. Install Phorge in a normal environment instead. Examples of +unusual environments are shared hosts, nontraditional hosts (gaming consoles, +storage appliances), and hosts with unusually tight resource constraints. The +vast majority of users run Phorge in normal environments (modern computers +with root access) and these are the only environments we support. + +Otherwise, if you're having an issue with a supported first-party application +and followed the upstream install instructions on a normal computer, we're happy +to try to help. + + +Getting More Information +======================== + +For some issues, there are places you can check for more information. This may +help you resolve the issue yourself. Even if it doesn't, this information can +help us figure out and resolve an issue. + + - For issues with `arc` or any other command-line script, you can get more + details about what the script is doing by adding the `--trace` flag. + - For issues with Phorge, check your webserver error logs. + - For Apache, this is often `/var/log/httpd/error.log`, or + `/var/log/apache2/error.log` or similar. + - For nginx, check both the nginx and php-fpm logs. + - For issues with the UI, check the Javascript error console in your web + browser. + - Some other things, like daemons, have their own debug flags or + troubleshooting steps. Check the documentation for information on + troubleshooting. Adjusting settings or enabling debugging modes may give + you more information about the issue. + + +Reproducibility +=============== + +The most important part of your report content is instructions on how to +reproduce the issue. What did you do? If you do it again, does it still break? +Does it depend on a specific browser? Can you reproduce the issue on +a fresh, unmodified Phorge instance? + +It is nearly impossible for us to resolve many issues if we can not reproduce +them. We will not accept reports which do not contain the information required +to reproduce problems. + +For help, see @{article:Providing Reproduction Steps}. + + +File a Bug Report +================= + +If you're up to date, have collected information about the problem, and have +the best reproduction instructions you can come up with, you're ready +to file a report. + +It is **particularly critical** that you include reproduction steps. + +You can file a report [[ https://we.phorge.it/maniphest/task/edit/form/2/ | on this instance]]. + + +Next Steps +========== + +Continue by: + + - reading general support information in @{article:Support Resources}; or + - returning to the @{article:Contributor Introduction}. diff --git a/src/docs/tech/celerity.diviner b/src/docs/contributor/celerity.diviner similarity index 99% rename from src/docs/tech/celerity.diviner rename to src/docs/contributor/celerity.diviner index 8501b1b536..a5706198d3 100644 --- a/src/docs/tech/celerity.diviner +++ b/src/docs/contributor/celerity.diviner @@ -1,62 +1,62 @@ @title Celerity Technical Documentation -@group celerity +@group developer Technical overview of the Celerity system. = Overview = Celerity is a static resource (CSS and JS) management system, which handles: - Keeping track of which resources a page needs. - Generating URIs for the browser to access resources. - Managing dependencies between resources. - Packaging resources into fewer HTTP requests for performance. - Preprocessing resources (e.g., stripping comments and whitespace). - Delivering resources and managing resource cache lifetimes. - Interfacing with the client to manage resources. Celerity is an outgrowth of the //Haste// system at Facebook. You can find more information about Celerity here: - @{article:Things You Should Do Soon: Static Resources} describes the history and context of the system and the problems it solves. - @{article:Adding New CSS and JS} provides a developer guide to using Celerity. = Class Relationships = Celerity's primary API is @{function:require_celerity_resource}, which marks a resource for inclusion when a response is rendered (e.g., when the HTML page is generated, or when the response to an Ajax request is built). For instance, if you use a CSS class like "widget-view", you must ensure the appropriate CSS is included by calling `require_celerity_resource('widget-view-css')` (or similar), at your use site. This function uses @{class:CelerityAPI} to access the active @{class:CelerityStaticResourceResponse} and tells it that it needs to include the resource later, when the response actually gets built. (This layer of indirection provides future-proofing against certain complex situations Facebook eventually encountered). When the time comes to render the response, the page renderer uses @{class:CelerityAPI} to access the active @{class:CelerityStaticResourceResponse} and requests that it render out appropriate references to CSS and JS resources. It uses @{class:CelerityResourceMap} to determine the dependencies for the requested resources (so you only have to explicitly include what you're actually using, and not all of its dependencies) and any packaging rules (so it may be able to generate fewer resource requests, improving performance). It then generates `