release-automation

name	release-automation
description	Automate plugin releases, versioning, and changelog management. Use when working with releases, semantic versioning, release workflows, version bumping, CHANGELOG creation, or release note generation. Critical for establishing release process from scratch.

Release Automation Specialist

Mission

Establish and automate a complete release process for the Qobuzarr project, implementing semantic versioning, automated changelog generation, and GitHub release workflows.

Expertise Areas

1. Release Process Establishment

• Design release workflow from scratch
• Implement semantic versioning strategy
• Create version management system
• Establish changelog practices
• Define release checklist and procedures

2. Semantic Versioning

• Implement MAJOR.MINOR.PATCH versioning
• Handle pre-release versions (alpha, beta, rc)
• Coordinate version numbers across files
• Detect breaking changes for version bumps
• Manage version in single source of truth

3. Changelog Automation

• Create and maintain CHANGELOG.md
• Parse commit messages (conventional commits)
• Generate release notes from git history
• Categorize changes (features, fixes, breaking)
• Format release notes for GitHub releases

4. Release Workflow Creation

• Design GitHub Actions release workflow
• Implement automated release on tag push
• Add release validation and testing
• Create artifact packaging and publishing
• Handle manual release triggers

5. Artifact Management

• Package plugin as ZIP with proper structure
• Generate checksums for verification
• Implement artifact signing
• Attach assets to GitHub releases
• Version artifacts appropriately

Current Project Context

Qobuzarr Release Status

• Current Status: CRITICAL GAP - Manual release process only
• Current Version: 0.0.14
• Existing Release Workflow: release.yml (basic, manual notes)
• Version File: VERSION (exists)
• Build System: MSBuild with .NET 6.0
• Package Format: ZIP (Lidarr.Plugin.Qobuzarr-v{version}.zip)
• Missing: CHANGELOG.md, automated notes, signing, SBOM

Critical Missing Components

1. CHANGELOG.md - No version history file
2. Automated Release Notes - Manual entry required
3. Artifact Signing - No signing implemented
4. SBOM Generation - No software bill of materials
5. Version Automation - Manual VERSION file updates
6. Release Validation - Minimal pre-release checks

Key Files to Create/Maintain

• CHANGELOG.md - CREATE - Version history
• .github/workflows/release.yml - ENHANCE - Current basic workflow
• .github/scripts/bump-version.ps1 - CREATE - Version management
• .github/scripts/generate-release-notes.sh - CREATE - Note automation
• VERSION - Existing single source of truth
• Qobuzarr.csproj - Update version automatically
• plugin.json - Update version automatically

Best Practices

Version Management Strategy

1. Single Source of Truth: VERSION file is canonical
2. Automated Propagation: Script updates all references
3. Validation: Workflow validates tag matches VERSION
4. Version Locations to Sync:
   • VERSION file
   • Qobuzarr.csproj (Version, FileVersion, AssemblyVersion)
   • plugin.json (version field)

Release Process Design

1. Pre-release Phase:

   • Developer updates VERSION file
   • Developer updates CHANGELOG.md (or runs script)
   • Developer commits changes
   • Developer creates and pushes version tag

2. Automated Release Phase (GitHub Actions):

   • Extract version from tag
   • Validate tag matches VERSION file
   • Restore dependencies and build Release config
   • Run full test suite (mandatory)
   • Package plugin as ZIP
   • Generate checksums (SHA256)
   • Sign artifacts (Cosign or GPG)
   • Generate SBOM (SPDX format)
   • Generate release notes from CHANGELOG + commits
   • Create GitHub release
   • Attach artifacts
   • Update wiki/documentation

3. Post-release Phase:

   • Update latest tag
   • Notify users/community
   • Monitor for issues
   • Begin next version development

Conventional Commits

Adopt conventional commit format for automated changelog:

feat: add new quality profile selection
fix: correct album search query encoding
docs: update installation instructions
chore: bump dependencies
test: add integration tests for search
perf: optimize caching layer
refactor: restructure download service
BREAKING CHANGE: remove deprecated search API

CHANGELOG.md Format

# Changelog

All notable changes to Qobuzarr will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.1.0] - 2025-11-24

### Added
- ✨ Initial public release
- 🎵 Full Qobuz streaming integration
- 🔍 ML-powered search optimization (65.8% API reduction)
- 💾 Multi-layer caching (94.7% hit rate)
- 📊 Performance telemetry

### Fixed
- 🐛 Album metadata parsing for special characters
- 🔧 Download retry logic for transient failures

### Performance
- ⚡ Progressive search with fallback strategies
- ⚡ Reduced average search latency by 2.3 seconds

### Documentation
- 📝 Comprehensive API reference
- 📝 Deployment guide for Docker environments

## [0.0.14] - 2025-11-20

### Added
- Initial private beta release

Release Notes Template

## What's New in v0.1.0

### 🎉 First Public Release
Qobuzarr is now available for public testing! This plugin brings high-quality Qobuz streaming integration to Lidarr with advanced search capabilities.

### ✨ Features
- Full Qobuz API integration with authentication
- ML-powered query optimization reducing API calls by 65.8%
- Multi-layer caching system with 94.7% hit rate
- Progressive search with intelligent fallback
- Performance telemetry and monitoring

### 🐛 Bug Fixes
- Fixed album metadata parsing for albums with special characters
- Improved download retry logic for transient API failures

### ⚡ Performance
- Average search latency reduced by 2.3 seconds
- Optimized caching reduces API calls significantly

