diff --git a/src/docs/book/phabricator.book b/src/docs/book/phabricator.book index ecac4a6ba..c4b574cc6 100644 --- a/src/docs/book/phabricator.book +++ b/src/docs/book/phabricator.book @@ -1,19 +1,21 @@ { "name" : "phabdev", "title" : "Phabricator Technical Documentation", "short" : "Phabricator Tech Docs", "root" : "../../../", "uri.source" : "https://secure.phabricator.com/diffusion/P/browse/master/%f$%l", "rules" : { - "(\\.php$)" : "DivinerPHPAtomizer" + "(\\.php$)" : "DivinerPHPAtomizer", + "(\\.diviner$)" : "DivinerArticleAtomizer" }, "exclude" : [ "(^externals/)", "(^scripts/)", "(^support/)", - "(^resources/)" + "(^resources/)", + "(^src/docs/user/)" ], "groups" : { } } diff --git a/src/docs/book/user.book b/src/docs/book/user.book index 35fb7fed1..5c22e2535 100644 --- a/src/docs/book/user.book +++ b/src/docs/book/user.book @@ -1,45 +1,48 @@ { "name" : "phabricator", "title" : "Phabricator User Documentation", "short" : "Phabricator User Docs", "root" : "../../../", "uri.source" : "https://secure.phabricator.com/diffusion/P/browse/master/%f$%l", "rules" : { "(\\.diviner$)" : "DivinerArticleAtomizer" }, "exclude" : [ "(^externals/)", + "(^webroot/rsrc/externals/)", "(^scripts/)", - "(^support/)" + "(^support/)", + "(^resources/)", + "(^src/docs/tech/)" ], "groups" : { "intro" : { "name" : "Introduction" }, "config" : { "name" : "Configuration" }, "userguide" : { "name" : "Application User Guides" }, "differential" : { "name" : "Differential (Code Review)" }, "diffusion" : { "name" : "Diffusion (Repository Browser)" }, "maniphest" : { "name" : "Maniphest (Task Tracking)" }, "slowvote" : { "name" : "Slowvote (Polls)" }, "herald" : { "name" : "Herald (Notifications)" }, "phriction" : { "name" : "Phriction (Wiki)" } } } diff --git a/src/docs/technical/celerity.diviner b/src/docs/tech/celerity.diviner similarity index 100% rename from src/docs/technical/celerity.diviner rename to src/docs/tech/celerity.diviner diff --git a/src/docs/technical/chatbot.diviner b/src/docs/tech/chatbot.diviner similarity index 100% rename from src/docs/technical/chatbot.diviner rename to src/docs/tech/chatbot.diviner diff --git a/src/docs/technical/conduit.diviner b/src/docs/tech/conduit.diviner similarity index 98% rename from src/docs/technical/conduit.diviner rename to src/docs/tech/conduit.diviner index 8a9997693..b64f086c0 100644 --- a/src/docs/technical/conduit.diviner +++ b/src/docs/tech/conduit.diviner @@ -1,57 +1,57 @@ @title Conduit Technical Documentation @group conduit Technical overview of the Conduit API. = Overview = Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on the internet. Theoretically, it provides an API to Phabricator so external scripts (including scripts written in other languages) can interface with the applications in the Phabricator suite. It technically does this, sort of, but it is unstable and incomplete so you should keep your expectations very low if you choose to build things on top of it. NOTE: Hopefully, this should improve over time, but making Conduit more robust isn't currently a major project priority because there isn't much demand for it outside of internal scripts. If you want to use Conduit to build things on top of Phabricator, let us know so we can adjust priorities. Conduit provides an authenticated HTTP API for Phabricator. It is informal and extremely simple: you post a JSON blob and you get a JSON blob back. You can access Conduit in PHP with @{class@libphutil:ConduitClient}, or in any language by executing ##arc call-conduit method## (see ##arc help call-conduit## for more information). You can see and test available methods at ##/conduit/## in the web interface. Arcanist is implemented using Conduit, and @{class:PhabricatorIRCBot} is intended as a practical example of how to write a program which interfaces with Phabricator over Conduit. = Class Relationships = The primary Conduit workflow is exposed at ##/api/##, which routes to @{class:PhabricatorConduitAPIController}. This controller builds a @{class:ConduitAPIRequest} representing authentication information and POST parameters, instantiates an appropriate subclass of @{class:ConduitAPIMethod}, and passes the request to it. Subclasses of @{class:ConduitAPIMethod} implement the actual methods which Conduit exposes. Conduit calls which fail throw @{class:ConduitException}, which the controller handles. There is a web interface for viewing and testing Conduit called the "Conduit Console", implemented by @{class:PhabricatorConduitConsoleController} at ##/conduit/##. A log of connections and calls is stored by @{class:PhabricatorConduitConnectionLog} and @{class:PhabricatorConduitMethodCallLog}, and can be accessed on the web via @{class:PhabricatorConduitLogController} at ##/conduit/log/##. Conduit provides a token-based handshake mechanism used by ##arc install-certificate## at ##/conduit/token/##, implemented by @{class:PhabricatorConduitTokenController} which stores generated tokens using -@{class:PhabricatorConduitCertificateToken}. \ No newline at end of file +@{class:PhabricatorConduitCertificateToken}. diff --git a/src/docs/technical/files.diviner b/src/docs/tech/files.diviner similarity index 98% rename from src/docs/technical/files.diviner rename to src/docs/tech/files.diviner index 71ccf1e7e..a7fccfd98 100644 --- a/src/docs/technical/files.diviner +++ b/src/docs/tech/files.diviner @@ -1,39 +1,39 @@ @title File Storage Technical Documentation @group filestorage Phabricator file storage details. = Overview = Phabricator has a simple, general-purpose file storage system with configurable storage backends that allows you to choose where files are stored. For a user guide, see @{article:Configuring File Storage}. = Class Relationships = @{class:PhabricatorFile} holds file metadata (name, author, phid), including an identifier for a @{class:PhabricatorFileStorageEngine} where the actual file data is stored, and a data handle which identifies the data within that storage engine. When writing data, a @{class:PhabricatorFileStorageEngineSelector} is instantiated (by default, @{class:PhabricatorDefaultFileStorageEngineSelector}, but you can change this by setting the ##storage.engine-selector## key in your configuration). The selector returns a list of satisfactory @{class:PhabricatorFileStorageEngine}s, in order of preference. For instance, suppose the user is uploading a picture. The upload pipeline would instantiate the configured selector, which might return a @{class:PhabricatorMySQLFileStorageEngine} and a @{class:PhabricatorLocalDiskFileStorageEngine}, indicating that the picture may be stored in either storage engine but MySQL is preferred. If a given storage engine fails to perform the write, it will fall back to the next engine. = Adding New Storage Engines = To add a new storage engine, extend @{class:PhabricatorFileStorageEngine}. In order to make files actually get written to it, you also need to extend @{class:PhabricatorFileStorageEngineSelector}, provide an implementation which selects your storage engine for whatever files you want to store there, and then configure Phabricator to use your selector by setting -##storage.engine-selector##. \ No newline at end of file +##storage.engine-selector##. diff --git a/src/docs/configuration/configuration_guide.diviner b/src/docs/user/configuration/configuration_guide.diviner similarity index 100% rename from src/docs/configuration/configuration_guide.diviner rename to src/docs/user/configuration/configuration_guide.diviner diff --git a/src/docs/configuration/configuring_accounts_and_registration.diviner b/src/docs/user/configuration/configuring_accounts_and_registration.diviner similarity index 100% rename from src/docs/configuration/configuring_accounts_and_registration.diviner rename to src/docs/user/configuration/configuring_accounts_and_registration.diviner diff --git a/src/docs/configuration/configuring_backups.diviner b/src/docs/user/configuration/configuring_backups.diviner similarity index 100% rename from src/docs/configuration/configuring_backups.diviner rename to src/docs/user/configuration/configuring_backups.diviner diff --git a/src/docs/configuration/configuring_file_storage.diviner b/src/docs/user/configuration/configuring_file_storage.diviner similarity index 98% rename from src/docs/configuration/configuring_file_storage.diviner rename to src/docs/user/configuration/configuring_file_storage.diviner index 916fa0bd0..66bcb7df7 100644 --- a/src/docs/configuration/configuring_file_storage.diviner +++ b/src/docs/user/configuration/configuring_file_storage.diviner @@ -1,105 +1,105 @@ @title Configuring File Storage @group config Setup how Phabricator will store files. = Overview = Phabricator allows users to upload files, and several applications use file storage (for instance, Maniphest allows you to attach files to tasks). You can configure several different storage systems: - you can store data in MySQL: this is the easiest to set up, but doesn't scale well; - you can store data on local disk: this is also easy to set up but won't scale to multiple web frontends without NFS; - or you can build a custom storage engine. By default, Phabricator is configured to store files up to 1MB in MySQL, and reject files larger than 1MB. It is recommended you set up local disk storage for files larger than 1MB. This should be sufficient for most installs. If you have a larger install or more unique requirements, you may want to customize this further. For technical documentation (including instructions on building custom storage engines) see @{article:File Storage Technical Documentation}. You don't have to fully configure this immediately, the defaults are okay until you need to upload larger files and it's relatively easy to port files between storage engines later. = Storage Engines = Builtin storage engines and information on how to configure them. == MySQL == - **Pros**: Fast, no setup required. - **Cons**: Storing files in a database is a classic bad idea. Does not scale well. Maximum file size is limited. MySQL storage is configured by default, for files up to (just under) 1MB. You can configure it with these keys: - ##storage.mysql-engine.max-size##: Change the filesize limit. Set to 0 to disable. For most installs, it is recommended you configure local disk storage below, and then either leave this as is or disable it, depending on how upset you feel about putting files in a database. == Local Disk == - **Pros**: Very simple. Almost no setup required. - **Cons**: Doesn't scale to multiple web frontends without NFS. For most installs, it is **strongly recommended** that you configure local disk storage. To do this, set the configuration key: - ##storage.local-disk.path##: Set to some writable directory on local disk. Make that directory. You're done. == Amazon S3 == - **Pros**: Scales well. - **Cons**: More complicated and expensive than other approaches. To enable file storage in S3, set these key: - ##amazon-s3.access-key## Your AWS access key. - ##amazon-s3.secret-key## Your AWS secret key. - ##storage.s3.bucket## S3 bucket name where files should be stored. == Custom Engine == For details about writing a custom storage engine, see @{article:File Storage Technical Documentation}. = Testing Storage Engines = You can test that things are correctly configured by going to the Files application (##/file/##) and uploading files. = Migrating Files Between Engines = If you want to move files between storage engines, you can use the `bin/files` 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 If that works properly, you can then migrate everything: phabricator/ $ ./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. = Next Steps = Continue by: - configuring file size upload limits with @{article:Configuring File Upload Limits}; or - - returning to the @{article:Configuration Guide}. \ No newline at end of file + - returning to the @{article:Configuration Guide}. diff --git a/src/docs/configuration/configuring_file_upload_limits.diviner b/src/docs/user/configuration/configuring_file_upload_limits.diviner similarity index 100% rename from src/docs/configuration/configuring_file_upload_limits.diviner rename to src/docs/user/configuration/configuring_file_upload_limits.diviner diff --git a/src/docs/configuration/configuring_inbound_email.diviner b/src/docs/user/configuration/configuring_inbound_email.diviner similarity index 100% rename from src/docs/configuration/configuring_inbound_email.diviner rename to src/docs/user/configuration/configuring_inbound_email.diviner diff --git a/src/docs/configuration/configuring_outbound_email.diviner b/src/docs/user/configuration/configuring_outbound_email.diviner similarity index 100% rename from src/docs/configuration/configuring_outbound_email.diviner rename to src/docs/user/configuration/configuring_outbound_email.diviner diff --git a/src/docs/configuration/managing_daemons.diviner b/src/docs/user/configuration/managing_daemons.diviner similarity index 100% rename from src/docs/configuration/managing_daemons.diviner rename to src/docs/user/configuration/managing_daemons.diviner diff --git a/src/docs/configuration/troubleshooting_https.diviner b/src/docs/user/configuration/troubleshooting_https.diviner similarity index 100% rename from src/docs/configuration/troubleshooting_https.diviner rename to src/docs/user/configuration/troubleshooting_https.diviner diff --git a/src/docs/contributing/contrib_intro.diviner b/src/docs/user/contributing/contrib_intro.diviner similarity index 100% rename from src/docs/contributing/contrib_intro.diviner rename to src/docs/user/contributing/contrib_intro.diviner diff --git a/src/docs/contributing/general_coding_standards.diviner b/src/docs/user/contributing/general_coding_standards.diviner similarity index 100% rename from src/docs/contributing/general_coding_standards.diviner rename to src/docs/user/contributing/general_coding_standards.diviner diff --git a/src/docs/contributing/internationalization.diviner b/src/docs/user/contributing/internationalization.diviner similarity index 100% rename from src/docs/contributing/internationalization.diviner rename to src/docs/user/contributing/internationalization.diviner diff --git a/src/docs/contributing/javascript_coding_standards.diviner b/src/docs/user/contributing/javascript_coding_standards.diviner similarity index 100% rename from src/docs/contributing/javascript_coding_standards.diviner rename to src/docs/user/contributing/javascript_coding_standards.diviner diff --git a/src/docs/contributing/php_coding_standards.diviner b/src/docs/user/contributing/php_coding_standards.diviner similarity index 100% rename from src/docs/contributing/php_coding_standards.diviner rename to src/docs/user/contributing/php_coding_standards.diviner diff --git a/src/docs/developer/adding_new_css_and_js.diviner b/src/docs/user/developer/adding_new_css_and_js.diviner similarity index 100% rename from src/docs/developer/adding_new_css_and_js.diviner rename to src/docs/user/developer/adding_new_css_and_js.diviner diff --git a/src/docs/developer/darkconsole.diviner b/src/docs/user/developer/darkconsole.diviner similarity index 100% rename from src/docs/developer/darkconsole.diviner rename to src/docs/user/developer/darkconsole.diviner diff --git a/src/docs/developer/database.diviner b/src/docs/user/developer/database.diviner similarity index 100% rename from src/docs/developer/database.diviner rename to src/docs/user/developer/database.diviner diff --git a/src/docs/developer/n_plus_one.diviner b/src/docs/user/developer/n_plus_one.diviner similarity index 100% rename from src/docs/developer/n_plus_one.diviner rename to src/docs/user/developer/n_plus_one.diviner diff --git a/src/docs/developer/phabricator_code_layout.diviner b/src/docs/user/developer/phabricator_code_layout.diviner similarity index 100% rename from src/docs/developer/phabricator_code_layout.diviner rename to src/docs/user/developer/phabricator_code_layout.diviner diff --git a/src/docs/developer/rendering_html.diviner b/src/docs/user/developer/rendering_html.diviner similarity index 100% rename from src/docs/developer/rendering_html.diviner rename to src/docs/user/developer/rendering_html.diviner diff --git a/src/docs/developer/running_builtin_php_webserver.diviner b/src/docs/user/developer/running_builtin_php_webserver.diviner similarity index 100% rename from src/docs/developer/running_builtin_php_webserver.diviner rename to src/docs/user/developer/running_builtin_php_webserver.diviner diff --git a/src/docs/developer/unit_tests.diviner b/src/docs/user/developer/unit_tests.diviner similarity index 100% rename from src/docs/developer/unit_tests.diviner rename to src/docs/user/developer/unit_tests.diviner diff --git a/src/docs/developer/using_edges.diviner b/src/docs/user/developer/using_edges.diviner similarity index 100% rename from src/docs/developer/using_edges.diviner rename to src/docs/user/developer/using_edges.diviner diff --git a/src/docs/developer/using_oauthserver.diviner b/src/docs/user/developer/using_oauthserver.diviner similarity index 100% rename from src/docs/developer/using_oauthserver.diviner rename to src/docs/user/developer/using_oauthserver.diviner diff --git a/src/docs/feedback.diviner b/src/docs/user/feedback.diviner similarity index 100% rename from src/docs/feedback.diviner rename to src/docs/user/feedback.diviner diff --git a/src/docs/flavortext/about_flavor_text.diviner b/src/docs/user/flavortext/about_flavor_text.diviner similarity index 100% rename from src/docs/flavortext/about_flavor_text.diviner rename to src/docs/user/flavortext/about_flavor_text.diviner diff --git a/src/docs/flavortext/javascript_object_array.diviner b/src/docs/user/flavortext/javascript_object_array.diviner similarity index 100% rename from src/docs/flavortext/javascript_object_array.diviner rename to src/docs/user/flavortext/javascript_object_array.diviner diff --git a/src/docs/flavortext/javascript_pitfalls.diviner b/src/docs/user/flavortext/javascript_pitfalls.diviner similarity index 100% rename from src/docs/flavortext/javascript_pitfalls.diviner rename to src/docs/user/flavortext/javascript_pitfalls.diviner diff --git a/src/docs/flavortext/php_pitfalls.diviner b/src/docs/user/flavortext/php_pitfalls.diviner similarity index 100% rename from src/docs/flavortext/php_pitfalls.diviner rename to src/docs/user/flavortext/php_pitfalls.diviner diff --git a/src/docs/flavortext/please_please_please.diviner b/src/docs/user/flavortext/please_please_please.diviner similarity index 100% rename from src/docs/flavortext/please_please_please.diviner rename to src/docs/user/flavortext/please_please_please.diviner diff --git a/src/docs/flavortext/project_history.diviner b/src/docs/user/flavortext/project_history.diviner similarity index 100% rename from src/docs/flavortext/project_history.diviner rename to src/docs/user/flavortext/project_history.diviner diff --git a/src/docs/flavortext/recommendations_on_branching.diviner b/src/docs/user/flavortext/recommendations_on_branching.diviner similarity index 100% rename from src/docs/flavortext/recommendations_on_branching.diviner rename to src/docs/user/flavortext/recommendations_on_branching.diviner diff --git a/src/docs/flavortext/recommendations_on_revision_control.diviner b/src/docs/user/flavortext/recommendations_on_revision_control.diviner similarity index 100% rename from src/docs/flavortext/recommendations_on_revision_control.diviner rename to src/docs/user/flavortext/recommendations_on_revision_control.diviner diff --git a/src/docs/flavortext/soon_static_resources.diviner b/src/docs/user/flavortext/soon_static_resources.diviner similarity index 100% rename from src/docs/flavortext/soon_static_resources.diviner rename to src/docs/user/flavortext/soon_static_resources.diviner diff --git a/src/docs/flavortext/things_you_should_do_now.diviner b/src/docs/user/flavortext/things_you_should_do_now.diviner similarity index 100% rename from src/docs/flavortext/things_you_should_do_now.diviner rename to src/docs/user/flavortext/things_you_should_do_now.diviner diff --git a/src/docs/flavortext/things_you_should_do_soon.diviner b/src/docs/user/flavortext/things_you_should_do_soon.diviner similarity index 100% rename from src/docs/flavortext/things_you_should_do_soon.diviner rename to src/docs/user/flavortext/things_you_should_do_soon.diviner diff --git a/src/docs/flavortext/writing_reviewable_code.diviner b/src/docs/user/flavortext/writing_reviewable_code.diviner similarity index 99% rename from src/docs/flavortext/writing_reviewable_code.diviner rename to src/docs/user/flavortext/writing_reviewable_code.diviner index 80e381e5d..687f7233a 100644 --- a/src/docs/flavortext/writing_reviewable_code.diviner +++ b/src/docs/user/flavortext/writing_reviewable_code.diviner @@ -1,163 +1,163 @@ @title Writing Reviewable Code @group flavortext Project recommendations on how to structure changes. This document is purely advisory. Phabricator 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: - 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 so small that they are meaningless on their own. - There should be a one-to-one mapping between ideas and commits: each commit should build one idea, and each idea should be implemented by one commit. - Turn large commits into small commits by dividing large problems into smaller problems and solving the small problems one at a time. - Write sensible commit messages. = Many Small Commits = Small, simple commits are generally better than large, complex commits. They are easier to understand, easier to test, and easier to review. The complexity of understanding, testing and reviewing a change often increases faster than its size: ten 200-line changes each doing one thing are often far easier to understand than one 2,000 line change doing ten things. Splitting a change which does many things into smaller changes which each do only one thing can decrease the total complexity associated with accomplishing the same goal. Each commit should do one thing. Generally, this means that you should separate distinct changes into different commits when developing. For example, if you're developing a feature and run into a preexisting bug, stash or checkpoint your change, check out a clean HEAD/tip, fix the bug in one change, and then merge/rebase your new feature on top of your bugfix so that you have two changes, each with one idea ("add feature x", "fix a bug in y"), not one change with two ideas ("add feature x and fix a bug in y"). (In Git, you can do this easily with local feature branches and commands like `git rebase`, `git rebase -i`, and `git stash`, or with merges. In Mercurial, you can use bookmarks or the queues extension. In SVN, there are few builtin tools, but you can use multiple working copies or treat Differential like a stash you access with `arc patch`.) Even changes like fixing style problems should ideally be separated: they're accomplishing a different goal. And it is far easier to review one 300-line change which "converts tabs to spaces" plus one 30-line change which "implements feature z" than one 330-line change which "implements feature z and also converts a bunch of tabs to spaces". Similarly, break related but complex changes into smaller, simpler components. Here's a ridiculous analogy: if you're adding a new house, don't make one 5,000-line change which adds the whole house in one fell sweep. Split it apart into smaller steps which are each easy to understand: start with the foundation, then build the frame, etc. If you decided to dig the foundation with a shovel or build the frame out of cardboard, it's both easier to miss and harder to correct if the decisions are buried in 5,000 lines of interior design and landscaping. Do it one piece at a time, providing enough context that the larger problem can be understood but accomplishing no more with each step than you need to in order for it to stand on its own. The minimum size of a change should be a complete implementation of the simplest subproblem which works on its own and expresses an entire idea, not just part of an idea. You could mechanically split a 1,000-line change into ten 100-line changes by choosing lines at random, but none of the individual changes would 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. See @{article:Differential User Guide: Large Changes} for information about reviewing big checkins. = Write Sensible Commit Messages = There are lots of resources for this on the internet. All of them say pretty much the same thing; this one does too. The single most important thing is: **commit messages should explain //why// you are making the change**. Differential attempts to encourage the construction of sensible commit messages, but can only enforce structure, not content. Structurally, commit messages should probably: - Have a title, briefly describing the change in one line. - Have a summary, describing the change in more detail. - Maybe have some other fields. The content is far more important than the structure. In particular, the summary should explain //why// you're making the change and //why// you're choosing the implementation you're choosing. The //what// of the change is generally well-explained by the change itself. For example, this is obviously an awful commit message: COUNTEREXAMPLE fix a bug But this one is almost as bad: COUNTEREXAMPLE Allow dots in usernames Change the regexps so usernames can have dots in them. This is better than nothing but just summarizes information which can be inferred from the text of the diff. Instead, you should provide context and explain why you're making the change you're making, and why it's the right one: lang=txt Allow dots in usernames to support Google and LDAP auth To prevent nonsense, usernames are currently restricted to A-Z0-9. Now that we have Google and LDAP auth, a couple of installs want to allow "." too since they have schemes like "abraham.lincoln@mycompany.com" (see Tnnn). There are no technical reasons not to do this, so I opened up the regexps a bit. We could mostly open this up more but I figured I'd wait until someone asks before allowing "ke$ha", etc., because I personally find such names distasteful and offensive. This information can not be extracted from the change itself, and is much more useful for the reviewer and for anyone trying to understand the change after the fact. An easy way to explain //why// is to reference other objects (bugs/issues/revisions) which motivate the change. Differential also includes a "Test Plan" field which is required by default. There is a detailed description of this field in @{article:Differential User Guide: Test Plans}. You can make it optional or disable it in the configuration, but consider adopting it. Having this information can be particularly helpful for reviewers. Some things that people sometimes feel strongly about but which are probably not really all that important in commit messages include: - If/where text is wrapped. - Maximum length of the title. - Whether there should be a period or not in the title. - Use of voice/tense, e.g. "fix"/"add" vs "fixes"/"adds". - Other sorts of pedantry not related to getting the context and 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 guidelines at your organization if you prefer, but getting the //why// into the message is the most important part. = Next Steps = Continue by: - reading recommendations on structuring revision control with @{article:Recommendations on Revision Control}; or - reading recommendations on structuring branches with - @{article:Recommendations on Branching}. \ No newline at end of file + @{article:Recommendations on Branching}. diff --git a/src/docs/installation_guide.diviner b/src/docs/user/installation_guide.diviner similarity index 100% rename from src/docs/installation_guide.diviner rename to src/docs/user/installation_guide.diviner diff --git a/src/docs/introduction.diviner b/src/docs/user/introduction.diviner similarity index 100% rename from src/docs/introduction.diviner rename to src/docs/user/introduction.diviner diff --git a/src/docs/userguide/advanced_configuration.diviner b/src/docs/user/userguide/advanced_configuration.diviner similarity index 100% rename from src/docs/userguide/advanced_configuration.diviner rename to src/docs/user/userguide/advanced_configuration.diviner diff --git a/src/docs/userguide/arcanist.diviner b/src/docs/user/userguide/arcanist.diviner similarity index 100% rename from src/docs/userguide/arcanist.diviner rename to src/docs/user/userguide/arcanist.diviner diff --git a/src/docs/userguide/arcanist_commit_ranges.diviner b/src/docs/user/userguide/arcanist_commit_ranges.diviner similarity index 100% rename from src/docs/userguide/arcanist_commit_ranges.diviner rename to src/docs/user/userguide/arcanist_commit_ranges.diviner diff --git a/src/docs/userguide/arcanist_coverage.diviner b/src/docs/user/userguide/arcanist_coverage.diviner similarity index 99% rename from src/docs/userguide/arcanist_coverage.diviner rename to src/docs/user/userguide/arcanist_coverage.diviner index 0f28258d8..9b3784074 100644 --- a/src/docs/userguide/arcanist_coverage.diviner +++ b/src/docs/user/userguide/arcanist_coverage.diviner @@ -1,69 +1,69 @@ @title Arcanist User Guide: Code Coverage @group userguide Explains code coverage features in Arcanist and Phabricator. 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 the @{article:Arcanist User Guide}. Before you can configure coverage features, you must set up unit test integration. For instructions, see @{article:Arcanist User Guide: Configuring a New Project} and @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}. = Using Coverage Features = If your project has unit tests with coverage integration (see below for instructions on setting it up), you can use "arc" to show coverage reports. For example: arc unit --detailed-coverage src/some/file.php Depending on how your test engine is configured, this will run tests relevant 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 libphutil, Arcanist and Phabricator = If you're contributing, libphutil, Arcanist and Phabricator support coverage if you install Xdebug: http://xdebug.org/ It should be sufficient to correctly install Xdebug; coverage information will be automatically enabled. = Building Coverage Support = To add coverage support to a unit test engine, just call ##setCoverage()## when building @{class@arcanist:ArcanistUnitTestResult} objects. Provide a map of file names (relative to the working copy root) to coverage report strings. Coverage report strings look like this: NNNNNCCCNNNNNNNNCCCCCCNNNUUUNNNNN Each line in the file is represented by a character. Valid characters are: - **N** Not executable. This is a comment or whitespace which should be ignored when computing test coverage. - **C** Covered. This line has test coverage. - **U** Uncovered. This line is executable but has no test coverage. - **X** Unreachable. If your coverage analysis can detect unreachable code, you can report it here. This format is intended to be as simple as possible. A valid coverage result might look like this: array( 'src/example.php' => 'NNCNNNCNUNNNUNUNUNUNUNC', 'src/other.php' => 'NNUNNNUNCNNNUNUNCNCNCNU', ); You may also want to filter coverage information to the paths passed to the unit test engine. See @{class@arcanist:ArcanistPhutilTestCase} and @{class@arcanist:PhutilUnitTestEngine} for an example of coverage integration -in PHP using Xdebug. \ No newline at end of file +in PHP using Xdebug. diff --git a/src/docs/userguide/arcanist_diff.diviner b/src/docs/user/userguide/arcanist_diff.diviner similarity index 100% rename from src/docs/userguide/arcanist_diff.diviner rename to src/docs/user/userguide/arcanist_diff.diviner diff --git a/src/docs/userguide/arcanist_extending_lint.diviner b/src/docs/user/userguide/arcanist_extending_lint.diviner similarity index 93% rename from src/docs/userguide/arcanist_extending_lint.diviner rename to src/docs/user/userguide/arcanist_extending_lint.diviner index a4966aeaa..9f4e08e1b 100644 --- a/src/docs/userguide/arcanist_extending_lint.diviner +++ b/src/docs/user/userguide/arcanist_extending_lint.diviner @@ -1,102 +1,102 @@ @title Arcanist User Guide: Customizing Existing Linters @group userguide Explains how to customize existing linters. 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 the @{article:Arcanist User Guide}. This guide explains how to refine lint behavior. To configure lint in the first place, see @{article:Arcanist User Guide: Configuring a New Project} and @{article:Arcanist User Guide: Lint}. = Overview = Arcanist ships with a number of linters which you may want to reuse in whole or in part in other projects. This document explains how to customize existing linters for use in new engines. First, you should set up an engine by following the instructions in @{article:Arcanist User Guide: Lint} and possibly @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}. Then, follow this guide to customize linters. = General Guidelines = You should customize linters by configuring or composing them, not by extending them -- their implementations are not necessarily stable. If a linter's configuration options aren't flexible enough to meet your needs, sending a patch which improves its configurability is better than one that makes it nonfinal. = Changing Rule Severities = By default, most linters raise lint messages as errors. You may want to reduce the severity of some messages (e.g., reduce errors to warnings). Do this by calling ##setCustomSeverityMap()##: $linter = new ArcanistTextLinter(); // Change "missing newline at end of file" message from error to warning. $linter->setCustomSeverityMap( array( ArcanistTextLinter::LINT_EOF_NEWLINE => ArcanistLintSeverity::SEVERITY_WARNING, )); See @{class@arcanist:ArcanistLintSeverity} for a list of available severity constants. = Disabling Rules = To disable rules entirely, set their severities to ##SEVERITY_DISABLED##: $linter = new ArcanistTextLinter(); // Disable "Tab Literal" message. $linter->setCustomSeverityMap( array( ArcanistTextLinter::LINT_TAB_LITERAL => ArcanistLintSeverity::SEVERITY_DISABLED, )); = Running Multiple Rulesets = If you want to run the same linter on different types of files but vary the configuration based on the file type, just instantiate it twice and configure each instance appropriately. For instance, this will enforce different column widths on different languages: $linters = array(); - // Warn on JS/CSS lines longer than 80 columns. + // Warn on JS/CSS lines longer than 80 columns. $linters['TextLinter80Col'] = id(new ArcanistTextLinter()) - ->setPaths(preg_grep('/\.(js|css)$/', $paths)); + ->setPaths(preg_grep('/\.(js|css)$/', $paths)); - // Warn on Java lines longer than 120 columns. + // Warn on Java lines longer than 120 columns. $linters['TextLinter120Col'] = id(new ArcanistTextLinter()) - ->setMaxLineLength(120) - ->setPaths(preg_grep('/\.(java)$/', $paths)); + ->setMaxLineLength(120) + ->setPaths(preg_grep('/\.(java)$/', $paths)); // ... return $linters; = Customizing Specific Linters = Some linters are specifically customizable or configurable. Some common options are documented here, consult class documentation for complete information. == ArcanistTextLinter == - Use ##setMaxLineLength()## to change the 80-column warning to something else. == ArcanistXHPASTLinter == - Use ##lint.xhpast.naminghook## in ##.arcconfig## to override naming convention rules. See @{class@arcanist:ArcanistXHPASTLintNamingHook} for details, and @{class:PhabricatorSymbolNameLinter} for an example. - Use ##getXHPASTTreeForPath()## to reuse the AAST in other linters. diff --git a/src/docs/userguide/arcanist_hooks.diviner b/src/docs/user/userguide/arcanist_hooks.diviner similarity index 100% rename from src/docs/userguide/arcanist_hooks.diviner rename to src/docs/user/userguide/arcanist_hooks.diviner diff --git a/src/docs/userguide/arcanist_lint.diviner b/src/docs/user/userguide/arcanist_lint.diviner similarity index 100% rename from src/docs/userguide/arcanist_lint.diviner rename to src/docs/user/userguide/arcanist_lint.diviner diff --git a/src/docs/userguide/arcanist_lint_unit.diviner b/src/docs/user/userguide/arcanist_lint_unit.diviner similarity index 100% rename from src/docs/userguide/arcanist_lint_unit.diviner rename to src/docs/user/userguide/arcanist_lint_unit.diviner diff --git a/src/docs/userguide/arcanist_mac_os_x.diviner b/src/docs/user/userguide/arcanist_mac_os_x.diviner similarity index 100% rename from src/docs/userguide/arcanist_mac_os_x.diviner rename to src/docs/user/userguide/arcanist_mac_os_x.diviner diff --git a/src/docs/userguide/arcanist_new_project.diviner b/src/docs/user/userguide/arcanist_new_project.diviner similarity index 100% rename from src/docs/userguide/arcanist_new_project.diviner rename to src/docs/user/userguide/arcanist_new_project.diviner diff --git a/src/docs/userguide/arcanist_quick_start.diviner b/src/docs/user/userguide/arcanist_quick_start.diviner similarity index 100% rename from src/docs/userguide/arcanist_quick_start.diviner rename to src/docs/user/userguide/arcanist_quick_start.diviner diff --git a/src/docs/userguide/arcanist_windows.diviner b/src/docs/user/userguide/arcanist_windows.diviner similarity index 100% rename from src/docs/userguide/arcanist_windows.diviner rename to src/docs/user/userguide/arcanist_windows.diviner diff --git a/src/docs/userguide/audit.diviner b/src/docs/user/userguide/audit.diviner similarity index 100% rename from src/docs/userguide/audit.diviner rename to src/docs/user/userguide/audit.diviner diff --git a/src/docs/userguide/differential.diviner b/src/docs/user/userguide/differential.diviner similarity index 100% rename from src/docs/userguide/differential.diviner rename to src/docs/user/userguide/differential.diviner diff --git a/src/docs/userguide/differential_faq.diviner b/src/docs/user/userguide/differential_faq.diviner similarity index 100% rename from src/docs/userguide/differential_faq.diviner rename to src/docs/user/userguide/differential_faq.diviner diff --git a/src/docs/userguide/differential_large_changes.diviner b/src/docs/user/userguide/differential_large_changes.diviner similarity index 100% rename from src/docs/userguide/differential_large_changes.diviner rename to src/docs/user/userguide/differential_large_changes.diviner diff --git a/src/docs/userguide/differential_test_plans.diviner b/src/docs/user/userguide/differential_test_plans.diviner similarity index 100% rename from src/docs/userguide/differential_test_plans.diviner rename to src/docs/user/userguide/differential_test_plans.diviner diff --git a/src/docs/userguide/diffusion.diviner b/src/docs/user/userguide/diffusion.diviner similarity index 100% rename from src/docs/userguide/diffusion.diviner rename to src/docs/user/userguide/diffusion.diviner diff --git a/src/docs/userguide/diffusion_symbols.diviner b/src/docs/user/userguide/diffusion_symbols.diviner similarity index 100% rename from src/docs/userguide/diffusion_symbols.diviner rename to src/docs/user/userguide/diffusion_symbols.diviner diff --git a/src/docs/userguide/diviner.diviner b/src/docs/user/userguide/diviner.diviner similarity index 100% rename from src/docs/userguide/diviner.diviner rename to src/docs/user/userguide/diviner.diviner diff --git a/src/docs/userguide/drydock.diviner b/src/docs/user/userguide/drydock.diviner similarity index 66% rename from src/docs/userguide/drydock.diviner rename to src/docs/user/userguide/drydock.diviner index 743c570a8..2ba4f241f 100644 --- a/src/docs/userguide/drydock.diviner +++ b/src/docs/user/userguide/drydock.diviner @@ -1,8 +1,8 @@ @title Drydock User Guide @group userguide Configuring Drydock for machine resource management. = Overview = -NOTE: Drydock is extremely new and not very useful yet. \ No newline at end of file +NOTE: Drydock is extremely new and not very useful yet. diff --git a/src/docs/userguide/events.diviner b/src/docs/user/userguide/events.diviner similarity index 100% rename from src/docs/userguide/events.diviner rename to src/docs/user/userguide/events.diviner diff --git a/src/docs/userguide/external_editor.diviner b/src/docs/user/userguide/external_editor.diviner similarity index 97% rename from src/docs/userguide/external_editor.diviner rename to src/docs/user/userguide/external_editor.diviner index e8de3bfb7..675ed7eb1 100644 --- a/src/docs/userguide/external_editor.diviner +++ b/src/docs/user/userguide/external_editor.diviner @@ -1,51 +1,51 @@ @title User Guide: Configuring an External Editor @group userguide Setting up an external editor to integrate with Diffusion and Differential. = Overview = You can configure a URI handler to allow you to open files from Differential and Diffusion in your preferred text editor. = Configuring Editors = To configure an external editor, go to Settings -> Application Settings -> Display Preferences and set "Editor Link" to a URI pattern (see below). This will enable an "Open in Editor" link in Differential, and an "Edit" button in Diffusion. In general, you'll set this field to something like: lang=uri editor://open/?file=%f Some editors support opening multiple files at once when filenames are separated by spaces. If your editor supports this feature, set "Edit Multiple Files" to "Supported". Otherwise, you can set it to "Not Supported" to disable "Open All" buttons in the interface. == Configuring: TextMate on OS X == TextMate installs a ##txmt://## handler by default, so it's easy to configure this feature if you use TextMate. First, create a local directory with symlinks for each repository callsign. For example, if you're developing Phabricator, it might look like this: /Users/alincoln/editor_links/ $ ls -l ... ARC -> /Users/alincoln/workspace/arcanist/ ... P -> /Users/alincoln/workspace/phabricator/ ... PHU -> /Users/alincoln/workspace/libphutil/ Then set your "Editor Link" to: lang=uri txmt://open/?url=file:///Users/alincoln/editor_links/%r/%f&line=%l == Configuring: Other Editors == General instructions for configuring some other editors and environments can be found here: - http://wiki.nette.org/en/howto-editor-link \ No newline at end of file + http://wiki.nette.org/en/howto-editor-link diff --git a/src/docs/userguide/herald.diviner b/src/docs/user/userguide/herald.diviner similarity index 100% rename from src/docs/userguide/herald.diviner rename to src/docs/user/userguide/herald.diviner diff --git a/src/docs/userguide/jump.diviner b/src/docs/user/userguide/jump.diviner similarity index 100% rename from src/docs/userguide/jump.diviner rename to src/docs/user/userguide/jump.diviner diff --git a/src/docs/userguide/libraries.diviner b/src/docs/user/userguide/libraries.diviner similarity index 100% rename from src/docs/userguide/libraries.diviner rename to src/docs/user/userguide/libraries.diviner diff --git a/src/docs/userguide/mail_rules.diviner b/src/docs/user/userguide/mail_rules.diviner similarity index 100% rename from src/docs/userguide/mail_rules.diviner rename to src/docs/user/userguide/mail_rules.diviner diff --git a/src/docs/userguide/maniphest_custom.diviner b/src/docs/user/userguide/maniphest_custom.diviner similarity index 100% rename from src/docs/userguide/maniphest_custom.diviner rename to src/docs/user/userguide/maniphest_custom.diviner diff --git a/src/docs/userguide/notifications.diviner b/src/docs/user/userguide/notifications.diviner similarity index 100% rename from src/docs/userguide/notifications.diviner rename to src/docs/user/userguide/notifications.diviner diff --git a/src/docs/userguide/owners.diviner b/src/docs/user/userguide/owners.diviner similarity index 100% rename from src/docs/userguide/owners.diviner rename to src/docs/user/userguide/owners.diviner diff --git a/src/docs/userguide/phame.diviner b/src/docs/user/userguide/phame.diviner similarity index 100% rename from src/docs/userguide/phame.diviner rename to src/docs/user/userguide/phame.diviner diff --git a/src/docs/userguide/phriction.diviner b/src/docs/user/userguide/phriction.diviner similarity index 100% rename from src/docs/userguide/phriction.diviner rename to src/docs/user/userguide/phriction.diviner diff --git a/src/docs/userguide/remarkup.diviner b/src/docs/user/userguide/remarkup.diviner similarity index 100% rename from src/docs/userguide/remarkup.diviner rename to src/docs/user/userguide/remarkup.diviner diff --git a/src/docs/userguide/reviews_vs_audit.diviner b/src/docs/user/userguide/reviews_vs_audit.diviner similarity index 100% rename from src/docs/userguide/reviews_vs_audit.diviner rename to src/docs/user/userguide/reviews_vs_audit.diviner diff --git a/src/docs/userguide/slowvote.diviner b/src/docs/user/userguide/slowvote.diviner similarity index 100% rename from src/docs/userguide/slowvote.diviner rename to src/docs/user/userguide/slowvote.diviner diff --git a/src/docs/userguide/users.diviner b/src/docs/user/userguide/users.diviner similarity index 100% rename from src/docs/userguide/users.diviner rename to src/docs/user/userguide/users.diviner diff --git a/src/docs/userguide/utf8.diviner b/src/docs/user/userguide/utf8.diviner similarity index 100% rename from src/docs/userguide/utf8.diviner rename to src/docs/user/userguide/utf8.diviner