From d4748c92e86ebf06d641e5d52627eac674c5095d Mon Sep 17 00:00:00 2001
From: "Alan L. Rezende" <109520132+alanrezendeee@users.noreply.github.com>
Date: Fri, 15 May 2026 01:22:25 -0300
Subject: [PATCH 1/2] docs: add RELEASE.md with PR-based release workflow

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

diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..87f9b1c
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,106 @@
+# 🚀 Release Workflow
+
+> How to release a new version of kimi-mem. **No direct pushes to `main`.**
+
+---
+
+## 📋 Checklist
+
+- [ ] All changes are on a feature branch (`feat/`, `fix/`, `docs/`)
+- [ ] CI passes (tests + linter) on the PR
+- [ ] CHANGELOG.md updated with `[Unreleased]` → `[X.Y.Z]` section
+- [ ] Version bumped in `kimi_mem/__init__.py` and `pyproject.toml`
+- [ ] PR reviewed and merged to `main`
+- [ ] Git tag `vX.Y.Z` created on the merge commit
+- [ ] Tag pushed to GitHub (`git push origin vX.Y.Z`)
+- [ ] Release workflow completes (CI → build → PyPI publish)
+
+---
+
+## 🔀 Step-by-Step
+
+### 1. Create a feature branch
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b feat/descriptive-name
+```
+
+### 2. Make changes
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+git commit -m "feat: add new Setup hook"
+git commit -m "fix: correct uninstall logic"
+git commit -m "test: add MCP server tests"
+```
+
+### 3. Push branch and open PR
+
+```bash
+git push origin feat/descriptive-name
+gh pr create --title "feat: descriptive title" --body "What changed and why."
+```
+
+Wait for CI to pass ✅
+
+### 4. Merge PR
+
+```bash
+gh pr merge --squash --delete-branch
+```
+
+**Never push directly to `main`.**
+
+### 5. Tag the release
+
+```bash
+git checkout main
+git pull origin main
+git tag -a v0.2.2 -m "Release v0.2.2: what changed"
+git push origin v0.2.2
+```
+
+### 6. Verify
+
+- GitHub Actions: CI passes → Release builds → PyPI publishes
+- Check: https://pypi.org/project/kimi-mem/
+
+---
+
+## ⚠️ Never Do This
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| `git push origin main` | Open PR → merge |
+| Delete and recreate a tag | Tag once, correctly |
+| Skip CHANGELOG | Always update CHANGELOG.md |
+| Skip version bump | Bump `__init__.py` + `pyproject.toml` |
+
+---
+
+## 🔧 Emergency Hotfix
+
+If a critical bug is found in a released version:
+
+1. Branch from the tag: `git checkout -b hotfix/v0.2.2 v0.2.1`
+2. Fix, commit, PR, merge to `main`
+3. Tag new version: `v0.2.2`
+
+---
+
+## 🏷️ Versioning
+
+We follow [SemVer](https://semver.org/):
+
+- `MAJOR` — breaking changes (rare in alpha)
+- `MINOR` — new features, backward compatible
+- `PATCH` — bug fixes only
+
+Pre-1.0: `0.MINOR.PATCH` — minor bumps are acceptable for new features.
+
+---
+
+*Last updated: 2026-05-15*

From f78bde27d47ca61ed74d1ed9b441337a389a8bf1 Mon Sep 17 00:00:00 2001
From: "Alan L. Rezende" <109520132+alanrezendeee@users.noreply.github.com>
Date: Fri, 15 May 2026 01:27:14 -0300
Subject: [PATCH 2/2] ci: add custom Pages workflow with concurrency to prevent
 artifact conflicts

---
 .github/workflows/pages.yml | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 .github/workflows/pages.yml

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..8c8f97b
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,36 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Prevent concurrent deployments — cancel any in-progress run
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4