From 4e91ba67e05468992dd385ed8d50b58b9de3ee67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20S=C3=A1ros?= <balazs.saros@instructure.com>
Date: Wed, 24 Jul 2024 11:09:24 +0200
Subject: [PATCH] docs: update release docs with major update info

---
 docs/contributor-docs/release.md | 51 +++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 10 deletions(-)

diff --git a/docs/contributor-docs/release.md b/docs/contributor-docs/release.md
index 207ce3c06a..a6fc068292 100644
--- a/docs/contributor-docs/release.md
+++ b/docs/contributor-docs/release.md
@@ -4,7 +4,7 @@ category: Contributor Guides
 order: 5
 ---
 
-# Release Process
+## Release Process for Minor Updates
 
 This document outlines the steps required for the release process. Please follow the instructions below:
 
@@ -19,7 +19,7 @@ git checkout master
 
 ##### 2. Create a New Branch for Release
 
-- The branch should be created from the latest master.
+- The branch should be created from the latest master. (note: if a local branch named `release` already exists, delete it beforehand)
 
 ```text
 ---
@@ -54,7 +54,7 @@ npm run bump
 type: code
 ---
 git add .
-git commit --amend
+HUSKY=0 git commit --amend
 ```
 
 ##### 6. Push Your Changes to Remote
@@ -78,15 +78,11 @@ git push origin release
 
 - The release process may take some time, be patient.
 
-##### 10. Announce the Release on Slack
+##### 10. Add a New Release to GitHub
 
-    - Once the release is successful, announce it on the #instui channel on Slack. Be sure to include the changelog and new version in your announcement.
+- Add a new release to GitHub. This will display the newly released version as the latest and automatically triggers a release notification in the #instui Slack channel.
 
-##### 11. Add a New Release to GitHub
-
-    - Finally, add a new release to GitHub. This will display the newly released version as the latest.
-
-##### 12. Release Process for Legacy Versions
+## Release Process for Legacy Versions
 
 This document describes the steps to follow when releasing updates to legacy versions. The example given is for v7:
 
@@ -151,3 +147,38 @@ git push origin release
 ##### 9. Announce the Release
 
 - Once the release is successful, announce it on the #instui channel on Slack. Be sure to include the changelog and new version in your announcement.
+
+## Release Process for Major updates
+
+Major version updates are very similar to minor updates but there are a couple additinal things to take care of.
+
+##### 1. Create a maintenance branch
+
+Before the update, create a maintenance branch from the current master and push it to remote. If the current major version is 11, then:
+
+```text
+---
+type: code
+---
+git checkout -b v11_maintenance
+git push origin v11_maintenance
+```
+
+##### 2. Update the version mapping for the docs
+
+Update the fields in the file `./packages/__docs__/versions.json` with the latest version and the maintenance branch map. Remove old unsupported versions if they are no longer needed and you don't want them to appear in the docs page version selector.
+
+##### 3. Add redirect for the legacy docs
+
+Add a new line to the file `./packages/__docs__/_redirects` to redirect the legacy docs. If the current major version is 11, then:
+
+```text
+---
+type: code
+---
+/v11/* https://v11--preview-instui.netlify.app/:splat 200
+```
+
+##### 4. Do a release like it was a minor update
+
+Follow the same process as it's described above. The `npm run bump` command should automatically recognise that there were a breaking commit and it should be a major version change.