Release Guide

Guide for creating and managing releases

Overview

Guide for creating and managing releases

Complete guide for creating and managing releases in Portfolio OS.

📋 Table of Contents

Release Process Overview
Semantic Versioning
Creating a Release
Pre-Releases
Automated Release Workflow
Troubleshooting

🎯 Release Process Overview

Portfolio OS uses an automated release system that:

âœ… Uses semantic versioning (SemVer)
âœ… Automates release creation via GitHub Actions
âœ… Extracts release notes from CHANGELOG.md
âœ… Supports pre-releases (alpha, beta, RC)
âœ… Generates release notes automatically

Release Workflow

graph LR
    A[Update CHANGELOG] --> B[Run Release Script]
    B --> C[Create Git Tag]
    C --> D[Push to GitHub]
    D --> E[GitHub Action Triggers]
    E --> F[Release Created]

📢 Semantic Versioning

We follow Semantic Versioning 2.0.0:

Version Format

MAJOR.MINOR.PATCH[-PRERELEASE]

Examples:
  1.0.0         - Stable release
  1.0.0-alpha.1 - Alpha pre-release
  1.0.0-beta.1  - Beta pre-release
  1.0.0-rc.1    - Release candidate
  1.0.1         - Patch release
  1.1.0         - Minor release
  2.0.0         - Major release

When to Increment

Version	When to Use	Example
MAJOR (2.0.0)	Breaking changes, major redesigns	Complete UI overhaul, API changes
MINOR (1.1.0)	New features, backwards compatible	New dashboard features, new pages
PATCH (1.0.1)	Bug fixes, minor improvements	Fix bugs, update dependencies

Pre-Release Types

alpha (1.0.0-alpha.1) - Early testing, unstable
beta (1.0.0-beta.1) - Feature complete, testing
rc (1.0.0-rc.1) - Release candidate, final testing

🚀 Creating a Release

Method 1: Using the Release Script (Recommended)

Stable Release

# Navigate to project root
cd C:\Users\jschi\OneDrive\Desktop\2025_portfolio\portfolio-os

# Create release
.\scripts\project-management\create-release.ps1 -Version "1.0.0"

Pre-Release

# Alpha release
.\scripts\project-management\create-release.ps1 -Version "1.0.0" -PreRelease "alpha.1"

# Beta release
.\scripts\project-management\create-release.ps1 -Version "1.0.0" -PreRelease "beta.1"

# Release candidate
.\scripts\project-management\create-release.ps1 -Version "1.0.0" -PreRelease "rc.1"

Dry Run (Preview)

# Preview what will happen
.\scripts\project-management\create-release.ps1 -Version "1.0.0" -DryRun

Method 2: Manual Release

# 1. Update CHANGELOG.md with release notes
# 2. Commit changes
git add CHANGELOG.md package.json
git commit -m "chore: Prepare release v1.0.0"
git push

# 3. Create and push tag
git tag -a v1.0.0 -m "Release v1.0.0 - Multi-Agent Development System"
git push origin v1.0.0

# 4. GitHub Action automatically creates the release

Method 3: Using GitHub CLI

# Create release directly
gh release create v1.0.0 \
  --title "🚀 Portfolio OS v1.0.0" \
  --notes-file CHANGELOG.md \
  --latest

ðŸ§ª Pre-Releases

Why Use Pre-Releases?

ðŸ§ª Test new features before stable release
ðŸ“Š Gather feedback from early users
ðŸ› Catch bugs before production
🎯 Staged rollout for risk mitigation

Pre-Release Workflow

# 1. Create alpha for early testing
.\scripts\project-management\create-release.ps1 -Version "1.1.0" -PreRelease "alpha.1"

# 2. After testing, create beta
.\scripts\project-management\create-release.ps1 -Version "1.1.0" -PreRelease "beta.1"

# 3. Final testing with release candidate
.\scripts\project-management\create-release.ps1 -Version "1.1.0" -PreRelease "rc.1"

# 4. Stable release
.\scripts\project-management\create-release.ps1 -Version "1.1.0"

Pre-Release Naming Convention

v1.1.0-alpha.1   - First alpha
v1.1.0-alpha.2   - Second alpha (if needed)
v1.1.0-beta.1    - First beta
v1.1.0-beta.2    - Second beta (if needed)
v1.1.0-rc.1      - Release candidate
v1.1.0           - Stable release

âš™ï¸ Automated Release Workflow

How It Works

The GitHub Action (.github/workflows/release.yml) automatically:

âœ… Detects when a version tag is pushed
âœ… Extracts version number and determines type
âœ… Reads release notes from CHANGELOG.md
âœ… Creates GitHub release with appropriate title
âœ… Marks as pre-release if applicable
âœ… Generates additional release notes from commits

Workflow Triggers

on:
  push:
    tags:
      - 'v*.*.*'      # Matches v1.0.0
      - 'v*.*.*-*'    # Matches v1.0.0-beta.1

Release Title Format

🚀 Stable: Portfolio OS v1.0.0
ðŸ”¬ Alpha: Portfolio OS v1.0.0-alpha.1 (Alpha)
ðŸ§ª Beta: Portfolio OS v1.0.0-beta.1 (Beta)
🎯 RC: Portfolio OS v1.0.0-rc.1 (Release Candidate)

