# Automated Release System Setup

## 🎯 Overview

This project now has a **fully automated release system** that:

1. **Automatically detects release types** from commit messages
2. **Creates releases on every merge to main** (when there are changes)
3. **Generates changelogs** from conventional commits
4. **Publishes to npm** automatically
5. **Provides manual fallback** for special cases

## 🔄 How It Works

### Automated Flow

```plain
Push to main → Tests run → Analyze commits → Determine release type → Create release
```

1. **Trigger**: Any push to the `main` branch (usually PR merges)
2. **Testing**: Full test suite runs to ensure quality
3. **Analysis**: System examines commits since last release
4. **Decision**: Release type determined by commit messages:
   - `major`: Breaking changes (`!:` or `BREAKING CHANGE:`)
   - `minor`: New features (`feat:`)
   - `patch`: Everything else (`fix:`, `docs:`, `chore:`, etc.)
5. **Release**: If changes exist, creates GitHub release + npm publish

### Manual Fallback

```plain
Create tag → Manual release workflow → Create release
```

For hotfixes or special releases, you can still use manual methods.

## 📁 Workflow Files

### `.github/workflows/auto-release.yml`

- **Purpose**: Main automated release workflow
- **Trigger**: Push to main branch
- **Jobs**:
  - `test`: Run tests
  - `determine-release`: Analyze commits and decide release type
  - `release`: Create release and publish

### `.github/workflows/release.yml`

- **Purpose**: Manual release fallback
- **Trigger**: Push of version tags (`v*`)
- **Use case**: Manual releases, hotfixes

### `.github/workflows/test.yml`

- **Purpose**: Quality assurance
- **Trigger**: PRs and pushes to main
- **Jobs**: Run tests and linting

## 🎯 Release Type Detection

The system analyzes commit messages since the last release:

### Major Release (X.0.0)

```bash
git commit -m "feat!: remove deprecated API"
git commit -m "feat: new system

BREAKING CHANGE: Old methods no longer work"
```

### Minor Release (0.X.0)

```bash
git commit -m "feat: add OAuth2 support"
git commit -m "feat(auth): implement JWT tokens"
```

### Patch Release (0.0.X)

```bash
git commit -m "fix: resolve memory leak"
git commit -m "docs: update API docs"
git commit -m "chore: update dependencies"
```

## 🛠️ Configuration Details

### Commit Analysis Logic

```bash
# Check for breaking changes first
if echo "$COMMITS" | grep -q "BREAKING CHANGE\|!:"; then
  RELEASE_TYPE="major"
# Then check for new features
elif echo "$COMMITS" | grep -q "^feat"; then
  RELEASE_TYPE="minor"
# Default to patch
else
  RELEASE_TYPE="patch"
fi
```

### Version Calculation

Uses the `@pawel-up/semver` package for proper semantic versioning:

```javascript
import SemVer from '@pawel-up/semver/classes/semver.js';
const ver = new SemVer(currentVersion);
ver.inc(releaseType);
return ver.format();
```

### Changelog Generation

Uses `conventional-changelog` package with the `conventionalcommits` preset via a Node.js script (`scripts/generate-changelog.js`):

```bash
node scripts/generate-changelog.js
```

This approach uses the `conventional-changelog` library directly instead of the CLI tool, which resolves security vulnerabilities in the older `conventional-changelog-cli` package.

## 🔧 Setup Requirements

### GitHub Secrets

- `GITHUB_TOKEN`: Automatically provided
- `NPM_TOKEN`: Required for npm publishing

### Dependencies

- `conventional-changelog-cli`: For changelog generation
- `@pawel-up/semver`: For version calculation
- `@commitlint/config-conventional`: For commit validation

### Permissions

The workflows require these permissions:

- `contents: write` - Create releases and tags
- `issues: write` - Update issues
- `pull-requests: write` - Update PRs

## 🚀 Usage Examples

### Normal Development Flow

1. **Create feature branch**

   ```bash
   git checkout -b feature/new-auth
   ```

2. **Make changes with proper commits**

   ```bash
   git commit -m "feat: add OAuth2 authentication"
   git commit -m "docs: update authentication docs"
   ```

3. **Create PR and merge to main**
   - PR triggers test workflow
   - Merge triggers auto-release workflow
   - System creates minor release automatically

### Hotfix Flow

1. **Create hotfix branch**

   ```bash
   git checkout -b hotfix/critical-bug
   ```

2. **Fix and commit**

   ```bash
   git commit -m "fix: resolve critical memory leak"
   ```

3. **Merge to main**
   - System creates patch release automatically

### Manual Release (if needed)

```bash
# For immediate release
npm run release:patch

# Or create tag manually
git tag v1.2.3
git push origin v1.2.3
```

## 🔍 Monitoring and Debugging

### Workflow Logs

Check the GitHub Actions tab to see:

- Which commits were analyzed
- What release type was determined
- Why a release was or wasn't created

### Common Issues

1. **No release created**: No new commits since last tag
2. **Wrong release type**: Check commit message format
3. **Tests failing**: Release won't proceed
4. **Permission errors**: Check GitHub token permissions

### Debugging Commands

```bash
# Check last tag
git describe --tags --abbrev=0

# See commits since last tag
git log --pretty=format:"%s" $(git describe --tags --abbrev=0)..HEAD

# Check conventional commit format
npx commitlint --edit .git/COMMIT_EDITMSG
```

## 🎉 Benefits

1. **Zero manual intervention** for regular releases
2. **Consistent release process** with proper semantic versioning
3. **Automatic changelog generation** from commit history
4. **Quality gates** with automated testing
5. **Flexible fallback** for special cases
6. **Proper audit trail** with conventional commits

This setup provides a modern, automated release system that follows industry best practices and reduces manual work while ensuring quality and consistency.
