yt2ai/docs/RELEASE.md

# Release Process Documentation

## Overview

YT2AI uses automated semantic versioning and release management through [semantic-release](https://semantic-release.gitbook.io/). All releases are triggered automatically based on conventional commit messages.

## Semantic Versioning

### Version Format
- **MAJOR** (`x.0.0`) - Breaking changes that are incompatible with previous versions
- **MINOR** (`x.y.0`) - New features that are backward compatible
- **PATCH** (`x.y.z`) - Bug fixes and improvements that are backward compatible

### Automated Version Bumping

Based on conventional commit prefixes:

| Commit Type | Version Bump | Example |
|-------------|-------------|---------|
| `feat:` | **MINOR** | `feat: add Claude.ai RPA integration` |
| `fix:` | **PATCH** | `fix: handle network timeout errors` |
| `perf:` | **PATCH** | `perf: optimize subtitle parsing performance` |
| `BREAKING CHANGE:` | **MAJOR** | Any commit with breaking change footer |
| `revert:` | **PATCH** | `revert: remove experimental feature` |
| `docs:` (README) | **PATCH** | `docs(README): update installation guide` |
| `chore(deps):` | **PATCH** | `chore(deps): update webpack to 5.89` |

## Conventional Commits

### Commit Message Format
```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Commit Types

#### Production Impact
- `feat:` - New feature for users
- `fix:` - Bug fix for users
- `perf:` - Performance improvement
- `revert:` - Revert previous commit

#### Development/Infrastructure  
- `build:` - Build system changes
- `ci:` - Continuous integration changes
- `docs:` - Documentation changes
- `style:` - Code style changes (formatting, etc.)
- `refactor:` - Code refactoring without feature/bug changes
- `test:` - Test additions or corrections
- `chore:` - Other changes (maintenance, deps, etc.)

### Examples

#### Feature Addition
```bash
git commit -m "feat: add support for YouTube Shorts URLs

- Extract video ID from /shorts/ URL format
- Update URL validation regex patterns
- Add unit tests for Shorts URL parsing"
```

#### Bug Fix
```bash
git commit -m "fix: handle mobile network timeout gracefully

- Increase timeout to 30s for mobile connections
- Add retry logic for failed network requests
- Improve error messages for network issues

Fixes #123"
```

#### Breaking Change
```bash
git commit -m "feat: redesign mobile overlay system

BREAKING CHANGE: MobileOverlay constructor now requires 
configuration object instead of individual parameters.

Migration: 
- Old: new MobileOverlay('id', 'type', 'content')  
- New: new MobileOverlay({id, type, content})"
```

## Release Workflow

### Automated Release (Recommended)

1. **Create feature branch:**
   ```bash
   git checkout -b feature/add-new-feature
   ```

2. **Make changes and commit with conventional format:**
   ```bash
   # Use commitizen for guided commit messages
   npm run commit
   
   # Or manual conventional commit
   git commit -m "feat: add subtitle language selection"
   ```

3. **Push and create pull request:**
   ```bash
   git push origin feature/add-new-feature
   # Create PR via GitHub interface
   ```

4. **Merge to main:**
   - PR is reviewed and approved
   - Merge to `main` branch triggers automated release

5. **Automated release process:**
   - CI runs tests and builds
   - Semantic-release analyzes commits
   - Version is bumped automatically
   - CHANGELOG.md is updated
   - GitHub release is created
   - Build artifacts are attached

### Manual Release (Emergency)

Only for hotfixes or when automation fails:

```bash
# Checkout main and ensure it's up to date
git checkout main
git pull origin main

# Run full verification
npm run verify

# Create manual release (dry run first)
npm run release:dry

# If dry run looks good, create actual release
npm run release
```

## Branch Strategy

### Main Branch (`main`)
- **Production-ready code only**
- **Protected branch** - requires PR approval
- **Triggers automated releases** on push
- **Always buildable and deployable**

### Development Branch (`develop`) - Optional
- **Feature integration branch**  
- **Pre-release testing**
- **Beta releases** (version format: `1.2.0-beta.1`)

### Feature Branches
- **Naming:** `feature/short-description` or `feat/issue-123`
- **Lifetime:** Until merged to main/develop
- **Base:** Created from `main` or `develop`

### Hotfix Branches
- **Naming:** `hotfix/urgent-fix-description`
- **Lifetime:** Very short - immediate merge
- **Base:** Created from `main`
- **Target:** Merge directly to `main`

## Release Artifacts

### GitHub Release Assets

Each release automatically includes:

1. **Production Bookmarklet**
   - `yt2ai-bookmarklet-{version}.min.js`
   - Ready for end-user installation
   - Minified and optimized (8-10KB)

2. **Readable Bookmarklet**  
   - `yt2ai-bookmarklet-{version}.readable.js`
   - Human-readable version for debugging
   - Same functionality, unminified

3. **Build Documentation**
   - `build-documentation-{version}.md`
   - Build system documentation snapshot
   - Version-specific build information

### Changelog Generation

Automatically generated sections:

- ✨ **Features** - New functionality (`feat:`)
- 🐛 **Bug Fixes** - Issue resolutions (`fix:`)
- ⚡ **Performance** - Performance improvements (`perf:`)
- 📚 **Documentation** - Documentation updates (`docs:`)
- 🔧 **Build System** - Build/tooling changes (`build:`, `ci:`)
- ♻️ **Refactoring** - Code refactoring (`refactor:`)
- ✅ **Tests** - Testing updates (`test:`)

## Quality Gates

### Pre-Release Validation

Before any release, the following must pass:

1. **Linting:** `npm run lint` - Code style compliance
2. **Formatting:** `npm run format:check` - Code formatting
3. **Unit Tests:** `npm test` - All tests pass with 80%+ coverage
4. **Build Success:** `npm run build` - Production build completes
5. **Bundle Size:** <10KB limit enforced
6. **Bookmarklet Format:** Proper `javascript:` prefix validation

### Security Scanning

- **Dependency Audit:** `npm audit` - No high/critical vulnerabilities
- **CodeQL Analysis:** Automated code security scanning
- **Manual Security Review:** For significant changes

## Version Management

### Package.json Updates

Semantic-release automatically updates:
- `version` field in package.json
- `package-lock.json` version references

### Code Version Injection

Build process injects version into code:
```javascript
window.__YT2AI_VERSION__ = process.env.npm_package_version || '1.0.0';
```

## Troubleshooting

### Release Fails to Generate

1. **Check commit format:**
   ```bash
   # Review recent commits
   git log --oneline -10
   
   # Validate against conventional format
   npx commitlint --from=HEAD~5
   ```

2. **Run dry-run to debug:**
   ```bash
   npm run release:dry
   ```

3. **Check for required changes:**
   - Must have releasable commit types (`feat`, `fix`, etc.)
   - Cannot release if no changes since last release

### Version Number Issues

1. **Reset version if needed:**
   ```bash
   # Check current version
   npm run version
   
   # View semantic-release analysis
   npm run release:dry
   ```

2. **Fix package.json manually:**
   - Only in extreme cases
   - Commit as `chore(release): fix version numbering`

### CI/CD Pipeline Failures

1. **Check GitHub Actions logs:**
   - Go to Actions tab in GitHub
   - Review failed step outputs
   - Common issues: test failures, build errors, permission issues

2. **Re-run failed jobs:**
   - Often temporary infrastructure issues
   - Click "Re-run failed jobs" in GitHub Actions

## Development Workflow

### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/yt2ai/yt2ai-bookmarklet.git
cd yt2ai-bookmarklet

# Install dependencies
npm install

# Setup git hooks
npm run prepare

# Verify setup
npm run verify
```

### Daily Development
```bash
# Create feature branch
git checkout -b feat/my-new-feature

# Make changes, then use guided commit
npm run commit

# Push and create PR
git push origin feat/my-new-feature
```

### Pre-Release Testing
```bash
# Full verification pipeline
npm run verify

# Test with debug version
npm run dev

# Manual testing on mobile device
# Install dist/bookmarklet-debug.js
```

## Monitoring Releases

### Release Health Checks

After each release:

1. **Installation Test:** Verify bookmarklet installs correctly
2. **Functionality Test:** Test core features on real YouTube videos
3. **Performance Test:** Verify bundle size and execution speed
4. **Mobile Test:** Test on actual Android Chrome device

### Rollback Process

If critical issues found in production:

1. **Immediate:** Create hotfix branch with urgent fix
2. **If unfixable:** Revert problematic commit and re-release
3. **Communication:** Update GitHub issues and documentation

```bash
# Hotfix process
git checkout main
git checkout -b hotfix/critical-mobile-bug

# Make minimal fix
git commit -m "fix: critical mobile overlay rendering issue"

# Push and merge immediately
git push origin hotfix/critical-mobile-bug
# Create PR and merge to main
```

## Release Schedule

### Automated Releases
- **Triggered by:** Merge to main branch
- **Frequency:** As needed based on changes
- **Time:** Within 10 minutes of merge

### Planned Releases
- **Major versions:** Quarterly (as needed)
- **Minor versions:** Bi-weekly to monthly  
- **Patch versions:** As needed for bugs

### Communication
- **GitHub Releases:** Automatic notification
- **README updates:** Include latest version info
- **Documentation:** Keep installation guides current

---

## Quick Reference

### Useful Commands
```bash
npm run commit        # Guided conventional commit
npm run release:dry   # Test release without publishing
npm run version      # Show current version
git log --oneline    # Review recent commits
npx commitlint --help # Commit message validation help
```

### Commit Types Quick Reference
- `feat:` → Minor version bump (new features)
- `fix:` → Patch version bump (bug fixes)  
- `BREAKING CHANGE:` → Major version bump (breaking changes)
- `docs:`, `chore:`, `ci:` → Usually no version bump

For questions about the release process, check [semantic-release documentation](https://semantic-release.gitbook.io/) or open a GitHub issue.