@dreamhorizonorg/sentinel/RELEASE.md

Open-source, zero-dependency tool that blocks compromised packages BEFORE download. Built to counter supply chain and credential theft attacks like Shai-Hulud.

# Release Process Guide

This document explains how to release a new version of Sentinel Package Manager.

## 📋 Pre-Release Checklist

Before releasing, ensure:

- [ ] All changes are committed and pushed to the main branch
- [ ] `CHANGELOG.md` has an "Unreleased" section with your changes (the script will auto-update it)
- [ ] `NPM_TOKEN` secret is configured in GitHub repository settings (Settings → Secrets → Actions)
- [ ] You're on the main branch and have latest changes pulled

## 🚀 Release Process

### Option 1: Using the Release Script (Recommended)

The easiest way to release:

```bash
# For patch release (1.0.0 → 1.0.1)
./scripts/release.sh patch

# For minor release (1.0.0 → 1.1.0)
./scripts/release.sh minor

# For major release (1.0.0 → 2.0.0)
./scripts/release.sh major

# For specific version
./scripts/release.sh 1.2.3
```

**What the script does automatically:**
1. Shows current version from package.json
2. Calculates new version (or uses specified version)
3. **Auto-updates CHANGELOG.md** (replaces "Unreleased" with dated version)
4. Asks for confirmation
5. Updates `package.json` version
6. Runs smoke tests locally
7. Commits both `package.json` and `CHANGELOG.md`
8. Creates an annotated git tag
9. Shows you the push commands

**Then push:**
```bash
git push && git push origin v1.0.0
```

### Option 2: Manual Release Process

If you prefer to do it manually (not recommended - script is easier):

#### Step 1: Update CHANGELOG.md

Move "Unreleased" section to a dated version:

```markdown
## [1.0.0] - 2024-12-02

### Added
- Your changes here
```

#### Step 2: Update package.json

```bash
# Edit package.json and change version to "1.0.0"
```

#### Step 3: Run Tests

```bash
npm run test:smoke
```

#### Step 4: Commit Changes

```bash
git add package.json CHANGELOG.md
git commit -m "chore: release v1.0.0"
```

#### Step 5: Create and Push Tag

```bash
# Create annotated tag
git tag -a v1.0.0 -m "Release v1.0.0"

# Push commit and tag
git push && git push origin v1.0.0
```

**Note**: The script automates all of this, so manual process is rarely needed.

## ⚙️ What Happens Automatically

Once you push the tag, GitHub Actions workflow (`release.yml`) automatically:

1. **Security Checks**
   - ✅ Verifies no package installations in workflows
   - ✅ Confirms zero dependencies in package.json
   - ✅ Checks no node_modules directory exists
   - ✅ Validates package.json integrity
   - ✅ Verifies npm token is valid

2. **Version Verification**
   - ✅ Extracts version from tag
   - ✅ Verifies version matches package.json

3. **Testing**
   - ✅ Runs smoke tests

4. **Publishing**
   - ✅ Runs npm publish dry-run (verifies package contents)
   - ✅ Publishes to npm as `@dreamhorizonorg/sentinel@1.0.0`

5. **GitHub Release**
   - ✅ Extracts changelog from CHANGELOG.md
   - ✅ Creates GitHub release with:
     - Release notes from changelog
     - npm package link
     - Installation instructions
     - Links to documentation

## 📊 Complete Release Flow

### Step-by-Step Process

