Release Management

aegir release [options]

Options:
  --build           Build project before release (default: true)
  --types           Generate TypeScript declarations (default: true)  
  --test            Run tests before release (default: true)
  --lint            Run linting before release (default: true)
  --contributors    Update contributors list (default: true)
  --bump            Bump package version (default: true)
  --changelog       Generate/update changelog (default: true)
  --publish         Publish to npm registry (default: true)
  --commit          Create release commit (default: true)
  --tag             Create git tag for release (default: true)
  --push            Push changes to remote (default: true)
  --ghrelease       Create GitHub release (default: true)
  --docs            Generate and publish documentation (default: true)
  --ghtoken         GitHub access token for releases
  --type            Version bump type (major|minor|patch|prerelease)
  --preid           Prerelease identifier (alpha|beta|rc)
  --distTag         npm dist-tag for publishing (default: 'latest')
  --remote          Git remote name (default: 'origin')

interface ReleaseOptions {
  /** Build project before release */
  build: boolean;
  /** Generate TypeScript declarations */
  types: boolean;
  /** Run tests before release */
  test: boolean;
  /** Run linting before release */
  lint: boolean;
  /** Update contributors list */
  contributors: boolean;
  /** Bump package version */
  bump: boolean;
  /** Generate/update changelog */
  changelog: boolean;
  /** Publish to npm registry */
  publish: boolean;
  /** Create release commit */
  commit: boolean;
  /** Create git tag for release */
  tag: boolean;
  /** Push changes to remote repository */
  push: boolean;
  /** Generate GitHub release */
  ghrelease: boolean;
  /** Generate and publish documentation */
  docs: boolean;
  /** GitHub access token for releases */
  ghtoken: string;
  /** Version bump type */
  type: 'major' | 'minor' | 'patch' | 'prepatch' | 'preminor' | 'premajor' | 'prerelease';
  /** Prerelease identifier */
  preid?: string;
  /** npm dist-tag for publishing */
  distTag: string;
  /** Git remote name */
  remote: string;
  /** Monorepo sibling dependency update message */
  siblingDepUpdateMessage: string;
  /** Git user name for sibling updates */
  siblingDepUpdateName: string;
  /** Git email for sibling updates */
  siblingDepUpdateEmail: string;
}

# Standard release
aegir release

# Skip tests and linting
aegir release --no-test --no-lint

# Pre-release
aegir release --type prerelease --preid beta

# Publish to beta tag
aegir release --distTag beta

# Skip documentation
aegir release --no-docs

# Custom GitHub token
aegir release --ghtoken $GITHUB_TOKEN

// .aegir.js
module.exports = {
  release: {
    build: true,
    test: true,
    lint: true,
    type: 'patch',
    distTag: 'latest',
    ghrelease: true,
    docs: true,
    ghtoken: process.env.GITHUB_TOKEN
  }
};

// Built-in semantic-release plugins:
// - @semantic-release/commit-analyzer: Analyze commits for version bumps
// - @semantic-release/release-notes-generator: Generate release notes
// - @semantic-release/changelog: Update CHANGELOG.md
// - @semantic-release/npm: Publish to npm registry
// - @semantic-release/github: Create GitHub releases
// - @semantic-release/git: Commit and tag releases

# Version bump triggers:
# - feat: minor version bump (new features)
# - fix: patch version bump (bug fixes)  
# - BREAKING CHANGE: major version bump
# - chore, docs, style, refactor, test: patch bump
# - Custom rules via configuration

# Patch release (1.0.0 -> 1.0.1)
git commit -m "fix: resolve authentication issue"

# Minor release (1.0.0 -> 1.1.0)  
git commit -m "feat: add user profile management"

# Major release (1.0.0 -> 2.0.0)
git commit -m "feat!: redesign API with breaking changes"
# or
git commit -m "feat: new API

BREAKING CHANGE: API restructured, see migration guide"

# Changelog

## [1.2.0](https://github.com/user/repo/compare/v1.1.0...v1.2.0) (2023-12-01)

### Features

* add user authentication ([abc123](https://github.com/user/repo/commit/abc123))
* implement data validation ([def456](https://github.com/user/repo/commit/def456))

### Bug Fixes  

* resolve memory leak in cache ([ghi789](https://github.com/user/repo/commit/ghi789))

### Documentation

* update API documentation ([jkl012](https://github.com/user/repo/commit/jkl012))

# Publishing features:
# - Automatic authentication via npm token
# - Dist-tag support (latest, beta, alpha, etc.)
# - Scope support (@organization/package)
# - Registry configuration
# - Provenance generation (npm provenance)

// package.json
{
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/",
    "provenance": true
  }
}

# GitHub features:
# - Automatic release creation
# - Release notes from changelog
# - Asset uploads (if configured)
# - Release tagging
# - Pull request integration
# - Branch protection compliance

# Pre-release examples:
aegir release --type prerelease --preid alpha  # 1.0.0-alpha.1
aegir release --type prerelease --preid beta   # 1.0.0-beta.1  
aegir release --type prerelease --preid rc     # 1.0.0-rc.1

# Pre-release dist-tags:
aegir release --type prerelease --preid beta --distTag beta
# npm install package@beta

aegir release-rc [options]

Options:
  --retries         Number of retry attempts for publish operations (default: 3)
  --tag             npm dist-tag for RC publishing (default: 'rc') 
  --prefix          Prefix output with package name (default: false)
  --concurrency     Parallel release limit for monorepos (default: 1)

interface ReleaseRcOptions {
  /** Number of retry attempts for publish operations */
  retries: number;
  /** npm dist-tag for RC publishing */
  tag: string;
  /** Prefix output with package name for monorepos */
  prefix?: boolean;
  /** Parallel release limit for monorepos */
  concurrency?: number;
}

# Monorepo features:
# - Cross-package dependency updates
# - Coordinated version bumping
# - Sibling dependency alignment
# - Parallel publishing with concurrency control
# - Selective package releasing

// .aegir.js
module.exports = {
  release: {
    siblingDepUpdateMessage: 'deps: update sibling dependencies',
    siblingDepUpdateName: 'Release Bot',
    siblingDepUpdateEmail: 'release@myproject.com'
  }
};

# Release workflow:
1. Pre-flight checks (git status, branch validation)
2. Build project (if --build)
3. Run tests (if --test)  
4. Run linting (if --lint)
5. Update contributors (if --contributors)
6. Analyze commits for version bump
7. Update package.json version (if --bump)
8. Generate/update changelog (if --changelog)
9. Build documentation (if --docs)
10. Create release commit (if --commit)
11. Create git tag (if --tag)
12. Publish to npm (if --publish)
13. Push to remote (if --push)
14. Create GitHub release (if --ghrelease)
15. Publish documentation (if --docs)

# Error scenarios:
# - Build failures: Release stops, no changes made
# - Test failures: Release stops, no changes made
# - Publish failures: Retries with exponential backoff
# - Git conflicts: Manual resolution required
# - Authentication failures: Clear error messages with solutions

# Dry run (not directly supported, but can be simulated)
# Use individual commands to test workflow:
aegir build
aegir test  
aegir lint
# ... manual verification

# GitHub Actions example
name: Release

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, '[skip ci]')"
    steps:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0
      
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Release
        run: npx aegir release
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}