@ema.co/mcp-toolkit 1.5.2 → 1.6.0

package/docs/release-process.md

@@ -0,0 +1,153 @@
+# Release Process
+
+## Lessons Learned (2026-01-16)
+
+The `feat/v1.5.0-intelligence-layer` branch was orphaned for weeks, containing 5,600+ lines of code that diverged significantly from main. This document establishes processes to prevent similar situations.
+
+## Branch Hygiene Rules
+
+### 1. No Long-Lived Feature Branches
+
+**Rule:** Feature branches should be merged or closed within **2 weeks**.
+
+**Why:** Long-lived branches diverge and become difficult to merge.
+
+**Process:**
+- If a feature takes longer than 2 weeks, break it into smaller PRs
+- If blocked, document why and set a reminder to revisit
+
+### 2. Pre-Branch Checklist
+
+Before creating a new feature branch:
+
+```bash
+# 1. Fetch latest and check for unmerged work
+git fetch origin
+git branch -r --no-merged main | grep -v HEAD
+
+# 2. If unmerged branches exist, decide:
+#    - Merge them first? OR
+#    - Explicitly abandon them?
+
+# 3. Start from latest main
+git checkout main
+git pull origin main
+git checkout -b feat/my-feature
+```
+
+### 3. Weekly Stale Branch Review
+
+Run weekly to identify abandoned branches:
+
+```bash
+# Show branches not merged to main, sorted by age
+git for-each-ref --sort=committerdate refs/remotes/origin \
+  --format='%(committerdate:short) %(refname:short)' | \
+  grep -v HEAD | grep -v main
+```
+
+### 4. Post-Merge Cleanup
+
+After merging a PR:
+
+```bash
+# Delete the remote branch
+git push origin --delete feat/my-feature
+
+# Delete local branch
+git branch -d feat/my-feature
+
+# Verify cleanup
+git remote prune origin
+```
+
+## Version Bumping Strategy
+
+### Semantic Versioning
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Breaking change | Major | 1.5.2 → 2.0.0 |
+| New feature | Minor | 1.5.2 → 1.6.0 |
+| Bug fix | Patch | 1.5.2 → 1.5.3 |
+
+### Branch Naming Convention
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Feature | `feat/descriptive-name` | `feat/intelligence-layer-additive` |
+| Fix | `fix/descriptive-name` | `fix/fallback-detection` |
+| Release | `release/vX.Y.Z` | `release/v1.6.0` |
+
+### Pre-Release Checklist
+
+Before creating a release:
+
+1. **Check for unmerged work:**
+   ```bash
+   git branch -r --no-merged main
+   ```
+
+2. **Run full test suite:**
+   ```bash
+   npm run build && npm test
+   ```
+
+3. **Review CHANGELOG:**
+   - Are all changes documented?
+   - Is the version number correct?
+
+4. **Create release branch:**
+   ```bash
+   git checkout -b release/v1.6.0
+   # Update version in package.json
+   git commit -am "chore: release v1.6.0"
+   ```
+
+## Conflict Prevention
+
+### When Parallel Work Happens
+
+If two features are being developed in parallel:
+
+1. **Communicate:** Let the team know what you're working on
+2. **Small PRs:** Merge frequently to reduce divergence
+3. **Rebase often:** Keep feature branches up to date with main
+
+```bash
+# Rebase feature branch on latest main
+git fetch origin
+git rebase origin/main
+```
+
+### When Merging a Large Feature
+
+For large features (>500 lines):
+
+1. **Create a tracking issue** documenting what's being added
+2. **Break into reviewable chunks** (≤300 lines per PR)
+3. **Merge incrementally** rather than one giant PR
+
+## Automation (Future)
+
+Consider adding GitHub Actions for:
+
+1. **Stale branch alerts:** Weekly notification of branches >14 days old
+2. **PR size warnings:** Flag PRs with >500 lines changed
+3. **Unmerged branch check:** CI fails if important branches are unmerged before release
+
+## Quick Reference
+
+```bash
+# Check for unmerged branches
+git branch -r --no-merged main | grep -v HEAD
+
+# Compare branch to main
+git log main..origin/feat/branch-name --oneline
+git diff --stat main...origin/feat/branch-name
+
+# Clean up after merge
+git push origin --delete feat/branch-name
+git branch -d feat/branch-name
+git remote prune origin
+```