Monitoring Releases

# Check GitHub Actions status
gh run list --workflow=release.yml

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

# Check latest release
gh release view --web

ðŸ“ Release Checklist

Before Release

Update CHANGELOG.md with release notes
Update version in package.json files
Run all tests: pnpm test
Run linting: pnpm lint
Build successfully: pnpm build
Commit and push all changes
Ensure you're on correct branch (main/develop)
No uncommitted changes

During Release

Run release script or create tag manually
Verify tag pushed to GitHub
Check GitHub Actions workflow started
Monitor workflow for errors

After Release

Verify release appears on GitHub
Check release notes are correct
Test release in production
Announce release (if applicable)
Update documentation if needed

ðŸ”§ Common Release Scenarios

Scenario 1: First Stable Release (v1.0.0)

# You're currently at v1.0.0 in package.json
.\scripts\project-management\create-release.ps1 -Version "1.0.0" -Message "First stable release"

Scenario 2: Bug Fix Release

# Fix bugs, update CHANGELOG.md, then:
.\scripts\project-management\create-release.ps1 -Version "1.0.1"

Scenario 3: New Feature Release

# Add features, update CHANGELOG.md, then:
.\scripts\project-management\create-release.ps1 -Version "1.1.0"

Scenario 4: Breaking Changes

# Major refactor, update CHANGELOG.md, then:
.\scripts\project-management\create-release.ps1 -Version "2.0.0"

Scenario 5: Testing New Feature

# Create beta for testing
.\scripts\project-management\create-release.ps1 -Version "1.2.0" -PreRelease "beta.1"

# After testing, stable release
.\scripts\project-management\create-release.ps1 -Version "1.2.0"

ðŸ› Troubleshooting

Issue: Tag Already Exists

âŒ Tag v1.0.0 already exists!

Solution:

Choose a different version number
Or delete existing tag: git tag -d v1.0.0 and git push origin :refs/tags/v1.0.0

Issue: GitHub Action Failed

âŒ Release workflow failed

Solution:

Check GitHub Actions tab
Review error logs
Common causes:
- Invalid CHANGELOG.md format
- Permissions issue
- Network error

Fix:

# Re-run the workflow
gh run rerun <run-id>

Issue: Release Not Showing

Tag pushed but no release created

Solution:

Check if GitHub Action ran: gh run list
Verify workflow file exists: .github/workflows/release.yml
Check repository permissions
Manually create release: gh release create v1.0.0 --notes-file CHANGELOG.md

Issue: Wrong Version in Release

Release created with wrong version number

Solution:

# Delete the release
gh release delete v1.0.0 --yes

# Delete the tag
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0

# Create again with correct version
.\scripts\project-management\create-release.ps1 -Version "1.0.1"

ðŸ“š Additional Resources

Commands Reference

# List all releases
gh release list

# View specific release
gh release view v1.0.0

# Download release assets
gh release download v1.0.0

# List all tags
git tag -l

# Delete tag locally
git tag -d v1.0.0

# Delete tag remotely
git push origin :refs/tags/v1.0.0

# View workflow runs
gh run list --workflow=release.yml

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

External Documentation

🎯 Quick Reference

Release Script Options

# Required
-Version "X.Y.Z"        # Version number (without 'v' prefix)

# Optional
-PreRelease "beta.1"    # Pre-release identifier
-Message "Description"  # Custom release message
-DryRun                 # Preview without making changes

Examples

# Stable release
.\scripts\project-management\create-release.ps1 -Version "1.0.0"

# Beta release
.\scripts\project-management\create-release.ps1 -Version "1.1.0" -PreRelease "beta.1"

# With custom message
.\scripts\project-management\create-release.ps1 -Version "1.0.1" -Message "Critical bug fixes"

# Dry run
.\scripts\project-management\create-release.ps1 -Version "1.0.0" -DryRun

Last updated: October 8, 2025

Releases & Security

Release Workflow

Release Guide

Overview

📋 Table of Contents

🎯 Release Process Overview

Release Workflow

📢 Semantic Versioning

Version Format

When to Increment

Pre-Release Types

🚀 Creating a Release

Method 1: Using the Release Script (Recommended)

Stable Release

Pre-Release

Dry Run (Preview)

Method 2: Manual Release

Method 3: Using GitHub CLI

ðŸ§ª Pre-Releases

Why Use Pre-Releases?

Pre-Release Workflow

Pre-Release Naming Convention

âš™ï¸ Automated Release Workflow

How It Works

Workflow Triggers

Release Title Format

Monitoring Releases

ðŸ“ Release Checklist

Before Release

During Release

After Release

ðŸ”§ Common Release Scenarios

Scenario 1: First Stable Release (v1.0.0)

Scenario 2: Bug Fix Release

Scenario 3: New Feature Release

Scenario 4: Breaking Changes

Scenario 5: Testing New Feature

ðŸ› Troubleshooting

Issue: Tag Already Exists

Issue: GitHub Action Failed

Issue: Release Not Showing

Issue: Wrong Version in Release

ðŸ“š Additional Resources

Commands Reference

External Documentation

🎯 Quick Reference

Release Script Options

Examples

âš™ï¸ Automated Release Workflow

ðŸ“ Release Checklist

ðŸ› Troubleshooting