From 2773addc3d1cf683aaad084f6493b9d899d84094 Mon Sep 17 00:00:00 2001
From: Norm <normandy@biribiri.dev>
Date: Wed, 7 Sep 2022 08:25:57 +0000
Subject: [PATCH] docs: Update install guide to use tag-merge strategy

Adapted from @toast's guide: https://mk.toast.cafe/notes/93o9n4tfsi
---
 docs/install.md | 47 +++++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/docs/install.md b/docs/install.md
index dbdf5e0d0..88946739a 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -38,22 +38,29 @@ Create a separate non-root user to run FoundKey:
 adduser --disabled-password --disabled-login foundkey
 ```
 
+The following steps will require logging into the `foundkey` user, so do that now.
+```sh
+su - foundkey
+```
+
 ## Install FoundKey
-1. Login to the `foundkey` user
+We recommend using a local branch and merging in upstream releases as they get tagged. This allows for easy local customization of your install.
 
-	`su - foundkey`
+First, clone the FoundKey repo:
+```sh
+git clone https://akkoma.dev/FoundKeyGang/FoundKey
+cd FoundKey
+```
 
-2. Clone the FoundKey repository
+Now create your local branch. In this example, we'll be using `toast.cafe` as the local branch name and release `v13.0.0-preview1` as the tag to track. To create that branch:
+```sh
+git checkout tags/v13.0.0-preview1 -b toast.cafe
+```
 
-	`git clone --recursive https://akkoma.dev/FoundKeyGang/FoundKey foundkey`
-
-3. Navigate to the repository
-
-	`cd foundkey`
-
-4. Install FoundKey's dependencies
-
-	`yarn install`
+Updating will be covered in a later section. For now you'll want to install the dependencies using Yarn:
+```sh
+yarn install
+```
 
 ## Configure FoundKey
 1. Copy `.config/example.yml` to `.config/default.yml`.
@@ -176,13 +183,21 @@ rc-service foundkey start
 You can check if the service is running with `rc-service foundkey status`.
 
 ### Updating FoundKey
-Use git to pull in the latest changes and rerun the build and migration commands:
-
+When a new release comes out, simply fetch and merge in the new tag. Here we opt to squash upstream commits as it allows for easy reverts in case something goes wrong.
+```sh
+git fetch -t
+git merge tags/v13.0.0-preview2 --squash
+  # you are now on the "next" release
+```
+
+Now you'll want to update your dependencies and rebuild:
 ```sh
-git pull
-git submodule update --init
 yarn install
 NODE_ENV=production yarn build
+```
+
+Next, run the database migrations:
+```sh
 yarn migrate
 ```