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

CHANGELOG.md - No version history file
Automated Release Notes - Manual entry required
Artifact Signing - No signing implemented
SBOM Generation - No software bill of materials
Version Automation - Manual VERSION file updates
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

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

Release Process Design

Pre-release Phase:
- Developer updates VERSION file
- Developer updates CHANGELOG.md (or runs script)
- Developer commits changes
- Developer creates and pushes version tag
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
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)

Create CHANGELOG.md:
- Initialize with current version (0.0.14)
- Add structure for unreleased changes
- Document all changes since initial development
Create Version Bump Script:
- Update VERSION file
- Update Qobuzarr.csproj
- Update plugin.json
- Validate semantic version format
Adopt Conventional Commits:
- Document in CONTRIBUTING.md
- Add commit message linting (optional)

Phase 2: Automation (High Priority)

Enhance release.yml Workflow:
- Add validation job
- Add comprehensive testing
- Add CHANGELOG extraction
- Add automated release notes
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
Implement Artifact Signing:
- Add Cosign keyless signing
- Or add GPG signing
- Document verification process

Phase 3: Advanced Features (Medium Priority)

Generate SBOM:
- Use Anchore or similar tool
- Attach SPDX JSON to releases
- Document dependency tree
Add Release Validation:
- Pre-release checklist automation
- Version consistency checks
- Documentation currency checks
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

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

Future Enhancements

Pre-release Channel: Beta releases from develop branch
Release Notifications: Discord/Slack announcements
Rollback Automation: Quick revert process
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:

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

Example 2: Create Release for v0.1.0

User: "Release version 0.1.0" Action:

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

Example 3: Fix Failed Release

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

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