Update From Phabricator

Updated 35 Days AgoPublic

Actions

How To Migrate from Phabricator To Phorge

The process of migrating from Phabricator to Phorge is very similar the Upgrading Process, except that you'll be switching to a different remote.

Assumptions and Requirements

This document makes several assumptions about your already-existing install:

1. We assume you've installed Phabricator using the official, supported instructions in https://secure.phabricator.com/book/phabricator/article/installation_guide/. That is, we assume you've used git clone to get the code from Phacility's GitHub mirrors.
2. We assume you've made no local changes ("fork") to the code. If you've added a library that's fine, but we assume no changes to the phabricator and arcanist code bases.

If you have made local changes to your install, then we assume you're comfortable enough with git to adapt.

Process

We won't rename any directories here - while new installs will have a phorge/ and arcanist/ directories, you'll keep phabricator/ and arcanist/. This way, your existing scripts and tools should keep working. This is something to keep in mind during migration, if you want to rename these directories in the future. You can make this change yourself if you feel comfortable to.

There are also many internal references to the phabricator term - we'll be keeping those as well.

Find Your Current Version

First, you'll want to check the current version of your Phabricator install. Phabricator and Phorge use Git commit hashes as "version". You can see your current versions of phabricator and arcanist packages by visiting your install /config page.

You'll want to be reasonably up-to-date before migrating - see Phabricator's Changelogs for details. We highly recommend updating at least to an early 2022 version.

Before considering a migration to Phorge, your Phabricator should be up to date, and have at least these upstream commits:

Note that since 2022, Phorge introduced 300+ commits, and Phabricator less than 30+ commits. We are generally aware of this situation (see Code Differences between Phabricator and Phorge). If you are interested in a specific feature that is Phabricator-only, please contact Phorge to catch these.

Depending on how long it's been since you've last updated, there may be some breaking changes added to Phorge - you may want to check the Changelog since 2022.

Updating

1. Stop the webserver and daemons.

2. Backup your install - Database and files storage.

3. Update the origin address in each repository and take changes:

$ cd ./phabricator/

# This will print out `master` or `stable` - it's the branch you're using:
$ git rev-parse --abbrev-ref '@{u}'

$ git remote rename origin old-origin
$ git remote add origin https://github.com/phorgeit/phorge.git
$ git fetch origin

# This creates a backup of your current state:
$ git branch last_known_good HEAD

# Remove some files we broke in Aphlict - we'll update that later.
$ rm -f ./support/aphlict/server/package-lock.json  ./support/aphlict/server/package.json

# Configure your new remote: You can use `origin/stable` instead that's the branch you've been using.
$ git branch --set-upstream-to=origin/master
$ git pull

# Repeat for Arcanist directory:
$ cd ../arcanist/
$ git remote rename origin old-origin
$ git remote add origin https://github.com/phorgeit/arcanist.git
$ git fetch origin
$ git branch last_known_good HEAD

# Configure your new remote: You can use `origin/stable` instead that's the branch you've been using.
$ git branch --set-upstream-to=origin/master

# Reset your working copy of Arcanist to the latest remote: You can use `origin/stable` instead that's the branch you've been using. This may remove any files you've changed in your working copy.
$ git reset --hard origin/master
# And again for Phorge
$ cd ../phabricator/
# Reset your working copy of Phorge to the latest remote: You can use `origin/stable` instead that's the branch you've been using. This may remove any files you've changed in your working copy.
$ git reset --hard origin/master

4. Update Some Configurations

The default values of these configuration values may have changed from Phabricator to Phorge, so here we'll explicitly set them to their previous defaults.

Update these configs by running ./bin/config set <config key> <value> in the phabricator directory, eg:

$ ./bin/config set storage.default-namespace phabricator

5. Re-install Aphlict

Aphlict is the Notifications Server, allowing for "real-time" notifications to show up on pages.

We've changed Aphlict's installation instructions in T15019.
Aphlict still requires node and npm.

$ cd ./phabricator/support/aphlict/server/
$ rm -rf node_modules/
$ npm install --no-save
$ cd ../../../../

Upgrade Storage and Restarting

Just like a regular update, you should run phabricator/bin/storage upgrade at this point.

Now run phabricator/bin/cache purge --all to clear any lingering static assets that should be updated automatically.

Next, restart the daemons and the webserver as instructed in Upgrading Phorge.

At this point, you should be back up and running the latest version of Phorge. Further upgrades should be handled normally.