yt2ai/docs/RELEASE.md

Release Process Documentation

Overview

YT2AI uses automated semantic versioning and release management through semantic-release. 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

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

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

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:

   git checkout -b feature/add-new-feature
   

2. Make changes and commit with conventional format:

   # 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:

   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:

# 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:

window.__YT2AI_VERSION__ = process.env.npm_package_version || '1.0.0';

Troubleshooting

Release Fails to Generate

1. Check commit format:

   # Review recent commits
   git log --oneline -10
   
   # Validate against conventional format
   npx commitlint --from=HEAD~5
   

2. Run dry-run to debug:

   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:

   # 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

# 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

# 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

# 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

# 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

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 or open a GitHub issue.