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

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

# Workflow Guide: GitHub Actions vs Manual Publishing

## 🔄 **Two Publishing Methods**

You have two ways to publish packages. **Choose one per release** to avoid conflicts.

---

## Method 1: GitHub Actions (Automated) 🤖

**Use for**: Regular releases, team collaboration, audit trail

### How it works:
- Push to `develop` → Auto-publishes to `@spectrumsense/spectrum-chat-dev`
- Push to `main` → Auto-publishes to `@spectrumsense/spectrum-chat`

### Workflow:

```bash
# 1. Make your changes
git checkout develop
# ... edit files ...

# 2. Commit changes (version stays at base, e.g., 0.1.3)
git add .
git commit -m "feat: your feature description"

# 3. Push to develop - This triggers GitHub Actions
git push origin develop

# 4. GitHub Actions automatically:
#    ✅ Bumps version (0.1.3 → 0.1.4-dev.0)
#    ✅ Switches to @spectrumsense/spectrum-chat-dev
#    ✅ Builds with develop config
#    ✅ Publishes to npm with 'dev' tag
#    ✅ Creates GitHub pre-release

# 5. Check the result
#    - Actions tab: https://github.com/spectrumsense/spectrum-chat/actions
#    - npm: https://www.npmjs.com/package/@spectrumsense/spectrum-chat-dev
#    - unpkg: https://unpkg.com/@spectrumsense/spectrum-chat-dev@dev/
```

### ⚠️ Important Rules:
- **DON'T** manually bump version before pushing
- **DON'T** run `npm run publish:develop` locally
- **DO** keep version at base (e.g., `0.1.3`) in `package.json`
- **DO** let GitHub Actions handle version bumping

### For Production:
```bash
# 1. Merge develop into main
git checkout main
git merge develop

# 2. Manually bump version for production
npm version patch  # or minor/major
# This updates to 0.1.4 (no -dev suffix)

# 3. Commit and push
git add package.json
git commit -m "chore: release v0.1.4"
git push origin main

# 4. GitHub Actions automatically publishes to production package
```

---

## Method 2: Manual Publishing (Quick) 🚀

**Use for**: Quick testing, local development, before pushing

### Workflow:

```bash
# 1. Make your changes
# ... edit files ...

# 2. Bump version manually
npm run version:bump
# Updates version: 0.1.3 → 0.1.4-dev.0

# 3. Publish immediately from your machine
npm run publish:develop
# This publishes to @spectrumsense/spectrum-chat-dev

# 4. Verify
# npm: https://www.npmjs.com/package/@spectrumsense/spectrum-chat-dev
# unpkg: https://unpkg.com/@spectrumsense/spectrum-chat-dev@0.1.4-dev.0/

# 5. Commit and push (optional)
git add .
git commit -m "feat: your changes (v0.1.4-dev.0)"

# Option A: Push to feature branch (won't trigger publish)
git push origin feature/your-feature

# Option B: Push to develop (will trigger another publish!)
# ⚠️ WARNING: This will publish 0.1.4-dev.1
# Only do this if you want another version
```

### For Production:
```bash
# 1. Bump to production version
npm version patch  # 0.1.3 → 0.1.4

# 2. Publish manually
npm run publish:prod

# 3. Commit and push
git add .
git commit -m "chore: release v0.1.4"
git push origin main --tags
```

---

## 🤔 **Which Method Should I Use?**

### Use **GitHub Actions** if:
- ✅ Working with a team
- ✅ Want consistent releases
- ✅ Need audit trail and GitHub releases
- ✅ Can wait 2-3 minutes for CI/CD
- ✅ Want automated changelog

### Use **Manual Publishing** if:
- ✅ Need to test immediately
- ✅ Working alone on a feature
- ✅ Want to publish before pushing
- ✅ Testing a quick fix
- ✅ Don't want to trigger CI yet

---

## 🚨 **Common Mistakes & Solutions**

