From 839edfbecef63680afbeb2c2bf89ecbca7511c42 Mon Sep 17 00:00:00 2001
From: Mike Johanson <michael.johanson@intel.com>
Date: Mon, 15 Sep 2025 13:13:10 -0700
Subject: [PATCH] docs: migration guide to v3

---
 .gitignore         |  1 +
 migration-guide.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 migration-guide.md

diff --git a/.gitignore b/.gitignore
index 4eddeebe..80901aae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,5 +14,6 @@ coverage
 .github/copilot-instructions.md
 *.md
 !README.md
+!migration-guide.md
 *.yaml
 !config.yaml
\ No newline at end of file
diff --git a/migration-guide.md b/migration-guide.md
new file mode 100644
index 00000000..75528633
--- /dev/null
+++ b/migration-guide.md
@@ -0,0 +1,54 @@
+# 🚨 Breaking Change Release — v3.0.0
+
+## 🔑 Breaking Changes
+
+### 1. Explicit flag syntax
+
+* **Long-form flags** must now use `--` (e.g., `--profile`).
+* **Short-form flags** must now use `-` (e.g., `-p`).
+
+---
+
+### 2. `config` now means “application configuration”
+
+* `config` now refers to the **application’s own configuration** (Go-standard).
+* `configv2` has been **removed**.
+
+---
+
+### 3. Old `config` → now called `profile`
+
+* The concept of `config` used for provisioning (previously passed as `configv2`) is now called a **profile**.
+* Use the `--profile` flag to provide this, aligning with the rest of the device-management-toolkit.
+
+---
+
+## 🚀 Migration Examples
+
+### Example: Switching from `configv2` to `--profile`
+
+**Before (v2.x):**
+
+```bash
+rpc-go configure --configv2 path/to/profile.yaml
+```
+
+**After (v3.0):**
+
+```bash
+rpc-go configure --profile path/to/profile.yaml
+# or, where supported:
+rpc-go configure -p path/to/profile.yaml
+```
+
+
+
+## ✅ Summary
+
+* **Flags must be explicit** (`--long`, `-s`).
+* **`config` = app configuration**.
+* **`configv2` removed**.
+* **`--profile` replaces `configv2`**.
+
+---
+