Infrastructure/Phabricator: Difference between revisions

    From KDE TechBase
    (Replaced content with "Moved to https://community.kde.org/Infrastructure/Phabricator")
     
    (23 intermediate revisions by 4 users not shown)
    Line 1: Line 1:
    = Phabricator User Guide =
    Moved to https://community.kde.org/Infrastructure/Phabricator
    [http://phabricator.org/ Phabricator] is a task management system which KDE is transitioning toward. It is written in php (hence the ph) and structured as a collection of applications, most of which take the form of web modules. These modules can be seen on the left hand side of the [https://phabricator.kde.org/ KDE Phabricator], with names like Differential, Maniphest, and Phriction. 
     
    Phabricator is under very active development, but is already an excellent tool. This page is intended to serve as a general-purpose introduction to the most important aspects: submitting and reviewing patches.  It should not take long before you are happily using Phabricator.  If you are not happy, you can submit bug reports to to [https://secure.phabricator.com/ Phabricator's own Phabricator] to request changes.  Note this can address only Phabricator-related unhappiness, but not deeper life issues.
     
    The modular structure allows projects to flexibly create their own workflows. Project maintainers should keep developers and contributors up to date with more specific guidelines on their pages in the KDE Community Wiki or Phriction.
     
    == Basic Tasks ==
    === Logging in ===
    The first challenge posed by Phab is logging in.  You will use your KDE Identity account for this.  If you don't have one, you can [https://identity.kde.org/index.php?r=registration/index sign up for one here ].  At the Phabricator login screen, enter that username and password in the "Login or Register with LDAP," which is the lower form. Hopefully this will be clarified and simplified in the future.
     
    === Getting help ===
    The official documentation is in the [https://secure.phabricator.com/book/phabricator/ Phabricator book] and [https://phacility.com/phabricator/ on their website] -- note the official website is full of puns -- but since everything is under rapid development most of the documentation is incomplete. A good way to find the information you're looking for is to search [https://secure.phabricator.com/ Phab upstream].  The search is in the upper right hand corner. In the future the official documentation may be hosted on the KDE site.
     
    === Phab Apps ===
    Luckily the use of most of the web applications is described in a small tag line. Differential and Maniphest, the code review and task management applications, are where you should expect to spend most of your time.  Calligra intends to collect information for developers in Phriction. You can also create your own to-do list in Dashboard. In addition to the pages which are listed there are more applications available. Some others not listed on the main page by default are Pholio, for discussing mockups, Slowvote, for conducting user polls, and Paste, for sharing text snippets.
     
    == Using Arcanist ==
    === What is Arc? ===
    Arcanist is Phabricator's excellent command line tool to interface with Git and other VCS systems. It tries hard to do the right thing and make sure it is doing the right thing.  Like the rest of Phabricator it is written in PHP. After you have installed Arc, you can learn more using <tt>man arc</tt> or <tt>arc --help</tt>. Another command useful for getting a feel for Phabricator's style is <tt>arc anoid</tt>.
     
    === Installing on Linux ===
    Although Arc is provided in the official Ubuntu repository and presumably others, at the time of this writing, the development is too fast paced for this version to be up-to-date. A better idea is to install from upstream; this requires downloading their php library libphutil as well as Arcanist. [https://gist.github.com/thomas-barthelemy/882e6e19405ebecb14be A script to do this automatically in Ubuntu is here.]  You will need the php command line and CURL packages: in Ubuntu, php5-cli and php5-curl.
     
    === Installing on Windows ===
    There is information on Arcanist.  Installing Arcanist on Windows is not much harder than on Linux, but getting php is a little more involved, since there is no package manager. You will need to configure your Php installation script to use Curl.
    * [https://secure.phabricator.com/book/phabricator/article/arcanist_windows/ Arc installation guide] 
    * [http://php.net/manual/en/install.windows.manual.php Php installation guide]
     
    === Connecting to KDE ===
    Your project repo should contain the file <tt>.arcconfig</tt> in the root directory.  If not, [https://projects.kde.org/projects/calligra/repository/revisions/master/entry/.arcconfig here is a simple template].  The only additional information Arc needs is your login identifier.  This is as simple as going to the link https://phabricator.kde.org/conduit/login/ and installing your API token with <tt>arc install-certificate.</tt>
     
    === Posting Patches ===
    The basic command to interface with Differential, the patch review system, is <tt>arc diff</tt>.  By default, this command will try to take your current git patch and create a new Differential to submit for upstream review.  It will reformat Git commit message, asking you to provide reviewers and providing the URL to the newly created diff.  In the same way the KDE bugtracker will [https://techbase.kde.org/Development/Git/Configuration#Commit_Template read from the commit template] and automatically close bugs, Phabricator reads commit messages and will update Maniphest and Diff automatically.  [https://secure.phabricator.com/T5132 Here is more information] about the special messages it looks for.
     
    === Workflow ===
    The basic workflow I have found successful is a feature-branch workflow.  I keep a master branch, and each patch becomes a different branch. With the correct upstream branch set, I use <tt>arc diff</tt> with no arguments to create a new diff.  After receiving feedback and making changes, I alter the Git commit with <tt>git commit --amend --no-edit</tt>  (Actually I perform a commit extend in [https://github.com/magit/magit Magit].) A second arc diff while on the edited branch and Arc will ask me for a comment message and update.  Finally I merge my feature branch and use Git to push; Phab will automatically close the diff when it detects the repository has been updated.  Alternatively, <tt>arc land</tt> can be configured to do the merge-and-push automatically.
     
    == Review: Differential and Maniphest ==
     
    === Information ===
    These are more self-explanatory than Arc and mostly follow the layout of a public forum.  Before sharing links to internal Phabricator pages and diffs, be sure they are configured to be "Visible to Public (No Login Required)."  I'm not sure if there's a way to set this automatically.

    Latest revision as of 11:39, 9 March 2016