Changes between Initial Version and Version 1 of Phabricator

Timestamp:

Jan 23, 2017, 1:01:07 PM (7 years ago)

Author:

Itms

Comment:

New page for Phabricator

Phabricator

@@ +1 @@
+Our Phabricator instance is located at https://code.wildfiregames.com. Any issue with the website should be reported to Itms.
+
+== 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.
+
+== 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.
+
+Read [wiki: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 [https://secure.phabricator.com/book/phabricator/article/arcanist/ 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 [https://git-scm.com/ Git], which you will need to install Arcanist anyways.
+
+Take a look at the [wiki:Phabricator#CommonproblemswithArcanist Common problems with Arcanist] section below if you have any trouble.
+
+Finally, associate arc with your credentials on code.wildfiregames.com using
+{{{
+arc install-certificate
+}}}
+
+Two commands are important, that you can run at the root of a SVN clone (where .arcconfig is):
+
+{{{
+arc patch Dn
+}}}
+applies the revision Dn (n being an integer) to your working copy. No need to download and apply, easy to update when a contributor updates a revision with a new diff, and more...
+
+{{{
+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.
+
+Always create diffs from a clone to the public SVN. Since Phabricator tracks the public repo, if you create diffs from a clone of the commit-access one, 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.
+* You will need to patch Arcanist against [https://secure.phabricator.com/T8075 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.