AEL Hubs Upgrade Process

ael-hubs-upgrade-process.md

This document explains my environment and workflow for handling upgrades to AEL's Hubs Cloud instance.

Overview

hubs.aelatgt.net includes source modifications to support script injection and a handful of project-specific tweaks. This allows developers to add new behaviors on a room-by-room basis without having to rebuild the client. Some projects require access to internal client logic, which we expose on a global APP.utils object.

Environment

I have multiple Git remotes configured so I can maneuver between the Mozilla and AEL repos:

$ git remote -v

origin  git@github.com:aelatgt/hubs.git (fetch)
origin  git@github.com:aelatgt/hubs.git (push)
upstream        https://github.com/mozilla/hubs.git (fetch)
upstream        https://github.com/mozilla/hubs.git (push)

You can set this up by running:

git remote add origin git@github.com:aelatgt/hubs.git
git remote add upstream https://github.com/mozilla/hubs.git

Upgrade process

Pull the latest hubs-cloud commits from Mozilla's repo:

git checkout hubs-cloud
git pull upstream hubs-cloud --ff

Create a new branch to contain AEL modifications. We follow the format hubs.aelatgt.MM.YY, e.g. hubs.aelatgt.04.22 for changes made in April 2022.

git checkout -b hubs.aelatgt.net.04.22

Determing what needs to be changed

I use GitHub's "compare" view to see which changes we made to the previous release. I start by looking at the commits on our current branch (e.g. commits for hubs.aelatgt.02.22). I'm looking for the hash of the most recent Mozilla commit as well as the latest AEL commit:

I plug these into a "compare" URL with the format:

https://github.com/mozilla/hubs/compare/<START_HASH>...<END_HASH>

where <START_HASH> and <END_HASH> represent the commit hashes I copied.

For example, here are the AEL modifications that were applied for the Feb 2022 release: https://github.com/mozilla/hubs/compare/70ad270739e7819df0f36cefaef8d958bc21d1c5...60c87f68c2d319ec73a436591fa79064554a6458

Making the changes

The compare view shows a list of commits as well as the overall changes to each file.

You need to make these same changes onto your new branch. You could do this by copy/pasting the changes manually. What I typically do is cherry-pick most of the commits which I know don't have conflicts, and then make any finishing touches by hand.

For instance, the script injection modiciation is fairly small -- it only involves adding a <TextInputField /> element to the room settings sidebar and a few lines in hubs.js to import() the saved script URL. I would add this to my new branch with:

git cherry-pick 45283c23a36f289902d87bf91f8c95ed4468fd36

You can repeat this for each of the commits until your local diff from hubs-cloud resembles the reference diff. Then, verify that the local version still works:

npm ci
npm start

Deploying

If everything looks good, you can deploy your changes

npm run deploy

Remember to also push these changes to GitHub. We keep the default branch on our repo set to whatever is actively deployed.

git push -u origin HEAD

Note: Three.js version changes

One modification that you may need to perform by hand is changing the Three.js version (example). I point Hubs towards a personal fork of Three.js which re-enables some morph target features (necessary for my face tracking project) that Mozilla reverted in their fork. In other projects, I can usually change a dependency in package.json and let NPM update the package-lock.json accordingly. However; Hubs tends to get build errors when I update this way. Instead, I manually update the entries in both package.json and package-lock.json to use the appropriate branch and commit hash. So if Hubs is producing mysterious build errors, or if NPM refuses to install dependencies, you made want to try performing your dependency updates manually.