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

# 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 scripts/promote-prerelease.sh <current_version>

Promotion Path:

alpha.N → beta.1
beta.N → rc.1
rc.N → stable (removes pre-release identifier)

Example:

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

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

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

{
  "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 candidate workflow to stable release.

Location: examples/rc-workflow.md

Covers:

RC creation
Production validation
Hotfix handling
Stakeholder approval
Stable release promotion

4. multi-prerelease-pipeline.md

Managing multiple concurrent pre-release tracks.

Location: examples/multi-prerelease-pipeline.md

Covers:

Parallel alpha/beta releases
Feature branch integration
Version conflict resolution
Backport strategies

Integration with Commands

This skill supports versioning plugin commands:

/versioning:bump - Extended with --prerelease flag
/versioning:info - Shows pre-release status
/versioning:rollback - Supports pre-release rollback

Best Practices

Alpha Stage

Release frequently - Daily or per-feature releases
Document breaking changes - Track API changes
Internal only - Never expose to external users
Fast iteration - Rapid development cycles
Version cleanup - Archive old alphas regularly

Beta Stage

Feature freeze - No new features, only bug fixes
Wider testing - Include early adopters
Gather feedback - Document user issues
Performance testing - Validate at scale
Documentation review - Ensure docs match features

RC Stage

Minimal changes - Critical fixes only
Production testing - Test in production-like environment
Stakeholder approval - Get sign-off before stable
Final documentation - Complete all docs
Release notes - Prepare comprehensive release notes

General

Clear communication - Announce each pre-release
Version consistency - Keep all files synchronized
Automated testing - Use CI/CD for all pre-releases
GitHub pre-release flag - Mark appropriately in GitHub
Retention policy - Clean up old pre-releases

Troubleshooting

Version Number Conflicts

If version already exists:

# Check existing tags
git tag -l "v1.0.0-*"

# Delete conflicting tag
git tag -d v1.0.0-alpha.1

# Recreate with correct number
bash scripts/create-prerelease.sh alpha 1.0.0

Promotion Issues

If promotion fails:

# Validate current version
bash scripts/test-prerelease.sh 1.0.0-alpha.3

# Check promotion path
# alpha.N → beta.1 → rc.1 → stable

# Force promotion if needed
bash scripts/promote-prerelease.sh 1.0.0-alpha.3 --force

GitHub Workflow Failures

If GitHub Actions workflow fails:

# Check workflow logs
gh run list --workflow=prerelease.yml

# View specific run
gh run view <run-id>

# Re-run failed jobs
gh run rerun <run-id>

Inconsistent Versions

If versions are out of sync:

# Check all version locations
bash scripts/test-prerelease.sh 1.0.0-beta.1

# Manual sync if needed
# Update VERSION file
echo '{"version": "1.0.0-beta.1"}' > VERSION

# Update package.json
npm version 1.0.0-beta.1 --no-git-tag-version

# Update pyproject.toml
sed -i 's/version = .*/version = "1.0.0-beta.1"/' pyproject.toml

prerelease-versions

Prerelease Versions

Overview

Pre-release Version Format

Pre-release Types

Alpha (α)

Beta (β)

Release Candidate (RC)

Scripts

1. create-prerelease.sh

2. promote-prerelease.sh

3. test-prerelease.sh

Templates

1. github-prerelease-workflow.yml

2. alpha-version-tag.template

3. beta-version-tag.template

4. rc-version-tag.template

5. prerelease-config.json

Examples

1. alpha-workflow.md

2. beta-workflow.md

3. rc-workflow.md

4. multi-prerelease-pipeline.md

Integration with Commands

Best Practices

Alpha Stage

Beta Stage

RC Stage

General

Troubleshooting

Version Number Conflicts

Promotion Issues

GitHub Workflow Failures

Inconsistent Versions

See Also

Similar Skills