From 90db888964ff42aaea87020f1ae58286118bad16 Mon Sep 17 00:00:00 2001
From: Maksym Arutyunyan <maksym.arutyunyan@dfinity.org>
Date: Thu, 4 Sep 2025 14:13:32 +0200
Subject: [PATCH 1/3] docs: add release guide

---
 RELEASE_GUIDE.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 RELEASE_GUIDE.md

diff --git a/RELEASE_GUIDE.md b/RELEASE_GUIDE.md
new file mode 100644
index 00000000..16f72e00
--- /dev/null
+++ b/RELEASE_GUIDE.md
@@ -0,0 +1,106 @@
+# Release Guide (stable-structures)
+
+This guide describes how to cut releases and publish them to [crates.io](https://crates.io) for `ic-stable-structures`.
+
+## Goals
+
+- Ship improvements without breaking users  
+- Validate APIs and memory model before stabilization  
+- Keep rollback cheap  
+
+## Release Options
+
+- **Opt-in feature flags**  
+  Hide experimental code behind non-default flags.
+
+- **Semantic Versioning Pre-Releases** ([semver.org](https://semver.org))  
+  - `x.y.z-alpha.N` — experimental, incomplete, may be unstable or buggy  
+  - `x.y.z-beta.N` — feature complete, testing needed, bugs expected  
+  - `x.y.z-rc.N` — release candidate, no new features, only bug fixes  
+
+Cargo won’t auto-pick pre-releases; users must pin them explicitly.
+
+## Policy
+
+- Any breaking and/or major change requires a **design doc** reviewed by stakeholders before release.  
+- Pre-releases (`-alpha`, `-beta`, `-rc`) are strongly encouraged for high-risk changes.  
+
+## When to Use (stable-structures specific)
+
+- **Public API changes**  
+  - Added methods → behind a feature flag until validated  
+  - Removed/signature changes → breaking (minor bump <1.0.0, major bump ≥1.0.0)
+
+- **Stable memory layout changes**  
+  - New/altered layout → feature flag + pre-release  
+  - Layout-breaking (cannot read old data) → breaking (minor bump <1.0.0, major bump ≥1.0.0)
+
+- **Processing-only changes** (no layout change)  
+  - Compatible algorithmic updates → minor bump  
+  - High risk → feature flag and/or pre-release
+
+- **Hidden layout migrations** (auto-migrate on load)  
+  - If old data won’t load without migration → treat as breaking  
+  - Ship via feature flag + pre-releases; promote only after successful trials  
+
+## Example: Memory Reclaim
+
+Adding a `reclaim()` method to free unused memory without changing layout, only processing it differently, is high risk and may cause data corruption:
+
+- Hide `reclaim()` behind a feature flag  
+- High risk → release as `-beta.N`  
+- Iterate with feedback, promote to stable once validated  
+- Remove feature flag after stabilization  
+
+## Release Process
+
+### Prepare
+
+1. Bump version in `Cargo.toml`:
+
+   ```toml
+   [package]
+   version = "x.y.z"
+   ```
+
+2. Ensure CI is green.  
+3. Preferable commit & PR name: `chore(release): vX.Y.Z` ([example PR](https://github.com/dfinity/stable-structures/pull/379)).  
+
+### Publish Release to GitHub
+
+1. Identify the commit to release.  
+2. Draft a new release:  
+   - Go to the [Releases](https://github.com/dfinity/stable-structures/releases) tab.  
+   - Click **Draft a new release**.  
+   - Create a new tag `vX.Y.Z` pointing to the commit.  
+   - Set the release title to `vX.Y.Z`.  
+   - Choose the previous tag as the last release.  
+   - Add release notes (GitHub can auto-generate, adjust as needed).  
+3. Click **Publish release**.  
+
+### Publish to crates.io
+
+1. Generate an API token:  
+   - Log in to crates.io → **Account Settings** → **API Tokens** → generate a new token.  
+2. Authenticate:  
+   ```bash
+   cargo login
+   ```
+   Enter the token when prompted.  
+3. Check out the repo at the release tag:  
+   ```bash
+   git checkout vX.Y.Z
+   ```
+4. Dry-run publish (mandatory):  
+   ```bash
+   cargo publish -p ic-stable-structures --dry-run
+   ```
+5. Publish:  
+   ```bash
+   cargo publish -p ic-stable-structures
+   ```
+
+### Verify
+
+- Check [crates.io](https://crates.io/crates/ic-stable-structures).  
+- Confirm documentation builds on [docs.rs](https://docs.rs).  

From aaee9dd91b9757fcbb8c3391b9f0499fa80b20fa Mon Sep 17 00:00:00 2001
From: Maksym Arutyunyan <maksym.arutyunyan@dfinity.org>
Date: Thu, 4 Sep 2025 14:14:50 +0200
Subject: [PATCH 2/3] .

---
 RELEASE_GUIDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/RELEASE_GUIDE.md b/RELEASE_GUIDE.md
index 16f72e00..6ab3cc9d 100644
--- a/RELEASE_GUIDE.md
+++ b/RELEASE_GUIDE.md
@@ -1,6 +1,6 @@
 # Release Guide (stable-structures)
 
-This guide describes how to cut releases and publish them to [crates.io](https://crates.io) for `ic-stable-structures`.
+This guide describes how to cut releases and publish them to [crates.io](https://crates.io/crates/ic-stable-structures) for `ic-stable-structures`.
 
 ## Goals
 

From 7b9985b94b157911200702251be80e579bf653a4 Mon Sep 17 00:00:00 2001
From: Maksym Arutyunyan <maksym.arutyunyan@dfinity.org>
Date: Thu, 4 Sep 2025 14:20:33 +0200
Subject: [PATCH 3/3] examples

---
 RELEASE_GUIDE.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/RELEASE_GUIDE.md b/RELEASE_GUIDE.md
index 6ab3cc9d..e9e187e7 100644
--- a/RELEASE_GUIDE.md
+++ b/RELEASE_GUIDE.md
@@ -38,6 +38,11 @@ Cargo won’t auto-pick pre-releases; users must pin them explicitly.
 - **Processing-only changes** (no layout change)  
   - Compatible algorithmic updates → minor bump  
   - High risk → feature flag and/or pre-release
+  - Examples
+    - Changing default values, coercions, or type conversions  
+    - Altering validation rules  
+    - Updating how parsing, ordering, deduplication, or filtering logic is applied  
+    - Modifying error handling or recovery behavior when reading/writing to stable memory  
 
 - **Hidden layout migrations** (auto-migrate on load)  
   - If old data won’t load without migration → treat as breaking