# Release Guide

This project uses an **automated release system** with conventional commits and GitHub Actions. Releases are automatically created when changes are merged to the main branch.

## 🚀 Automated Releases (Recommended)

### How It Works

1. **Push to main branch** (usually via PR merge)
2. **Tests run automatically** to ensure quality
3. **System analyzes commit messages** since the last release
4. **Release type is determined automatically:**
   - `major` - if commits contain "breaking:" or "!:"
   - `minor` - if commits contain "feat:" (new features)
   - `patch` - for all other changes (bug fixes, docs, etc.)
5. **Release is created automatically** with changelog and npm publish

### Commit Message Examples

```bash
# Major release (breaking changes)
git commit -m "feat!: remove deprecated API"
git commit -m "feat: new system

BREAKING CHANGE: Old methods no longer work"

# Minor release (new features)
git commit -m "feat: add OAuth2 support"
git commit -m "feat(auth): implement JWT tokens"

# Patch release (bug fixes, docs, etc.)
git commit -m "fix: resolve memory leak"
git commit -m "docs: update API documentation"
git commit -m "chore: update dependencies"
```

### What Happens Automatically

1. ✅ Tests run to ensure everything works
2. ✅ Version is bumped in `package.json`
3. ✅ Changes are committed with conventional commit message
4. ✅ Git tag is created (e.g., `v1.2.3`)
5. ✅ GitHub release is created with automated changelog
6. ✅ Package is published to npm

## 🔧 Manual Releases (Fallback)

If you need to create a release manually (e.g., for hotfixes or special releases):

### Option 1: Use the release script

```bash
# Create a patch release (bug fixes)
npm run release:patch

# Create a minor release (new features)
npm run release:minor

# Create a major release (breaking changes)
npm run release:major

# Or use the default (patch)
npm run release
```

### Option 2: Manual tag creation

```bash
npm run build
# Update version in package.json
npm version patch --no-git-tag-version

# Commit the change
git add package.json
git commit -m "chore: bump version to X.Y.Z"

# Create and push tag
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z
```

## 📋 Conventional Commits

The release system uses conventional commits to generate changelogs. Your commit messages should follow this format:

```plain
type(scope): description

[optional body]

[optional footer]
```

### Commit Types

- `feat`: New features (triggers minor release)
- `fix`: Bug fixes (triggers patch release)
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

### Breaking Changes

To indicate a breaking change, use either:

- `!:` in the commit message: `feat!: remove deprecated API`
- `BREAKING CHANGE:` in the commit body:

  ```plain
  feat: new authentication system
  
  BREAKING CHANGE: Old auth methods are no longer supported
  ```

## 🔄 Workflow Comparison

| Aspect | Automated Release | Manual Release |
|--------|------------------|----------------|
| **Trigger** | Push to main | Tag push or script |
| **Release Type** | Auto-detected from commits | Manually specified |
| **Effort** | Zero - fully automated | Manual intervention |
| **Use Case** | Regular development flow | Hotfixes, special releases |

## 🛠️ Configuration

The release system is configured in:

- `.github/workflows/auto-release.yml` - Automated release workflow
- `.github/workflows/release.yml` - Manual release workflow (fallback)
- `scripts/release.js` - Manual release automation script
- `commitlint.config.js` - Conventional commits configuration
- `package.json` - Version management and scripts

## 🚨 Troubleshooting

### Common Issues

1. **No release created**: Check if commits follow conventional format
2. **Wrong release type**: Ensure commit messages use correct prefixes
3. **Tests failing**: Release won't proceed if tests fail
4. **Permission denied**: Ensure GitHub token has write permissions

### Debugging

The automated workflow logs will show:

- Last tag found
- Commits since last tag
- Determined release type
- Calculated new version

### Rollback

If you need to rollback a release:

1. Delete the tag locally: `git tag -d vX.Y.Z`
2. Delete the tag on GitHub: `git push origin :refs/tags/vX.Y.Z`
3. Revert the version in `package.json`
4. Commit the revert: `git commit -m "chore: revert version to X.Y.Z"`
5. Push the changes: `git push origin main`
