prerelease-versions

What this skill does

# Prerelease Versions

Pre-release version management patterns including alpha, beta, and release candidate (RC) tagging with GitHub pre-release workflows.

## Overview

This skill provides comprehensive patterns for managing pre-release versions throughout the software development lifecycle. It supports semantic versioning pre-release identifiers (alpha, beta, rc) with GitHub Actions automation for safe pre-production testing.

## Pre-release Version Format

Semantic versioning pre-release format:
```
<major>.<minor>.<patch>-<prerelease>.<number>
```

Examples:
- `1.0.0-alpha.1` - First alpha release
- `1.0.0-alpha.2` - Second alpha release
- `1.0.0-beta.1` - First beta release
- `1.0.0-beta.2` - Second beta release
- `1.0.0-rc.1` - First release candidate
- `1.0.0-rc.2` - Second release candidate
- `1.0.0` - Stable release (promoted from RC)

## Pre-release Types

### Alpha (α)

**Purpose**: Internal testing, highly unstable, breaking changes expected

**Characteristics**:
- Incomplete features
- No stability guarantees
- Frequent breaking changes
- Internal team only
- Rapid iteration

**When to use**:
- Feature development in progress
- API design validation
- Internal dogfooding
- Proof of concept testing

### Beta (β)

**Purpose**: External testing, feature complete but may have bugs

**Characteristics**:
- Feature complete
- API mostly stable
- Known bugs expected
- Open to early adopters
- Limited breaking changes

**When to use**:
- Feature freeze reached
- Ready for wider testing
- Gathering user feedback
- Performance optimization
- Documentation review

### Release Candidate (RC)

**Purpose**: Final pre-release testing, production ready unless critical bugs found

**Characteristics**:
- Fully tested features
- API stable
- Only critical bug fixes
- Production environment testing
- No new features

**When to use**:
- All tests passing
- Documentation complete
- Ready for production
- Final validation
- Stakeholder approval

## Scripts

All scripts are located in `scripts/` and provide functional pre-release management.

### 1. create-prerelease.sh

Create a new pre-release version with automatic version calculation.

**Usage**:
```bash
bash scripts/create-prerelease.sh <prerelease_type> <base_version>
```

**Parameters**:
- `prerelease_type`: alpha, beta, or rc
- `base_version`: Target stable version (e.g., 1.0.0)

**Example**:
```bash
# Create first alpha release for version 1.0.0
bash scripts/create-prerelease.sh alpha 1.0.0
# Output: 1.0.0-alpha.1

# Create next alpha release
bash scripts/create-prerelease.sh alpha 1.0.0
# Output: 1.0.0-alpha.2
```

**Features**:
- Auto-increments pre-release number
- Updates VERSION file
- Updates manifest files (package.json, pyproject.toml)
- Creates git tag
- Validates semantic versioning format

### 2. promote-prerelease.sh

Promote a pre-release to the next stage or stable release.

**Usage**:
```bash
bash scripts/promote-prerelease.sh <current_version>
```

**Promotion Path**:
```
alpha.N → beta.1
beta.N → rc.1
rc.N → stable (removes pre-release identifier)
```

**Example**:
```bash
# Promote alpha to beta
bash scripts/promote-prerelease.sh 1.0.0-alpha.3
# Output: 1.0.0-beta.1

# Promote beta to RC
bash scripts/promote-prerelease.sh 1.0.0-beta.2
# Output: 1.0.0-rc.1

# Promote RC to stable
bash scripts/promote-prerelease.sh 1.0.0-rc.2
# Output: 1.0.0
```

**Features**:
- Automatic promotion logic
- Version file updates
- Manifest synchronization
- Git tag creation
- Changelog generation

### 3. test-prerelease.sh

Validate pre-release version format and readiness.

**Usage**:
```bash
bash scripts/test-prerelease.sh <version>
```

**Validations**:
- Semantic versioning format
- Pre-release identifier validity
- Version consistency across files
- Git tag availability
- Changelog entry presence

**Exit Codes**:
- `0`: All validations passed
- `1`: Format validation failed
- `2`: Consistency check failed
- `3`: Git tag conflict
- `4`: Changelog missing

