From 1636dea8f15986378857fee9893bee8e88f39a58 Mon Sep 17 00:00:00 2001
From: Du Wenbo <duwenbo88@163.com>
Date: Mon, 6 Apr 2026 09:08:03 +0800
Subject: [PATCH] docs: add version management guide to README

Step-by-step instructions for releasing, downloading old versions,
comparing versions, and keeping version metadata in sync.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/README.md b/README.md
index 2a99de8..f54ec90 100644
--- a/README.md
+++ b/README.md
@@ -168,6 +168,81 @@ Full Swagger docs at [http://localhost:8000/docs](http://localhost:8000/docs) af
 
 ---
 
+## Version Management
+
+We use **Semantic Versioning** (MAJOR.MINOR.PATCH) and **git tags** to manage releases.
+
+### Where Version Is Tracked
+
+Version must be consistent across **three places**:
+
+| Location | Example | How to update |
+|----------|---------|---------------|
+| `VERSIONS.json` | `"project_version": "1.2.0"` | Edit the file |
+| Git tag | `v1.2.0` | `git tag -a v1.2.0 -m "description"` |
+| Gitea repo description | `[v1.2.0] EMS Core...` | Gitea Settings or API |
+
+### Releasing a New Version
+
+```bash
+# 1. Update VERSIONS.json (set project_version, last_updated, notes)
+#    For customer repos, also update core_version if core was updated
+
+# 2. Commit the version bump
+git add VERSIONS.json
+git commit -m "chore: bump version to vX.Y.Z"
+
+# 3. Create annotated tag (MUST be after VERSIONS.json is updated)
+git tag -a vX.Y.Z -m "vX.Y.Z: brief description of this release"
+
+# 4. Push commit AND tag together
+git push origin main
+git push origin vX.Y.Z
+
+# 5. Update Gitea repo description
+curl -X PATCH "http://<GITEA_HOST>/api/v1/repos/tianpu/<REPO>" \
+  -H "Authorization: token <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"description": "[vX.Y.Z] Updated description"}'
+```
+
+### Downloading a Specific Version
+
+```bash
+# Clone and checkout a specific version
+git clone http://100.69.143.96:3300/tianpu/ems-core.git
+cd ems-core
+git checkout v1.1.0       # switch to v1.1.0 (detached HEAD)
+
+# Or download as zip without cloning
+curl -o ems-core-v1.1.0.zip \
+  "http://100.69.143.96:3300/tianpu/ems-core/archive/v1.1.0.zip"
+```
+
+### Viewing / Comparing Versions
+
+```bash
+# List all available versions
+git tag -l
+
+# See what changed between two versions
+git diff v1.1.0 v1.2.0
+
+# View a specific file at an old version
+git show v1.1.0:VERSIONS.json
+
+# View commit log between versions
+git log v1.1.0..v1.2.0 --oneline
+```
+
+### Switching Back to Latest
+
+```bash
+git checkout main          # go back to latest
+```
+
+---
+
 ## Note
 
 ems-core is the backend-only shared library. Each customer project (tp-ems, zpark-ems) owns its own frontend, deployed independently.