@spectrumsense/spectrum-chat-dev/docs/VERSION_MANAGEMENT.md

Embeddable AI Widget - Add trusted, evidence-based answers directly to your website. Simple installation, enterprise-grade security.

# Version Management Guide

## 🎯 **How It Works**

The publishing workflow now includes **smart version bumping** that:
- **Ensures semantic versioning**: Dev versions are always ahead of production
- **Prevents 403 errors**: Automatically detects and skips already-published versions
- **Auto-bumps intelligently**: Compares with production and bumps base version when needed

---

## 📦 **Version Strategy**

### **In Your Repository (package.json)**

Keep the **base version** (e.g., `0.1.4`) without the `-dev.X` suffix:

```json
{
  "version": "0.1.4"
}
```

### **When Publishing to Dev**

The smart bump script automatically:

1. **Checks production version** on `@spectrumsense/spectrum-chat`
2. **Compares** current base version with production version
3. **Auto-bumps** base version if needed (e.g., if prod is `0.1.5`, bumps to `0.1.6`)
4. **Converts** to dev version (e.g., `0.1.6` → `0.1.6-dev.0`)
5. **Checks** if `0.1.6-dev.0` exists on npm
6. **Auto-increments** to `0.1.6-dev.1`, `0.1.6-dev.2`, etc. if needed
7. **Publishes** to `@spectrumsense/spectrum-chat-dev`

---

## 🔄 **Workflow Examples**

### **Example 1: Dev Version Behind Production (Auto-Bump)**

```bash
# Production has: 0.1.5
# package.json has: "version": "0.1.5"
git push origin develop

# GitHub Actions:
# 📊 Checks production version: 0.1.5
# ⚠️  Base version 0.1.5 is not ahead of production 0.1.5
# ✅ Auto-bumps base version: 0.1.5 → 0.1.6
# ✅ Converts 0.1.6 → 0.1.6-dev.0
# ✅ Checks npm: 0.1.6-dev.0 doesn't exist
# ✅ Publishes as 0.1.6-dev.0
```

### **Example 2: Dev Version Already Ahead**

```bash
# Production has: 0.1.5
# package.json has: "version": "0.1.6"
git push origin develop

# GitHub Actions:
# 📊 Checks production version: 0.1.5
# ✅ Base version 0.1.6 is ahead of production 0.1.5
# ✅ Converts 0.1.6 → 0.1.6-dev.0
# ✅ Checks npm: 0.1.6-dev.0 doesn't exist
# ✅ Publishes as 0.1.6-dev.0
```

### **Example 3: Multiple Dev Publishes (Same Base Version)**

```bash
# Production has: 0.1.5
# package.json has: "version": "0.1.6"
# npm dev already has: 0.1.6-dev.0, 0.1.6-dev.1

git push origin develop

# GitHub Actions:
# 📊 Checks production version: 0.1.5
# ✅ Base version 0.1.6 is ahead of production 0.1.5
# ✅ Converts 0.1.6 → 0.1.6-dev.0
# ⚠️  Checks npm: 0.1.6-dev.0 exists!
# ⚠️  Tries 0.1.6-dev.1: exists!
# ✅ Tries 0.1.6-dev.2: available!
# ✅ Publishes as 0.1.6-dev.2
```

---

## 🚀 **When to Manually Bump Version**

**Note:** With the new auto-bump feature, manual version bumps are optional! The script will automatically ensure dev is ahead of production. However, you can still manually bump for semantic clarity.

### **Scenario: New Feature Release (Bump Minor)**

When you want to release a new minor version (e.g., `0.1.x` → `0.2.0`):

```bash
# Bump the base version
npm run version:bump:minor
# package.json now: "version": "0.2.0"

# Commit and push
git add package.json
git commit -m "chore: bump version to 0.2.0"
git push origin develop

# GitHub Actions will publish as: 0.2.0-dev.0
```

### **Scenario: Bug Fix (Bump Patch) - OPTIONAL**

```bash
# You can manually bump, or let auto-bump handle it
npm run version:bump:patch
# 0.1.4 → 0.1.5

git add package.json
git commit -m "chore: bump version to 0.1.5"
git push origin develop

# Publishes as: 0.1.5-dev.0
```

### **Scenario: Breaking Changes (Bump Major)**

```bash
npm run version:bump:major
# 0.1.4 → 1.0.0

git add package.json
git commit -m "chore: bump version to 1.0.0"
git push origin develop

# Publishes as: 1.0.0-dev.0
```

### **Scenario: No Manual Bump (Let Auto-Bump Handle It)**