**Example**:
```bash
# Validate alpha release
bash scripts/test-prerelease.sh 1.0.0-alpha.1

# Validate RC release
bash scripts/test-prerelease.sh 1.0.0-rc.1
```

## Templates

All templates are located in `templates/` and provide production-ready configurations.

### 1. github-prerelease-workflow.yml

GitHub Actions workflow for automated pre-release creation and testing.

**Location**: `templates/github-prerelease-workflow.yml`

**Features**:
- Automatic pre-release detection from branch name
- Parallel testing for alpha/beta/RC
- Pre-release asset uploading
- GitHub pre-release flag setting
- Notification integration

**Trigger Branches**:
- `alpha/*` → Creates alpha releases
- `beta/*` → Creates beta releases
- `release/*` → Creates RC releases

**Usage**:
```bash
# Copy to project
cp templates/github-prerelease-workflow.yml .github/workflows/prerelease.yml

# Customize as needed
vim .github/workflows/prerelease.yml
```

### 2. alpha-version-tag.template

Git tag annotation template for alpha releases.

**Location**: `templates/alpha-version-tag.template`

**Format**:
```
Alpha Release v{VERSION}

🚧 INTERNAL TESTING ONLY

This is an unstable alpha release for internal testing.
Breaking changes are expected in future releases.

Changes:
{CHANGELOG}

Testing:
- [ ] Unit tests passed
- [ ] Integration tests passed
- [ ] Manual testing completed

DO NOT USE IN PRODUCTION
```

### 3. beta-version-tag.template

Git tag annotation template for beta releases.

**Location**: `templates/beta-version-tag.template`

**Format**:
```
Beta Release v{VERSION}

🧪 EARLY ACCESS

This is a beta release for early adopters and testing.
Features are complete but bugs may exist.

Changes:
{CHANGELOG}

Testing:
- [ ] All tests passing
- [ ] Performance benchmarks completed
- [ ] Documentation reviewed
- [ ] Known issues documented

Use with caution in production environments.
```

### 4. rc-version-tag.template

Git tag annotation template for release candidates.

**Location**: `templates/rc-version-tag.template`

**Format**:
```
Release Candidate v{VERSION}

✅ PRODUCTION READY (pending final validation)

This release candidate is considered stable and ready for production
unless critical issues are discovered during final testing.

Changes:
{CHANGELOG}

Validation:
- [x] All tests passing
- [x] Performance validated
- [x] Documentation complete
- [x] Security audit completed
- [ ] Production deployment tested

Expected stable release: {EXPECTED_DATE}
```

### 5. prerelease-config.json

Configuration template for pre-release workflow settings.

**Location**: `templates/prerelease-config.json`

**Structure**:
```json
{
  "prerelease": {
    "alpha": {
      "branch_pattern": "alpha/*",
      "auto_increment": true,
      "testing_required": ["unit", "integration"],
      "notification_channels": ["slack-dev"],
      "retention_days": 30
    },
    "beta": {
      "branch_pattern": "beta/*",
      "auto_increment": true,
      "testing_required": ["unit", "integration", "e2e"],
      "notification_channels": ["slack-qa", "slack-dev"],
      "retention_days": 90
    },
    "rc": {
      "branch_pattern": "release/*",
      "auto_increment": true,
      "testing_required": ["unit", "integration", "e2e", "performance"],
      "notification_channels": ["slack-releases", "slack-qa"],
      "retention_days": 180
    }
  }
}
```

## Examples

All examples are located in `examples/` and demonstrate real-world workflows.

### 1. alpha-workflow.md

Complete alpha release workflow from creation to promotion.

**Location**: `examples/alpha-workflow.md`

**Covers**:
- Creating alpha branch
- Initial alpha release
- Iterative alpha releases
- Bug fixes in alpha
- Promoting to beta

### 2. beta-workflow.md

Complete beta release workflow including feedback integration.

**Location**: `examples/beta-workflow.md`

**Covers**:
- Beta release creation
- User feedback collection
- Bug fix releases
- Feature freeze enforcement
- Promotion to RC

### 3. rc-workflow.md

Complete release cand