First of all, this guide assumes you are familiar with git and Mastodon development generally. If you are not, you should not be attempting a big code merge of upstream Mastodon into Hometown! I will at some point writing a lengthy guide to getting set up as a Hometown developer from scratch, but for now you should probably refer to the [Mastodon developer docs](https://docs.joinmastodon.org/dev/setup/#manual). Probably ignore the section at the top about the "Vagrantfile" and just go straight into "Manual install from source" -- I want you to be familiar with the nitty gritty of everything if you're going to get your hands dirty here.
Setting up your remotes
So the first thing we want to make sure of is that our git repo is pointing to both Mastodon and Hometown. I use the following naming scheme, but feel free to use your own:
git remote add origin git@github.com:mastodon/mastodon.gitgit remote add hometown git@github.com:hometown-fork/hometown.git
...and then also a remote for your own fork of Hometown, where you'll be making a pull request from since you probably don't have write access to Hometown itself. For the purposes of this document we'll assume it's called myfork:
git remote add myfork git@github.com:myfork/hometown.git
To merge from upstream Mastodon into Hometown, broadly speaking we are going to be pulling down release code from the remote called origin (the Mastodon project on Github) and then applying it to a Hometown working branch locally, then pushing that branch to the remote called myfork (the Hometown project on Github). Once it's up there, we make a pull request from the branch you just created on myfork to hometown/hometown-dev.
Getting started with working code
We want to start with a working release version of the latest Hometown. If you don't already have Hometown running locally, you should have a version of Mastodon running locally in a dev environment that is equivalent to the part before the + in the Hometown version string. So if you are starting from Hometown v3.5.5+1.0.8, you can locally install Mastodon v3.5.5. Once you have the Mastodon version running locally, switch over to the equivalent Hometown release:
git checkout v3.5.5+1.0.8- If you try to run
foreman starthere you'll get lots of error messages because we need to install extra dependencies and do a database migration. bundle installRAILS_ENV=development bundle exec rails db:migrateforeman start
Now go to localhost:3000 in a browser and see if there's a working Hometown server. You can confirm you are running the right version of Hometown by looking at the footer way down beneath the compose box on the desktop web client.
Make a sandbox where it's okay if you mess up
Now that we have a working Hometown version locally, we want to make a new working branch from where the code is currently at. Something like:
-
git branch myusername-4.0.0-merge(or whatever you are going to call it) -
git checkout myusername-4.0.0-merge
Now you are working off the code as of the latest Hometown release, but you are doing it in a context of a branch that isn't going to mess up code anywhere else if you make any big mistakes. This is the branch that we are going to push to the myfork remote, which we'll eventually make a pull request from.
Push the big red button
Now you want to make sure you are synced with the latest releases on upstream Mastodon, so run
git fetch --tags origin
Now we're sure to have all the latest release tags from upstream.
Now we want to identify the tag for the version of upstream we are merging. If you go to the release page for the version, you'll see the tag name listed next to the release, marked by the little tag icon:
We want to merge the tagged release from Mastodon into our code that we want to update, so for the sake of this document we are doing:
git merge v4.0.0
This is going to spit out a bunch of merge conflict errors. Like a lot. I'm sorry.
Note: typically I merge one version at a time in chronological order, even if my ultimate goal is to be several releases ahead of where I'm starting (for example, updating from Mastodon v3.5.5 to 4.0.0 to 4.0.1 to 4.0.2, since those are all tagged releases in a row)
Getting ourselves out of this mess
So now we need to resolve the merge conflicts and then make sure the whole thing actually runs.
Dec 28 2022: I need to write this part still. I am probably going to do it after the v4.0.2+1.1.0 release. Sorry!