```
┌─────────────────────────────────────────────────────────────┐
│ 1. PREPARE (Before Release)                                 │
├─────────────────────────────────────────────────────────────┤
│ • Add changes to CHANGELOG.md under "Unreleased" section   │
│ • Commit and push your code changes to main branch          │
│ • Ensure NPM_TOKEN is set in GitHub Secrets                 │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. RUN RELEASE SCRIPT (Local)                               │
├─────────────────────────────────────────────────────────────┤
│ $ ./scripts/release.sh patch                                │
│                                                              │
│ Script automatically:                                        │
│ ✅ Calculates version (1.0.0 → 1.0.1)                       │
│ ✅ Updates CHANGELOG.md (Unreleased → [1.0.1] - date)      │
│ ✅ Updates package.json version                             │
│ ✅ Runs tests locally                                        │
│ ✅ Creates commit                                            │
│ ✅ Creates tag: v1.0.1                                       │
│                                                              │
│ Output: "git push && git push origin v1.0.1"                │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. PUSH TAG (Developer)                                      │
├─────────────────────────────────────────────────────────────┤
│ $ git push && git push origin v1.0.1                        │
│                                                              │
│ This triggers release.yml workflow                          │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. GITHUB ACTIONS (Automatic)                                │
├─────────────────────────────────────────────────────────────┤
│ release.yml workflow runs:                                  │
│                                                              │
│ Security Checks:                                             │
│ ✅ No package installations in workflows                    │
│ ✅ Zero dependencies verified                                │
│ ✅ No node_modules directory                                │
│ ✅ Package.json integrity check                             │
│                                                              │
│ Verification:                                                │
│ ✅ Version matches package.json                             │
│                                                              │
│ Testing:                                                     │
│ ✅ Runs smoke tests                                          │
│                                                              │
│ Publishing:                                                  │
│ ✅ Validates npm token                                       │
│ ✅ Dry-run publish (verifies contents)                      │
│ ✅ Publishes to npm: @dreamhorizonorg/sentinel@1.0.1       │
│                                                              │
│ Release:                                                     │
│ ✅ Extracts changelog from CHANGELOG.md                     │
│ ✅ Creates GitHub release with notes                         │
│ ✅ Links npm package ↔ GitHub release                        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. DONE! ✅                                                  │
├─────────────────────────────────────────────────────────────┤
│ • Package published to npm                                  │
│ • GitHub release created                                    │
│ • Both are linked together                                   │
│ • Users can install: npm install -g @dreamhorizonorg/sentinel│
└─────────────────────────────────────────────────────────────┘
```

## 🔍 Verifying the Release

After the workflow completes:

1. **Check npm**: https://www.npmjs.com/package/@dreamhorizonorg/sentinel
   - Verify the new version is published
   - Check package contents

2. **Check GitHub Release**: https://github.com/dream-horizon-org/sentinel/releases
   - Verify release is created
   - Check release notes are correct
   - Verify npm link works

3. **Test Installation**:
   ```bash
   npm install -g @dreamhorizonorg/sentinel@1.0.0
   sentinel --version
   ```

## 🐛 Troubleshooting

### Workflow Fails at Security Check

**Issue**: "Dependencies detected in package.json"
- **Solution**: Ensure package.json has no `dependencies` or `devDependencies` fields

**Issue**: "NPM_TOKEN is missing or invalid"
- **Solution**: Add `NPM_TOKEN` secret in GitHub repository settings (Settings → Secrets → Actions)

### Workflow Fails at Version Check

**Issue**: "Version mismatch"
- **Solution**: Ensure tag version (e.g., `v1.0.0`) matches package.json version (`1.0.0`)

### npm Publish Fails

**Issue**: "Package already exists"
- **Solution**: Version already published. Use a new version number.

**Issue**: "Authentication failed"
- **Solution**: Verify `NPM_TOKEN` has publish permissions for `@dreamhorizonorg` scope

## 📝 Complete Example: Releasing v1.0.1

### Before Release

```bash
# 1. Make sure you're on main branch with latest changes
git checkout main
git pull origin main

# 2. Add your changes to CHANGELOG.md under "Unreleased"
# Edit CHANGELOG.md:
#   ## [Unreleased]
#   
#   ### Added
#   - New feature X
#   - Bug fix Y
```

### Release Process

```bash
# 3. Run the release script
./scripts/release.sh patch

# Output you'll see:
# 📦 Current version: 1.0.0
# 🚀 New version: 1.0.1
# 📝 Auto-updating CHANGELOG.md...
# ✅ Updated CHANGELOG.md: '## [1.0.1] - 2024-12-02'
# Continue with release? [y/N]: y
# 📝 Updating package.json...
# 🧪 Running tests...
# ✅ Tests passed
# 📝 Committing version bump...
# 🏷️  Creating tag: v1.0.1
# ✅ Release prepared!
# 
# Next steps:
#   git push && git push origin v1.0.1

# 4. Push the tag (triggers GitHub Actions)
git push && git push origin v1.0.1
```

### After Push