### 📝 Documentation
- Added comprehensive installation guide
- Added API reference documentation
- Added troubleshooting guide

### 🔒 Security
- Updated dependencies with latest security patches

**Full Changelog**: https://github.com/.../compare/v0.0.14...v0.1.0

---

## Installation

Download `Lidarr.Plugin.Qobuzarr-v0.1.0.zip` and extract to your Lidarr plugins directory.

See the [Installation Guide](docs/INSTALLATION.md) for detailed instructions.

Commands & Scripts to Create

1. Version Bump Script

File: .github/scripts/bump-version.ps1

# Bump version in VERSION, csproj, and plugin.json
param(
    [Parameter(Mandatory=$true)]
    [string]$Version
)
# Update VERSION file
# Update Qobuzarr.csproj
# Update plugin.json
# Validate format

2. Release Notes Generator

File: .github/scripts/generate-release-notes.sh

#!/bin/bash
# Extract CHANGELOG section for version
# Parse recent commits
# Format with emojis and categories
# Generate full changelog link

3. Tag Release Script

File: .github/scripts/tag-release.sh

#!/bin/bash
# Validate VERSION file
# Create annotated tag
# Push tag to origin

Workflow Enhancement

Enhanced release.yml Structure

name: Release

on:
  push:
    tags:
      - 'v*.*.*'
  workflow_dispatch:
    inputs:
      version:
        description: 'Release version (e.g., 0.1.0)'
        required: true

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Validate version format
      - name: Check tag matches VERSION file
      - name: Verify CHANGELOG updated

  build-and-test:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - name: Setup environment
      - name: Restore and build
      - name: Run tests (mandatory)

  package:
    needs: build-and-test
    runs-on: ubuntu-latest
    steps:
      - name: Build Release configuration
      - name: Package plugin ZIP
      - name: Generate checksums
      - name: Sign artifacts
      - name: Generate SBOM

  release:
    needs: package
    runs-on: ubuntu-latest
    steps:
      - name: Generate release notes
      - name: Create GitHub release
      - name: Upload artifacts
      - name: Update documentation

Implementation Roadmap

Phase 1: Foundation (Immediate)

1. Create CHANGELOG.md:

   • Initialize with current version (0.0.14)
   • Add structure for unreleased changes
   • Document all changes since initial development

2. Create Version Bump Script:

   • Update VERSION file
   • Update Qobuzarr.csproj
   • Update plugin.json
   • Validate semantic version format

3. Adopt Conventional Commits:

   • Document in CONTRIBUTING.md
   • Add commit message linting (optional)

Phase 2: Automation (High Priority)

4. Enhance release.yml Workflow:

   • Add validation job
   • Add comprehensive testing
   • Add CHANGELOG extraction
   • Add automated release notes

5. Create Release Notes Generator:

   • Parse CHANGELOG.md for current version
   • Parse git log for additional commits
   • Format with emojis and categories
   • Include full changelog link

6. Implement Artifact Signing:

   • Add Cosign keyless signing
   • Or add GPG signing
   • Document verification process

Phase 3: Advanced Features (Medium Priority)

7. Generate SBOM:

   • Use Anchore or similar tool
   • Attach SPDX JSON to releases
   • Document dependency tree

8. Add Release Validation:

   • Pre-release checklist automation
   • Version consistency checks
   • Documentation currency checks

9. Create Release Dashboard:

   • Track release metrics
   • Monitor download counts
   • Track issue reports post-release

Troubleshooting

Manual Release Process (Current)

Problem: Currently requires manual release note writing Solution: Follow implementation roadmap to automate

Version Synchronization

Problem: VERSION, csproj, plugin.json can get out of sync Solution: Create bump-version.ps1 script to update all at once

Missing CHANGELOG

Problem: No version history tracked Solution: Initialize CHANGELOG.md with historical versions

Enhancement Opportunities

Immediate Needs

1. CHANGELOG.md Creation: Critical for version tracking
2. Version Automation: Eliminate manual sync errors
3. Release Notes: Auto-generate from changelog + commits
4. Artifact Signing: Add security verification

Future Enhancements

5. Pre-release Channel: Beta releases from develop branch
6. Release Notifications: Discord/Slack announcements
7. Rollback Automation: Quick revert process
8. Release Analytics: Track adoption and issues

Related Skills

• code-quality - Ensure tests pass before release
• artifact-manager - Handle artifact lifecycle
• deployment-manager - Deploy releases to environments

Examples

Example 1: First Automated Release

User: "Set up automated releases for Qobuzarr" Action:

1. Create CHANGELOG.md with historical entries
2. Create bump-version.ps1 script
3. Create generate-release-notes.sh script
4. Enhance release.yml workflow
5. Document release process in CONTRIBUTING.md
6. Test with beta release

Example 2: Create Release for v0.1.0

User: "Release version 0.1.0" Action:

1. Run ./scripts/bump-version.ps1 -Version "0.1.0"
2. Update CHANGELOG.md with finalized changes
3. Commit: git commit -m "chore: release v0.1.0"
4. Tag: git tag -a v0.1.0 -m "Release 0.1.0"
5. Push: git push origin v0.1.0
6. Monitor release workflow
7. Verify GitHub release created with notes

Example 3: Fix Failed Release

User: "The release workflow failed on tests" Action:

1. Review test failure logs
2. Fix failing tests
3. Commit fix
4. Delete failed tag: git tag -d v0.1.0 && git push origin :refs/tags/v0.1.0
5. Re-create tag after fix
6. Re-trigger release