From caf555c60ab9774eafea9eaf566be7db92a43e5e Mon Sep 17 00:00:00 2001
From: "Ben Sheldon [he/him]" <bensheldon@gmail.com>
Date: Mon, 23 Aug 2021 19:29:00 -0700
Subject: [PATCH] Add upgrade instructions for v1 to v2 (#345)

---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 7addc8a9c..190678552 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,8 @@ For more of the story of GoodJob, read the [introductory blog post](https://isla
     - [ActiveJob concurrency](#activejob-concurrency)
     - [Cron-style repeating/recurring jobs](#cron-style-repeatingrecurring-jobs)
     - [Updating](#updating)
+        - [Upgrading minor versions](#upgrading-minor-versions)
+        - [Upgrading v1 to v2](#upgrading-v1-to-v2)
 - [Go deeper](#go-deeper)
     - [Exceptions, retries, and reliability](#exceptions-retries-and-reliability)
         - [Exceptions](#exceptions)
@@ -405,17 +407,45 @@ config.good_job.cron = {
 
 GoodJob follows semantic versioning, though updates may be encouraged through deprecation warnings in minor versions.
 
-To apply updates:
+#### Upgrading minor versions
 
-```bash
-bin/rails g good_job:update
-```
+Upgrading between minor versions (e.g. v1.4 to v1.5) should not introduce breaking changes, but can introduce new deprecation warnings and database migration notices.
 
-...and run the resulting migration:
+To perform upgrades to the GoodJob database tables:
 
-```bash
-bin/rails db:migrate
-```
+1. Generate new database migration files:
+
+    ```bash
+    bin/rails g good_job:update
+    ```
+
+1. Run the database migration locally
+
+    ```bash
+    bin/rails db:migrate
+    ```
+
+1. Commit the migration files and resulting `db/schema.rb` changes.
+1. Deploy the code, run the migrations against the production database, and restart server/worker processes.
+
+#### Upgrading v1 to v2
+
+GoodJob v2 introduces a new Advisory Lock key format that is different than the v1 advisory lock key format; it's therefore necessary to perform a simple, but staged production upgrade. If you are already using `>= v1.12+` no other changes are likely44
+necessary.
+
+1. Upgrade your production environment to `v1.99.x` following the minor version upgrade process, including database migrations. `v1.99` is a transitional release that is safely compatible with both `v1.x` and `v2.0.0` because it uses both `v1`- and `v2`-formatted advisory locks.
+1. Address any deprecation warnings generated by `v1.99`.
+1. Upgrade your production environment to `v1.99.x` to `v2.0.x` again following the _minor_ upgrade process.
+
+Notable changes:
+
+- Renames `:async_server` execution mode to `:async`; renames prior `:async` execution mode to `:async_all`.
+- Sets default Development environment's execution mode to `:async` with disabled polling.
+- Triggers `GoodJob.on_thread_error` for unhandled ActiveJob exceptions.
+- Renames `GoodJob.reperform_jobs_on_standard_error` accessor to `GoodJob.retry_on_unhandled_error`.
+- Renames `GoodJob::Adapter.shutdown(wait:)` argument to `GoodJob::Adapter.shutdown(timeout:)`.
+- Changes Advisory Lock key format from `good_jobs[ROW_ID]` to `good_jobs-[ACTIVE_JOB_ID]`.
+- Expects presence of columns `good_jobs.active_job_id`, `good_jobs.concurrency_key`, `good_jobs.concurrency_key`, and `good_jobs.retried_good_job_id`.
 
 ## Go deeper