```bash
# Production is at: 0.1.5
# package.json is at: 0.1.5 (same as prod)
# Just push without manually bumping!

git push origin develop

# GitHub Actions automatically:
# - Detects base version equals production
# - Auto-bumps to 0.1.6
# - Publishes as: 0.1.6-dev.0
```

---

## 🎨 **Manual Publishing**

### **Quick Dev Release**

```bash
# From anywhere, just run:
npm run publish:develop

# This will:
# 1. Smart bump version (checks npm, auto-bumps if needed)
# 2. Switch to dev package name
# 3. Build with develop config
# 4. Publish to npm with 'dev' tag
# 5. Update 'latest' tag
```

### **Production Release**

```bash
# 1. Ensure version is a clean base (e.g., 0.1.4, not 0.1.4-dev.X)
# 2. Run:
npm run publish:prod

# This publishes to @spectrumsense/spectrum-chat (production)
```

---

## 📋 **Available Commands**

| Command | Purpose |
|---------|---------|
| `npm run version:bump` | Smart bump for dev (checks npm, auto-increments) |
| `npm run version:bump:patch` | Bump patch version (0.1.4 → 0.1.5) |
| `npm run version:bump:minor` | Bump minor version (0.1.4 → 0.2.0) |
| `npm run version:bump:major` | Bump major version (0.1.4 → 1.0.0) |
| `npm run publish:develop` | Smart bump + build + publish to dev |
| `npm run publish:prod` | Build + publish to production |
| `npm run tag:latest` | Update 'latest' tag manually |

---

## ✅ **Best Practices**

### **1. Keep Base Version in Repo**

❌ **Don't commit** `-dev.X` versions:
```json
{
  "version": "0.1.4-dev.2"  // ❌ Bad
}
```

✅ **Do commit** base versions:
```json
{
  "version": "0.1.4"  // ✅ Good
}
```

### **2. Let Automation Handle Everything**

- The smart bump script automatically:
  - Ensures dev version is ahead of production
  - Adds `-dev.0` and increments as needed
  - Bumps base version if it's not ahead of production
- You don't need to manually manage versions unless you want to!

### **3. Optional: Manually Bump for Semantic Clarity**

You can manually bump the base version when you have:
- **New features** → `npm run version:bump:minor`
- **Bug fixes** → `npm run version:bump:patch` (optional - auto-bump handles this)
- **Breaking changes** → `npm run version:bump:major`

But if you don't, the script will auto-bump patch version for you!

### **4. Semantic Versioning is Guaranteed**

The smart bump ensures dev is always ahead of production:
- If prod is `0.1.5` and base is `0.1.5`, it auto-bumps to `0.1.6`
- This prevents the semantic versioning issue where `0.1.5-dev.X` appears after `0.1.5` production

### **5. Don't Worry About 403 Errors**

The smart bump prevents them! If a version exists, it automatically finds the next available one.

---

## 🔍 **Troubleshooting**

### **Issue: Script says version exists but it doesn't**

```bash
# Check what's actually published
npm view @spectrumsense/spectrum-chat-dev versions

# If you see a discrepancy, there might be a cache issue
# Wait a few minutes and try again
```

### **Issue: Want to force a specific version**

```bash
# Manually edit package.json to the exact version you want
# (including -dev.X if needed)

# Then publish without auto-bump:
node scripts/update-package-name.js develop
npm run build:develop
npm publish --tag dev
node scripts/update-latest-tag.js
```

### **Issue: Need to unpublish a bad version**

```bash
# Unpublish specific version (only works within 72 hours)
npm unpublish @spectrumsense/spectrum-chat-dev@0.1.4-dev.5

# Then push again to re-publish with correct code
git push origin develop
```

---

## 🎯 **Summary**

**The Golden Rules:**

1. ✅ Keep base version in `package.json` (e.g., `0.1.4`)
2. ✅ Let GitHub Actions / smart bump handle everything automatically
3. ✅ Dev versions are always guaranteed to be ahead of production
4. ✅ No more 403 errors - script auto-finds available versions!
5. ✅ No more semantic versioning issues - dev is always semantically ahead of prod

**What's New:**

The smart bump script now checks the production package version and automatically ensures the dev base version is ahead. If you push with `0.1.5` and production already has `0.1.5`, it will auto-bump to `0.1.6` before creating the dev version. This maintains proper semantic versioning where `0.1.6-dev.X` is a pre-release of `0.1.6`, not something that comes after `0.1.5` production.

---

## 🔗 **Related Documentation**

- **Publishing Guide**: `docs/PUBLISHING_WORKFLOW.md`
- **unpkg Usage**: `docs/UNPKG_USAGE.md`
- **Quick Reference**: `QUICK_PUBLISH.md`

---

**Questions?** The smart bump script is at `scripts/smart-version-bump.js`