From 63598e630aba8448c96c058d062ba499f6c2d649 Mon Sep 17 00:00:00 2001
From: Mingwei Samuel <mingwei.samuel@gmail.com>
Date: Fri, 30 Aug 2024 12:59:00 -0700
Subject: [PATCH] ci: update `RELEASING.md`, say to manually bump versions of
 renamed crates

---
 .github/workflows/release.yml |  2 ++
 RELEASING.md                  | 39 ++++++++++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 630a3276f0d3..1189a4dc800e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -95,3 +95,5 @@ jobs:
         env:
           # Make sure to set this so the `gh` CLI works using our token.
           GH_TOKEN: ${{ steps.generate_token.outputs.token }}
+          # Show `cargo-smart-release`'s stack trace on error.
+          RUST_BACKTRACE: 1
diff --git a/RELEASING.md b/RELEASING.md
index 6f86d1409fb3..e854f169f033 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -132,7 +132,44 @@ The changelogs should now be safely preserved by future releases.
 
 ## Addendum: Renaming crates
 
-TODO
+First, follow the [steps above for moving crates](#addendum-moving-crates).
+
+After renaming a crate, `cargo-smart-release` will see it a brand new crate with no published
+versions on crates.io, and will therefore not bump the version. This is not desired behavior, and
+generating the changelog will fail unintelligibly due to the conflicting versions:
+```log
+BUG: User segments are never auto-generated: ...
+```
+
+To fix this, before releasing, manually bump the version of the renamed crate. `Cargo.toml`:
+```toml
+name = "crate_old_name"
+publish = true
+version = "0.8.0"
+# becomes
+name = "crate_new_name"
+publish = true
+version = "0.9.0"
+```
+(In this case, bumping the minor version)
+
+You will also need to manually update any crates that depend on the renamed crate as well:
+```toml
+crate_old_name = { path = "../crate_old_path", version = "^0.8.0" }
+# becomes
+crate_new_name = { path = "../crate_new_path", version = "^0.9.0" }
+```
+
+Commit those changes, then continue as normal.
+
+```sh
+git tag | grep old_crate
+```
+Find and copy the newest (largest) version.
+
+```sh
+git tag new_crate-v0.5.2 old_crate-v0.5.2
+```
 
 ## Addendum: The GitHub App account