Skip to content

RELEASE-PROCESS.md

Latest commit

 

History

History
287 lines (200 loc) · 8.61 KB

RELEASE-PROCESS.md

File metadata and controls

287 lines (200 loc) · 8.61 KB

Automated Release Process

This document explains the automated release process for SomonScript using semantic-release and multi-registry publishing.

Overview

The project now uses semantic-release to automatically:

  • Determine the next version number based on commit messages
  • Generate release notes and changelog
  • Create GitHub releases
  • Publish to multiple package registries (NPM, JSR, GitHub Packages)
  • Update documentation

Supported Package Registries

1. NPM Registry (Primary)

2. JSR (JavaScript Registry)

3. GitHub Packages

Conventional Commits

All commits must follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types and Version Impact

Type Description Version Bump Example
feat New feature Minor (0.1.0) feat: add union type support
fix Bug fix Patch (0.0.1) fix: resolve parser memory leak
perf Performance improvement Patch (0.0.1) perf: optimize lexer tokenization
docs Documentation changes Patch (0.0.1) docs: update API examples
style Code style changes Patch (0.0.1) style: fix indentation
refactor Code refactoring Patch (0.0.1) refactor: extract type checker
build Build system changes Patch (0.0.1) build: update TypeScript config
test Test changes No release test: add parser unit tests
ci CI/CD changes No release ci: update GitHub Actions
chore Maintenance tasks No release chore: update dependencies
revert Revert previous commit Patch (0.0.1) revert: undo union type changes

Breaking Changes (Major Version)

To trigger a major version bump (1.0.0), include BREAKING CHANGE: in the commit footer:

feat: redesign type system API

BREAKING CHANGE: The TypeChecker class constructor now requires a config parameter

Examples

# Minor release (new feature)
git commit -m "feat: add intersection types support"

# Patch release (bug fix)
git commit -m "fix: handle empty string literals correctly"

# Major release (breaking change)
git commit -m "feat: redesign compiler API

BREAKING CHANGE: Compiler.compile() now returns Promise<CompileResult> instead of CompileResult"

# No release (internal change)
git commit -m "test: add comprehensive type system tests"

Release Triggers

Automatic Releases

Releases are automatically triggered when commits are pushed to:

  • main branch: Production releases (latest)
  • develop branch: Development pre-releases (dev)
  • beta branch: Beta pre-releases (beta)

Manual Releases

You can manually trigger a release using:

# Dry run (test without actual release)
npm run release:dry

# Actual release (if you have permissions)
npm run release

Or via GitHub Actions workflow dispatch with dry-run option.

Release Process Flow

  1. Pull Request Validation (New!)

    • Comprehensive quality checks on every PR
    • Multi-Node.js version testing (20.x & 22.x)
    • Smart change detection (only runs relevant checks)
    • Automatic merge blocking if validation fails
    • Success/failure status posted to PR

  2. Validation Phase

    • Run full test suite across supported Node.js versions (20.x & 22.x)
    • Validate architecture quality (no 'as any', union types working)
    • Check modular structure
    • Performance benchmark validation

  3. Semantic Release Phase

    • Analyze commits since last release
    • Determine next version number
    • Generate changelog and release notes
    • Update package.json version
    • Create Git tag
    • Publish to NPM
    • Create GitHub release

  4. Multi-Registry Publishing

    • Publish to JSR with updated version
    • Publish to GitHub Packages
    • Update documentation

  5. Post-Release

    • Update README with installation instructions
    • Generate API documentation
    • Commit documentation changes

Branch Strategy

Main Branch (main)

  • Purpose: Production releases
  • Trigger: Every push creates a release
  • Version: Standard semantic versions (1.0.0, 1.1.0, 1.1.1)
  • NPM Tag: @latest

Develop Branch (develop)

  • Purpose: Development previews
  • Trigger: Every push creates a pre-release
  • Version: Pre-release versions (1.1.0-dev.1, 1.1.0-dev.2)
  • NPM Tag: @dev

Beta Branch (beta)

  • Purpose: Beta testing
  • Trigger: Every push creates a beta release
  • Version: Beta versions (1.1.0-beta.1, 1.1.0-beta.2)
  • NPM Tag: @beta

Installation Commands by Registry

For End Users

# NPM (recommended for most users)
npm install -g @lindentech/somon-script

# JSR (recommended for TypeScript projects)
npx jsr add @lindentechde/somon-script

# GitHub Packages (for enterprise/private usage)
npm install @lindentechde/somon-script --registry=https://npm.pkg.github.com

For Developers

# Install specific version
npm install @lindentech/somon-script@1.2.3

# Install beta version
npm install @lindentech/somon-script@beta

# Install development version
npm install @lindentech/somon-script@dev

Environment Setup Requirements

For Contributors

No additional setup required - just follow conventional commits!

For Maintainers

Required secrets in GitHub repository settings:

  1. NPM_TOKEN: NPM automation token for publishing

  2. GITHUB_TOKEN: Automatically provided by GitHub Actions

    • Permissions: Contents (write), Issues (write), Pull Requests (write)

For JSR Publishing

  • JSR uses GitHub OIDC authentication (automatic)
  • Repository must be linked to JSR package at https://jsr.io

Troubleshooting

Release Not Triggered

  1. Check commit message format (must follow conventional commits)
  2. Ensure you're pushing to main, develop, or beta branch
  3. Check GitHub Actions logs for validation failures

Publishing Failures

  1. NPM: Check NPM_TOKEN secret and permissions
  2. JSR: Ensure repository is linked to JSR package
  3. GitHub Packages: Check GitHub token permissions

Version Not Bumped

  • Only commits with feat, fix, perf, docs, style, refactor, build, or revert trigger releases
  • Commits with test, ci, or chore do not trigger releases

Migration from Manual Releases

What Changed

  • ❌ No more manual version bumping in package.json
  • ❌ No more manual tag creation
  • ❌ No more manual changelog updates
  • ✅ Automatic versioning based on commits
  • ✅ Automatic multi-registry publishing
  • ✅ Automatic changelog generation

Best Practices

  1. Write meaningful commit messages following conventional commits
  2. Use conventional types appropriate for your changes
  3. Add breaking change notes when introducing breaking changes
  4. Test thoroughly before pushing to main
  5. Use branch protection to ensure PR reviews

Monitoring Releases

Support

For questions about the release process:

  1. Check GitHub Actions logs
  2. Review this documentation
  3. Create an issue with the release label
  4. Contact the maintainers

This automated release process ensures consistent, reliable, and multi-platform distribution of SomonScript across all major JavaScript package registries.