```bash
# 5. Watch the workflow run (takes 2-5 minutes)
# Go to: https://github.com/dream-horizon-org/sentinel/actions
# Click on the latest "Release" workflow run

# 6. Verify the release completed:
# ✅ All security checks passed
# ✅ Tests passed
# ✅ Published to npm
# ✅ GitHub release created

# 7. Check the results:
# - npm: https://www.npmjs.com/package/@dreamhorizonorg/sentinel/v/1.0.1
# - GitHub: https://github.com/dream-horizon-org/sentinel/releases/tag/v1.0.1

# 8. Test installation:
npm install -g @dreamhorizonorg/sentinel@1.0.1
sentinel --version  # Should show v1.0.1
```

## 🔐 Security Notes

- **Zero Dependencies**: The workflow verifies package.json has no dependencies
- **No Installations**: No `npm install`, `yarn install`, etc. ever runs
- **Multiple Checks**: Security checks run before every publish
- **Fail Fast**: Workflow stops immediately if any security check fails
- **Dry Run**: npm publish is tested with `--dry-run` before actual publish
- **Token Validation**: npm token is verified before publishing

## 🎯 Key Points to Remember

1. **CHANGELOG.md**: Add your changes under "Unreleased" section BEFORE running the script
   - The script will automatically replace "Unreleased" with the version and date
   - You only need to write WHAT changed, not the version/date

2. **Version Format**: 
   - Tag format: `v1.0.1` (with 'v' prefix)
   - package.json format: `1.0.1` (no 'v' prefix)
   - Script handles this automatically

3. **Two-Step Process**:
   - Step 1: Run script locally (prepares release)
   - Step 2: Push tag (triggers GitHub Actions to publish)

4. **What's Automated**:
   - ✅ Version calculation
   - ✅ CHANGELOG.md date update
   - ✅ package.json version update
   - ✅ Test execution
   - ✅ Commit creation
   - ✅ Tag creation
   - ✅ npm publishing
   - ✅ GitHub release creation

5. **What's Manual**:
   - Writing changelog content (what changed)
   - Running the script
   - Pushing the tag

## 🧪 Testing the Release Process

### Option 1: Local Test Script (Recommended)

Test everything locally without creating tags or publishing:

```bash
# Test the release process locally
./scripts/release-test.sh patch

# This will:
# ✅ Test CHANGELOG.md update logic
# ✅ Test package.json version update
# ✅ Run all security checks
# ✅ Test npm publish dry run
# ✅ Verify version matching
# ❌ Does NOT create commits or tags
# ❌ Does NOT publish anything
```

### Option 2: GitHub Actions Test Workflow

Test the full workflow in GitHub Actions without publishing:

```bash
# 1. Create a test tag (starts with "test-v")
git tag -a test-v1.0.1 -m "Test release v1.0.1"
git push origin test-v1.0.1

# 2. Watch the "Release Test (Dry Run)" workflow run
# Go to: https://github.com/dream-horizon-org/sentinel/actions

# This will:
# ✅ Run all security checks
# ✅ Run tests
# ✅ Test npm publish dry run
# ✅ Generate release notes
# ❌ Does NOT publish to npm
# ❌ Does NOT create GitHub release
```

### Option 3: Manual Workflow Dispatch

Test via GitHub Actions UI:

1. Go to: Actions → "Release Test (Dry Run)" → "Run workflow"
2. Enter version: `1.0.1`
3. Click "Run workflow"
4. Watch it execute all checks without publishing

### What Gets Tested

- ✅ All security checks (zero dependencies, no node_modules, etc.)
- ✅ Version verification
- ✅ Package integrity
- ✅ Tests execution
- ✅ npm publish dry run (shows what would be published)
- ✅ Release notes generation
- ✅ Workflow logic

### Cleanup After Testing

```bash
# Delete test tag locally
git tag -d test-v1.0.1

# Delete test tag from remote
git push origin :refs/tags/test-v1.0.1
```

## 📚 Related Files

- `.github/workflows/release.yml` - Release workflow definition
- `.github/workflows/release-test.yml` - Test workflow (no publish)
- `scripts/release.sh` - Release helper script
- `scripts/release-test.sh` - Test script (local, no publish)
- `CHANGELOG.md` - Changelog format
- `package.json` - Package metadata and version