Infrastructure/Phabricator: Difference between revisions

From KDE Community Wiki
(Begin arc tips&tricks section)
(Many improvements)
Line 1: Line 1:
= Phabricator User Guide =
[http://phabricator.org/ Phabricator] is KDE's task management and patch review system. 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.
[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 may only address Phabricator-related unhappiness.
 
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.


{{Info|The KDE community does not use the Phabricator bug reporting function. We continue to use bugzilla at https://bugs.kde.org}}
{{Info|The KDE community does not use the Phabricator bug reporting function. We continue to use bugzilla at https://bugs.kde.org}}


== Basic Tasks ==
= Basic Tasks =
=== Logging in ===
== 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.
Log in to Phabricator with your KDE Identity account.  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 home page, click the "Log in" button on the top of the page and enter your KDE Identity username and password.


=== Getting help ===
== 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.
The official documentation is in the [https://secure.phabricator.com/book/phabricator/ Phabricator book] and [https://phacility.com/phabricator/ on their website] -- note that 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/ Phabricator upstream].


=== Phab Apps ===
== Posting a Patch using the website ==
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.
First, create a diff file using <tt>git diff</tt> (or <tt>git format-patch</tt>) Log in to Phabricator and enter Code Review (a.k.a Differential).  Click the <tt>+Create Diff</tt> button in the upper-right corner of the screen. Paste the text of the diff or upload the file using the file dialog.  Select the project at the bottom; if you start typing it will perform a search among active projects. For a reviewer, use the name of the project itself (the text-field will auto-complete valid projects to help you out). In some cases, you will want to request a review from particular people instead of or in addition to the group.


=== Posting a Patch ===
{{Note|1= You '''must''' specify at least one reviewer for your diff.  If you upload a revision with no reviewers, nobody will get notified.}}
First, create a diff file using <tt>git diff</tt> (or <tt>git format-patch</tt>.) Log in to Phab and enter Code Review (a.k.a Differential)Click the <tt>+Create Diff</tt> button in the upper-right corner of the screen. Paste the text of the diff or upload the file using the file dialog.  Select the project at the bottom, if you start typing it will perform a search among active projects.  


For a reviewer, the default is to select the project itself. That means all users who are members of the project will be notified, and any user can approve the patch. In some cases, you will want to request a review from particular people instead.
If your patch is intended to fix a Bugzilla ticket, include the following on its own line in the Summary section:
<pre>
BUG: 385942
</pre>
(Just the Bugzilla ticket number, '''not the full URL''')


{{Note|1= You '''must''' specify at least one reviewer for your diff.  If you upload a revision with no reviewers, nobody will get notified.}}
This will cause that Bugzilla ticket to be automatically closed when the patch is committed.


== Using Arcanist ==
If your patch implements a feature rather than fixing a bug, use "FEATURE" instead of "BUG":
=== What is Arc? ===
<pre>
Arcanist is Phabricator's fully featured command line tool to interface with your local Git repository. It can be used to submit your patches for review. 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>.
FEATURE: 384936
</pre>
(As before, just the Bugzilla ticket number, '''not the full URL''')


=== Installing on Linux ===
[https://techbase.kde.org/Development/Git/Configuration#Commit_Template Here is more information] about other special messages that interact with Bugzilla tickets. You can also add special messages that interact with [https://secure.phabricator.com/T5132 other Phabricator tools (e.g. Maniphest tasks)].
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 good option is to install directly from upstream. You will need the php command line and CURL packages: in Ubuntu, php5-cli and php5-curl. Then you can download the repositories and add the arc command line tool to your command line.  [https://gist.github.com/thomas-barthelemy/882e6e19405ebecb14be A script to do this automatically in Ubuntu is here.]


=== Installing on Windows ===
= Using Arcanist to post patches =
Downloading the Arcanist web scripts on Windows is no different than on Linux, but getting php is a little more involved, since there is no package manager. Phabricator has a more complete installation guide.
== What is Arc? ==
Using the web UI to post patches gets tiresome after a while. Arcanist is a tool to simplify and speed up the process of posting, updating, and merging Phabricator patches.


* [https://secure.phabricator.com/book/phabricator/article/arcanist_windows/ Arc installation guide] 
Phabricator's fully featured command line tool to interface with your local Git repository. It can be used to submit your patches for review.. . 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>.
* [http://php.net/manual/en/install.windows.manual.php Php installation guide]


The most non-obvious step is that you will need to configure your Php installation to use Curl.  This requires editing the php.ini configuration file to add the line <tt>extension_dir = "ext"</tt> and add <tt>php_curl</tt> to the list of extensions.
== Installing on Linux ==
Getting <tt>arc</tt> is easy on Linux; just use your distro's package manager:
* Debian/Ubuntu/KDE Neon: <tt>sudo apt install arcanist</tt>
* Fedora: <tt>sudo dnf install arcanist</tt>
* openSUSE: <tt>sudo zypper install arcanist</tt>
* Arch/Antergos/Manjaro: <tt>sudo pacman -S arcanist</tt>
* Windows: [https://secure.phabricator.com/book/phabricator/article/arcanist_windows/ Arc installation guide] The most non-obvious step is that you will need to configure your [http://php.net/manual/en/install.windows.manual.php Php installation] to use Curl.  This requires editing the php.ini configuration file to add the line <tt>extension_dir = "ext"</tt> and add <tt>php_curl</tt> to the list of extensions. After adding php.exe to your path and installing arcanist/libphutil, you can run arc by defining a function in your Powershell profile: <pre> function arc { php -f "C:\path\to\arcanist.php" -- $args }</pre>


After adding php.exe to your path and installing arcanist/libphutil, you can run arc by defining a function in your Powershell profile:
== Workflow ==
<pre> function arc { php -f "C:\path\to\arcanist.php" -- $args }</pre>
The sanest and easiest way to use <tt>arc</tt> is to follow a typical '''feature branch workflow''': keep your master branch synchronized with the upstream repository, and make all changes on separate branches.


=== Connecting to KDE ===
=== Step 1: Create a new diff ===
Your project repo should contain the file <tt>.arcconfig</tt> in the root directory.  If not, [https://cgit.kde.org/plasma-framework.git/tree/.arcconfig here is a simple template].  If you prefer you can set a default URL for repositories that don't contain an <tt>.arcconfig</tt> file by doing
Before editing anything, create a new branch for your patch:
<pre>arc set-config default https://phabricator.kde.org</pre>
<pre>
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>
$ git checkout -b <branchname> origin/master
 
</pre>  
=== Posting Patches ===
Make changes on the feature branch. When you're ready to have your changes reviewed, do the following:
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 into something like this:  
<pre>
$ git add <space-separated list of all the files you changed>
$ git commit
$ arc diff
</pre>
When you run <tt>arc diff</tt>, you will go through a series of dialogues. At the end, you will be asked to rewrite your Git commit message to fit the standard Differential format, like so:  
<pre>
<pre>
<first line of original git commit message>
<first line of original git commit message>
Line 60: Line 70:
</pre>
</pre>


The only thing you will have to fill in is the reviewer. As mentioned above, the default is to choose the whole project as the reviewer. This can be done in the text by writing one of the project hashtags in the reviewer field. For example, [https://phabricator.kde.org/project/profile/8/ the default reviewer for Krita is #krita] and [https://phabricator.kde.org/project/profile/34/ the default hashtag for KDE PIM is #kde_pim]. Additionally, when you create your diff, you can [https://secure.phabricator.com/rP2427d317b2f0957b0c4917c5c321e07d94c7e2b9 associate it with an existing Maniphest task] by adding a line like
<tt><first line of original git commit message></tt> will become the commit message, so please follow [https://chris.beams.io/posts/git-commit/#seven-rules commit message best practices].
<pre>Maniphest Tasks: T50</pre>


As when using the web UI, enter any special Bugzilla keywords (such as <tt>BUG: 385942</tt>) on their own lines in the "Summary" section.


Phabricator does not require Arcanist for every upstream transaction. 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.
As when using the web UI, for the "Reviewers" section, enter a hashtag for the review group--which is usually equal to the project name. For example, the review group for[https://phabricator.kde.org/project/profile/8/ Krita]  is #krita and the review group for [https://phabricator.kde.org/project/profile/34/ KDE PIM]  is #kde_pim. If you can't figure out the correct hashtag, leave the Reviewers section blank for now over <tt>arc</tt>'s protestations and then edit your revision on the web UI after it's been created; you will be able to enter reviewers into a nice text box that auto-completes with valid reviewers, which is much more user-friendly.


=== Workflow ===
Don't touch the "Differential Revision:" section.
The basic workflow I have found successful with Arc is a feature-branch workflow. I keep a master branch synchronized with the upstream, and make all of my changes on separate branches.


'''Step 1: Creating a new diff.'''
=== Step 2: Update your diff ===
 
After <tt>arc</tt> uploads the patch to phabricator, the project's reviewers will take a look and give you some comments. If you get a thumbs up immediately, you can skip this step. But often you will get a review like "looks good, we can take it if you fix problems x, y, and z."  Make the necessary changes, add an extra commit to the git branch, and update the Phabricator revision:
Before editing anything, create a new branch for your new feature.
<pre>
$ git checkout -b <branchname> origin/master
</pre>  
Make or cherry-pick changes into this feature branch. When you're ready to have your changes reviewed:
<pre>
<pre>
[implement changes based on review comments]
$ git add -u
$ git commit
$ git commit
$ arc diff
$ arc diff
</pre>
</pre>
When you run arc diff, you will go through a series of dialogues.  You will be asked to rewrite your Git commit message to fit the standard Differential format. Remember that you must enter a reviewer, either by entering a project hashtag or an individual user.


'''Step 2: Updating your diff.'''
=== Step 3: Land your diff ===
If you do not have a [[Infrastructure/Get_a_Contributor_Account | KDE Developer Account]], then someone who does will have to land your patch for you. Otherwise, you can do it yourself once the patch has been accepted and reviewers have given you permission to "ship it!"


After you upload the code the reviewer will take a look and give you some comments. If you get a thumbs up, you can skip this step.  But often you will get a review like "looks good, we can take it if you fix problems x, y, z."  After you make your changes, you can add an extra commit to the git branch.
<pre>
<pre>
$ git add -u
$ [make sure you are on your feature branch]
$ git commit
$ arc land
$ arc diff
</pre>
</pre>
This will squash all of the commits in your feature branch together. Phabricator aims for a tight correspondence of one commit = one change = one diff.  If you don't want to squash your commits, using Arc for the last step is unnecessary, as Phabricator will monitor the repo and mark the diff as closed when it sees the commit. You can push using <tt>git push</tt> instead.


'''Step 3: Landing your diff.'''
If you are new to <tt>arc</tt>, you may want to double-check the commit message before actually pushing to make sure the commit looks as intended. You can do so with <tt>arc land --hold</tt>, which will squash your feature-branch in a single commit on master, without pushing it.  <tt>arc land</tt> also assumes the upstream branch is called "origin/master." Usually that is the case, but if you have been asked to commit to a "stable branch", you can do so using the <tt>--onto</tt> argument with the branch name, e.g: <pre>arc land --onto Applications/18.04</pre>


The following needs you to have a full [[Infrastructure/Get_a_Contributor_Account | KDE Developer Account]]. If this is one of your first patches to KDE projects, so you do not have one yet, you will need your reviewers or someone else to land the diff.
== Arcanist Tips & Tricks ==
=== Updating the summary of the Differential from the local Git commit message ===


After the patch is in an acceptable state, the reply to your new message will be: "Ship it!"
If you changed the commit message locally and want to update the text in the summary in Differential, call Arc like this:
<pre>
<pre>
$ git checkout <branchname>
$ arc diff --edit --verbatim
$ arc land
</pre>
</pre>
This will squash all of the commits in your feature branch together. Phabricator aims for a tight correspondence of one commit = one change = one diff.  If you don't want to squash your commits, using Arc for the last step is unnecessary, as Phab will monitor the repo and mark the diff as closed when it sees the commit. You can push using <tt>git push</tt> instead.


If you are new to Arc, you may want to double-check the commit message before actually pushing to make sure the commit looks as intended. You can do so with <tt>arc land --hold</tt>, which will squash your feature-branch in a single commit on master, without pushing it.  <tt>arc land</tt> also assumes the upstream branch is called "origin/master." Usually that is the case, but for more complicated workflows some additional configuration is required.
=== Marking patches as dependent on other patches ===
Sometimes you will want to submit a patch that depends on another patch, creating a '''dependency chain'''.


==== If  each patch is intended for a different project ====
Example: you submit a patch to add new feature in KIO, and then submit another patch for Dolphin that uses that feature. Here's what you do:
<ol>
<li>Create your first patch as above</li>
<li>When creating the second patch, add the following to its own line in the "Summary" section:
<pre>Depends on DXXXX</pre>
(Replace "DXXXX" with the ID of the dependent patch, '''not the full URL)'''</li>
</ol>


=== Tips & Tricks ===
==== If the patches are all for the same project ====
Example: you are implementing multiple new features for a single project that each depend on the patch for the prior feature. Here's what you do:
<ol>
<li>Create a branch to track the first feature:
<pre>
$ git checkout -b <branch name for feature 1> origin/master
</pre>
Then implement the feature and make a commit.
</li>
<li>Then create a branch for your second feature, ''tracking the first branch:''
<pre>
git checkout -b <branch name for feature 2> --track <branch name for feature 1>
</pre>
As above, implement the feature and make a commit. Continue this pattern for any other required dependent features.
</li>


'''Updating the summary of the Differential from the local Git commit message'''
<li>
When you're ready to turn your dependency chain feature branches into patches, do the following:
<pre>
$ git checkout <branch name for feature 1>
$ arc diff [then go through the process of creating the patch normally]
$ git checkout <branch name for feature 2>
git commit --amend  [then add the special text "Depends on DXXXX", replacing DXXXX with the ID of the first patch
$ arc diff [then go through the process of creating the patch normally]
</pre>
...And so on.
</li>


If you changed the commit message locally and want to update the text in the summary in Differential, call Arc like this:
<li>After you get comments, you will have to make changes to your patches and re-base dependent patches:
<pre>
<pre>
$ arc diff --edit --verbatim
$ git checkout <branch name for feature 1>
[Make changes]
$ git add -u
$ git commit
$ arc diff
$ git checkout <branch name for feature 2>
$ git rebase <branch name for feature 1>
$ git add -u
$ git commit
$ arc diff
</pre>
</pre>
...And so on.
</li>


== Review ==
<li>When you're ready to land any or all of your patches, do it in sequence, starting from the patch with no unmet dependencies:
 
<pre>
=== Discussions on Diff and Maniphest ===
# (beware, did not test, see also https://phabricator.kde.org/D10207#199285)
Diff and Maniphest are used for coordinating changes and pre-reviewing patches. These are more self-explanatory than Arc and mostly follow the layout of a public forum, like Review Board or Github.  Before sharing links to Phabricator pages and diffs on the KDE forums or bug tracker, be sure you have configured them to be "Visible to Public (No Login Required)."
$ git checkout <branch name for feature 1>
$ arc land
$ git checkout <branch name for feature 2>
$ arc land
</pre>
</li>
</ol>


== Customization ==


=== Creating custom dashboard feeds ===
= Customization =
You can customize your Phabricator homepage by creating a new dashboard.  However the selection of what you can post on your dashboard is limited. The defaults will show all tasks from all projects.   
== Creating custom dashboard feeds ==
You can customize your Phabricator homepage by creating a new dashboard.  However the selection of what you can post on your dashboard is limited. The defaults will show all tasks from all projects.   


To narrow this down, you need to define a custom query to serve as a filter.  For example, if you work on Plasma Mobile and want to monitor the to-do list, perhaps you want to show only tasks which are in the Plasma Mobile and are tagged as open. To do that, enter Maniphest, select "advanced search," select the appropriate terms, then click "save custom query." You can give your query a name. Once it is saved, the query will become available as a new filter for creating feeds on your dashboard. (In Differential you seem to need to perform the test search before the "save query" button becomes visible.)
To narrow this down, you need to define a custom query to serve as a filter.  For example, if you work on Plasma Mobile and want to monitor the to-do list, perhaps you want to show only tasks which are in the Plasma Mobile and are tagged as open. To do that, enter Maniphest, select "advanced search," select the appropriate terms, then click "save custom query." You can give your query a name. Once it is saved, the query will become available as a new filter for creating feeds on your dashboard. (In Differential you seem to need to perform the test search before the "save query" button becomes visible.)

Revision as of 14:01, 8 February 2018

Phabricator is KDE's task management and patch review system. 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.

Information

The KDE community does not use the Phabricator bug reporting function. We continue to use bugzilla at https://bugs.kde.org


Basic Tasks

Logging in

Log in to Phabricator with your KDE Identity account. If you don't have one, you can sign up for one here . At the Phabricator home page, click the "Log in" button on the top of the page and enter your KDE Identity username and password.

Getting help

The official documentation is in the Phabricator book and on their website -- note that 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 Phabricator upstream.

Posting a Patch using the website

First, create a diff file using git diff (or git format-patch) Log in to Phabricator and enter Code Review (a.k.a Differential). Click the +Create Diff button in the upper-right corner of the screen. Paste the text of the diff or upload the file using the file dialog. Select the project at the bottom; if you start typing it will perform a search among active projects. For a reviewer, use the name of the project itself (the text-field will auto-complete valid projects to help you out). In some cases, you will want to request a review from particular people instead of or in addition to the group.

Note

You must specify at least one reviewer for your diff. If you upload a revision with no reviewers, nobody will get notified.


If your patch is intended to fix a Bugzilla ticket, include the following on its own line in the Summary section:

BUG: 385942

(Just the Bugzilla ticket number, not the full URL)

This will cause that Bugzilla ticket to be automatically closed when the patch is committed.

If your patch implements a feature rather than fixing a bug, use "FEATURE" instead of "BUG":

FEATURE: 384936

(As before, just the Bugzilla ticket number, not the full URL)

Here is more information about other special messages that interact with Bugzilla tickets. You can also add special messages that interact with other Phabricator tools (e.g. Maniphest tasks).

Using Arcanist to post patches

What is Arc?

Using the web UI to post patches gets tiresome after a while. Arcanist is a tool to simplify and speed up the process of posting, updating, and merging Phabricator patches.

Phabricator's fully featured command line tool to interface with your local Git repository. It can be used to submit your patches for review.. . After you have installed Arc, you can learn more using man arc or arc --help. Another command useful for getting a feel for Phabricator's style is arc anoid.

Installing on Linux

Getting arc is easy on Linux; just use your distro's package manager:

  • Debian/Ubuntu/KDE Neon: sudo apt install arcanist
  • Fedora: sudo dnf install arcanist
  • openSUSE: sudo zypper install arcanist
  • Arch/Antergos/Manjaro: sudo pacman -S arcanist
  • Windows: Arc installation guide The most non-obvious step is that you will need to configure your Php installation to use Curl. This requires editing the php.ini configuration file to add the line extension_dir = "ext" and add php_curl to the list of extensions. After adding php.exe to your path and installing arcanist/libphutil, you can run arc by defining a function in your Powershell profile:
     function arc { php -f "C:\path\to\arcanist.php" -- $args }

Workflow

The sanest and easiest way to use arc is to follow a typical feature branch workflow: keep your master branch synchronized with the upstream repository, and make all changes on separate branches.

Step 1: Create a new diff

Before editing anything, create a new branch for your patch:

$ git checkout -b <branchname> origin/master

Make changes on the feature branch. When you're ready to have your changes reviewed, do the following:

$ git add <space-separated list of all the files you changed>
$ git commit
$ arc diff

When you run arc diff, you will go through a series of dialogues. At the end, you will be asked to rewrite your Git commit message to fit the standard Differential format, like so:

<first line of original git commit message>

Summary: <rest of original commit message>

Reviewers: 

Differential Revision: <URL to the new diff>

<first line of original git commit message> will become the commit message, so please follow commit message best practices.

As when using the web UI, enter any special Bugzilla keywords (such as BUG: 385942) on their own lines in the "Summary" section.

As when using the web UI, for the "Reviewers" section, enter a hashtag for the review group--which is usually equal to the project name. For example, the review group forKrita is #krita and the review group for KDE PIM is #kde_pim. If you can't figure out the correct hashtag, leave the Reviewers section blank for now over arc's protestations and then edit your revision on the web UI after it's been created; you will be able to enter reviewers into a nice text box that auto-completes with valid reviewers, which is much more user-friendly.

Don't touch the "Differential Revision:" section.

Step 2: Update your diff

After arc uploads the patch to phabricator, the project's reviewers will take a look and give you some comments. If you get a thumbs up immediately, you can skip this step. But often you will get a review like "looks good, we can take it if you fix problems x, y, and z." Make the necessary changes, add an extra commit to the git branch, and update the Phabricator revision:

[implement changes based on review comments]
$ git add -u
$ git commit
$ arc diff

Step 3: Land your diff

If you do not have a KDE Developer Account, then someone who does will have to land your patch for you. Otherwise, you can do it yourself once the patch has been accepted and reviewers have given you permission to "ship it!"

$ [make sure you are on your feature branch]
$ arc land

This will squash all of the commits in your feature branch together. Phabricator aims for a tight correspondence of one commit = one change = one diff. If you don't want to squash your commits, using Arc for the last step is unnecessary, as Phabricator will monitor the repo and mark the diff as closed when it sees the commit. You can push using git push instead.

If you are new to arc, you may want to double-check the commit message before actually pushing to make sure the commit looks as intended. You can do so with arc land --hold, which will squash your feature-branch in a single commit on master, without pushing it. arc land also assumes the upstream branch is called "origin/master." Usually that is the case, but if you have been asked to commit to a "stable branch", you can do so using the --onto argument with the branch name, e.g:

arc land --onto Applications/18.04

Arcanist Tips & Tricks

Updating the summary of the Differential from the local Git commit message

If you changed the commit message locally and want to update the text in the summary in Differential, call Arc like this:

$ arc diff --edit --verbatim

Marking patches as dependent on other patches

Sometimes you will want to submit a patch that depends on another patch, creating a dependency chain.

If each patch is intended for a different project

Example: you submit a patch to add new feature in KIO, and then submit another patch for Dolphin that uses that feature. Here's what you do:

  1. Create your first patch as above
  2. When creating the second patch, add the following to its own line in the "Summary" section:
    Depends on DXXXX
    (Replace "DXXXX" with the ID of the dependent patch, not the full URL)

If the patches are all for the same project

Example: you are implementing multiple new features for a single project that each depend on the patch for the prior feature. Here's what you do:

  1. Create a branch to track the first feature:
    $ git checkout -b <branch name for feature 1> origin/master
    

    Then implement the feature and make a commit.

  2. Then create a branch for your second feature, tracking the first branch:
    git checkout -b <branch name for feature 2> --track <branch name for feature 1>
    

    As above, implement the feature and make a commit. Continue this pattern for any other required dependent features.

  3. When you're ready to turn your dependency chain feature branches into patches, do the following:
    $ git checkout <branch name for feature 1>
    $ arc diff [then go through the process of creating the patch normally]
    $ git checkout <branch name for feature 2>
    git commit --amend  [then add the special text "Depends on DXXXX", replacing DXXXX with the ID of the first patch
    $ arc diff [then go through the process of creating the patch normally]
    

    ...And so on.

  4. After you get comments, you will have to make changes to your patches and re-base dependent patches:
    $ git checkout <branch name for feature 1>
    [Make changes]
    $ git add -u
    $ git commit
    $ arc diff
    $ git checkout <branch name for feature 2>
    $ git rebase <branch name for feature 1>
    $ git add -u
    $ git commit
    $ arc diff
    

    ...And so on.

  5. When you're ready to land any or all of your patches, do it in sequence, starting from the patch with no unmet dependencies:
    # (beware, did not test, see also https://phabricator.kde.org/D10207#199285)
    $ git checkout <branch name for feature 1>
    $ arc land
    $ git checkout <branch name for feature 2>
    $ arc land
    


Customization

Creating custom dashboard feeds

You can customize your Phabricator homepage by creating a new dashboard. However the selection of what you can post on your dashboard is limited. The defaults will show all tasks from all projects.

To narrow this down, you need to define a custom query to serve as a filter. For example, if you work on Plasma Mobile and want to monitor the to-do list, perhaps you want to show only tasks which are in the Plasma Mobile and are tagged as open. To do that, enter Maniphest, select "advanced search," select the appropriate terms, then click "save custom query." You can give your query a name. Once it is saved, the query will become available as a new filter for creating feeds on your dashboard. (In Differential you seem to need to perform the test search before the "save query" button becomes visible.)