From da670f51ec74d7ed6f2f3b48f1de37642787a35b Mon Sep 17 00:00:00 2001
From: Jordan Neufeld <jordan.neufeld@shopify.com>
Date: Fri, 4 Mar 2022 15:42:31 -0600
Subject: [PATCH] update release documentation

---
 README.md  |  5 +---
 RELEASE.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 4 deletions(-)
 create mode 100644 RELEASE.md

diff --git a/README.md b/README.md
index 332c1fa1b..f0a4530b2 100644
--- a/README.md
+++ b/README.md
@@ -616,9 +616,6 @@ For example, `shopify_test_redis_master` or `shopify_development_mysql_1`.
 
 ### Release
 
-1. Update `CHANGELOG.md`
-1. Change versions in `README.md`
-1. Create a release commit and a signed tag.
-1. [Bump version for Homebrew](https://github.com/Shopify/homebrew-shopify/blob/master/toxiproxy.rb#L9)
+See [RELEASE.md](./RELEASE.md)
 
 [blog]: https://shopifyengineering.myshopify.com/blogs/engineering/building-and-testing-resilient-ruby-on-rails-applications
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 000000000..3ef00d44f
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,70 @@
+# Releasing 
+- [Releasing](#releasing)
+  - [Before You Begin](#before-you-begin)
+  - [Local Release Preparation](#local-release-preparation)
+    - [Update the CHANGELOG.md](#update-the-changelogmd)
+    - [Create Release Commit and Tag](#create-release-commit-and-tag)
+    - [Run Pre-Release Tests](#run-pre-release-tests)
+  - [Submit Release Pull Request](#submit-release-pull-request)
+  - [Push Release Tag](#push-release-tag)
+  - [Verify Github Release](#verify-github-release)
+  - [Update Homebrew versions](#update-homebrew-versions)
+
+## Before You Begin
+
+Ensure your local workstation is configured to be able to [Sign Commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
+
+## Local Release Preparation
+
+### Update the [CHANGELOG.md](CHANGELOG.md)
+
+- Add a new version header at the top of the document, just after `# [Unreleased]`
+- Update links at bottom of changelog
+
+### Create Release Commit and Tag
+
+```bash
+export RELEASE_VERSION=2.x.y
+git checkout master
+git pull origin master
+git commit -S -m "Release $RELEASE_VERSION"
+git tag -s "v$RELEASE_VERSION" -m "Release $RELEASE_VERSION"
+```
+
+### Run Pre-Release Tests
+
+```bash
+make test-release
+```
+
+## Submit Release Pull Request
+
+- Submit a PR of your Release commit on Github
+- Merge it to master (after approval)
+
+## Push Release Tag
+
+- On your local machine again, push your tag to github
+
+```bash
+git push origin v2.x.y
+```
+
+## Verify Github Release
+
+- Github Actions should kick off a build and release after the tag is pushed.
+- Verify that a [Release gets created in Github](https://github.com/Shopify/toxiproxy/releases) and verify that the release notes look correct
+- Github Actions should also attatch the built binaries to the release (it might take a few mins)
+
+## Update Homebrew versions
+
+- Update [homebrew-shopify toxiproxy.rb](https://github.com/Shopify/homebrew-shopify/blob/master/toxiproxy.rb#L9) manifest
+  1. Update `app_version` string to your released version
+  2. Update hashes for all platforms (find the hashes in the checksums.txt from your release notes)
+
+- Do a manual check of installing toxiproxy via brew
+  1. While in the homebrew-shopify directory...
+  ```bash
+  brew install ./toxiproxy.rb --debug
+  ```
+  Note: it's normal to get some errors when homebrew attempts to load the file as a Cask instead of a formula, just make sure that it still gets installed.
\ No newline at end of file