### Mistake 1: Mixed Approaches
```bash
# ❌ WRONG: Bumped locally AND pushed to develop
npm run version:bump        # Now at 0.1.4-dev.0
git push origin develop     # GitHub Actions bumps to 0.1.4-dev.1
# Result: Two versions published, confusion!
```

**Solution**: Pick one method per release

---

### Mistake 2: Forgot to Bump Version
```bash
# ❌ WRONG: Publishing without version bump
npm run publish:develop
# Error: 403 - Cannot publish over existing version
```

**Solution**: Always bump first when publishing manually
```bash
npm run version:bump
npm run publish:develop
```

---

### Mistake 3: Wrong Package Name
```bash
# ❌ WRONG: Using npm publish directly
npm publish
# Result: Wrong package name, wrong config
```

**Solution**: Always use the scripts
```bash
npm run publish:develop  # or publish:prod
```

---

## 📊 **Comparison Table**

| Feature | GitHub Actions | Manual |
|---------|---------------|--------|
| Speed | 2-3 minutes | Instant |
| Automation | Full | None |
| Version Control | Automatic | Manual |
| Package Name | Auto-switches | Auto-switches |
| GitHub Release | Auto-creates | Manual |
| Audit Trail | Yes | No |
| Requires Push | Yes | No |
| Team Friendly | Yes | No |

---

## 🎯 **Recommended Strategy**

### For Most Releases:
**Use GitHub Actions** - It's consistent and creates proper releases

```bash
# Regular workflow
git checkout develop
# make changes
git commit -am "feat: new feature"
git push origin develop
# ✅ Done! GitHub Actions handles publishing
```

### For Quick Testing:
**Use Manual Publishing** - When you need to test RIGHT NOW

```bash
# Quick test workflow
npm run version:bump
npm run publish:develop
# ✅ Test immediately on unpkg
# Push to feature branch later (not develop)
```

### For Production:
**Use GitHub Actions** - Ensures proper release process

```bash
# Production workflow
git checkout main
git merge develop
npm version minor  # Manual version bump for production
git push origin main --tags
# ✅ GitHub Actions publishes and creates release
```

---

## 🔍 **Your Current Situation**

You said:
> "I did npm run version:bump but do I need to do npm run publish:develop?"

**Answer**: You have two choices right now:

### Choice A: Publish Manually Now (Quick)
```bash
# You already bumped to 0.1.4-dev.0, so just publish
npm run publish:develop

# Then reset for future GitHub Actions
git checkout package.json  # Back to 0.1.3
git add package.json
git commit -m "chore: reset version for CI"
git push origin develop
```

**Result**: 
- ✅ `0.1.4-dev.0` is published NOW
- ✅ Future pushes use GitHub Actions properly

### Choice B: Revert and Use GitHub Actions
```bash
# Undo your version bump
git checkout package.json  # Back to 0.1.3

# Push to trigger GitHub Actions
git push origin develop
```

**Result**:
- ✅ GitHub Actions publishes `0.1.4-dev.0`
- ✅ Wait 2-3 minutes for CI/CD
- ✅ Clean automated process

---

## 💡 **My Recommendation for You**

Since you just merged a PR and want to release:

**Go with Choice A** (publish manually now):
```bash
npm run publish:develop
```

Then set up for future GitHub Actions use:
```bash
git checkout package.json
git add package.json
git commit -m "chore: reset version for CI"
git push origin develop
```

This gets your release out immediately while keeping your workflow clean for the future.

---

## 📚 **Additional Resources**

- **GitHub Actions**: `.github/workflows/publish.yml`
- **Manual Publishing**: `QUICK_PUBLISH.md`
- **Detailed Guide**: `PUBLISHING_WORKFLOW.md`
- **Package Scripts**: `package.json` → `scripts` section

---

**Questions?** Check which versions are published:
- Dev: https://www.npmjs.com/package/@spectrumsense/spectrum-chat-dev
- Prod: https://www.npmjs.com/package/@spectrumsense/spectrum-chat