Version 12 (modified by Krinkle, 5 years ago) ( diff )

update git-based arc workaround

Our Phabricator instance is located at https://code.wildfiregames.com. Any issue with the website should be reported to Itms.

Known issue: Revisions up to D82 were created before Phabricator was made public and they still have their old "Users only" view policy. If you want a revision to be viewable from the public you can ask somebody to change that manually.

Creating an account

When creating your account, choose the username carefully. If you are to become a team member, the username will be your commit name so Phabricator maps your account with your SVN commits. If you already are a team member, choose your Phabricator username so it matches exactly your SVN username.

When logged in, you can customize a lot of things by clicking your user icon and the settings icon at the right-top of the page.

Finding your way around

The applications you should need regularly are pinned at the left.

  • Differential allows you to create revisions and get reviews.
  • Diffusion allows you to browse SVN commits.
  • Audit allows you to "raise concerns" over previous commits, so issues are fixed ASAP, and not forgotten.
  • Paste is a handy tool, make use of it instead of using alternative tools like Pastebin or Gists.

A lot of other applications are available under Applications. If you find yourself using one frequently, you can pin it.

For a list of available hotkeys press Shift + ? or ? (depending on keyboard layout).

Using Differential

Differential is a really powerful tool. It allows you to upload and download patches easily for review.

A revision is a proposal of some code change. It is associated a diff, which is just a code difference. You can update the diff associated with a revision, based on comments, reviews, etc. Each time the diff is updated, Jenkins will download it, apply it to the current SVN, build and run tests; it will then post the results to the revision.

For security reasons, we require patch authors to be members of the Contributors group on Phabricator before their patches are automatically tested. So before uploading your first patch, just come on IRC and say hello so a team member can add you to the group.

Read SubmittingPatches for more information on the review process.

There are two ways to upload patches: using Arcanist (recommended) or doing it manually.

Using Arcanist

Phabricator can be interacted with through Arcanist, a command line interface. The installation of Arcanist might not be too user-friendly but the user guide there should contain what you need. Basically you will need to install php-cli, get the code for Arcanist and add the tools to your PATH.

On Windows, I recommend using the Git Bash tool that comes with Git, which you will need to install Arcanist anyways.

Take a look at the Common problems with Arcanist section below if you have any trouble.

Configura Arcanist

Finally, associate arc with your credentials with our Phabricator instance by using

arc install-certificate

Download a patch

To download a patch from Phabricator using Arcanist, run the following command from the root of a local SVN clone (where .arcconfig is):

arc patch Dn

This will apply the latest diff from a revision Dn (n being an integer) to your working copy.

Download a patch (Git)

If you use a Git-based mirror (such as https://github.com/0ad/0ad), then using arc diff may fail because Arcanist demands to find the latest SVN revision in the git-log which might not be mirrored yet. Arcanist tries to searching the full git commit history for a commit message containing git-svn-id: @{latest-revision}, which it will then never find. (Upstream issue: https://secure.phabricator.com/T9044). The --force and --skip-dependencies options to arc diff do not solve this issue.

As a workaround, you can download the diff from Phabricator Differential directly (using the "Download Raw Diff" link), and then applying it using the patch command. Below is a function you can use (e.g. place in ~/.bash_profile).

# From https://git.io/JeYgl#L292
function pull0ad {
    if [ -z "$1" ]; then
        echo "usage: ${FUNCNAME[0]} Dnnnn"
        return 1
    fi
    patch="$1"
    curl "https://code.wildfiregames.com/{$patch}?download=true" -L 2>/dev/null > /tmp/arc.diff
    git checkout -q -B "arcpatch_$patch" origin/master
    git apply -p0 --index -v /tmp/arc.diff
    git commit -q -m "D2079"
}

0ad (master)$ pull0ad D1991
 Checking patch...
 Applied patch!

0ad (arcpatch_D1991)$

Upload a patch

arc diff --preview

creates a diff from your working copy and uploads it to Phabricator. When following the given link, you will be able to create a new revision or update an existing one with the new code change.

If you're a team member with commit access, always create diffs from a clone of the public SVN. Since Phabricator tracks the public repo, if you create diffs from a clone of the commit-access one, the paths won't match.

Manually uploading a patch

You can also create a patch by using svn diff (or the corresponding "Create patch" feature with TortoiseSVN on Windows, or git format-patch if you work on a git clone).

Always create the diff from the root of the repository (where .arcconfig is).

It is recommended to generate the patch with full file context so review is eased on Phabricator. Use

svn diff --diff-cmd=diff -x -U999999

to do so.

Committing

If you have commit access, you can clone the non-public repository. Then, you can use

arc patch Dn
svn st

and check everything is ready for commit.

The commit message must contain

Differential Revision: https://code.wildfiregames.com/Dn

on its own line at the end of the message!

A useful command is

arc commit --revision Dn --show

which pre-formats a very verbose commit message. You can copy it, remove the unneeded content and paste it into the commit message editor.

Always use --show or you will commit without confirmation! For more safety you can use the command in a public clone.

Porting patches from Trac

Please port your own patches from Trac. Don't port other people's patches! Revision authors must be the actual patch authors.

To do so, I suggest running:

svn patch /path/to/your_patch.diff
arc diff --preview

Then click on the link.

  • Name the new revision and add a summary and a test plan.
  • Write the Trac ticket number in the Trac tickets field.
  • In the summary, if you write #1234, Phabricator should replace that with a link to the Trac ticket.

Common problems with Arcanist

Some frequent issues with Arcanist are listed below, along with tips.

On Windows,

  • Make sure TortoiseSVN is installed with the box command line client tools checked.
  • Differential revisions will be created without context (T2465). In order to work around the issue, you can change the behavior of svn diff the following way:
    • Create a file called contextdiff.bat with the following contents:
      @echo off
      diff.exe -U9999999 -L %3 -L %5 %6 %7
      
      This file will use the diff executable provided by the Git Bash environment, so it should work.
    • Change you SVN settings: go to %appdata%\Subversion\ and edit the config file. Find the line beginning with
      # diff-cmd = ...
      
      and replace it by
      diff-cmd = X:\full\path\to\contextdiff.bat
      
    • You can test it works by running svn diff in the repository: the output should contain the entire contents of the modified file. From now on arc diff will create diffs with context available.
  • You will need to patch Arcanist against T8075. To do so, in your clone of the arcanist git repository, run
    git remote add oujesky https://github.com/oujesky/arcanist.git
    git fetch oujesky
    git cherry-pick b728af9
    

If you get errors about 'SimpleXMLElement' it's because PHP 7 does not come with php-xml. You have to install that package, which might be called php7-xml.

If Arcanist "cannot parse svninfo" it's because your locale outputs the result of the command "svn info" in something that is not English. You can write to your shell rc file something like

alias arc='LANG=C LC_ALL=C arc'

in order to make SVN output information in its default locale, which is English, and that Arcanist can parse.

Note: See TracWiki for help on using the wiki.