ash-library-release

name	ash-library-release
description	Manages version releases for ash_cookie_consent Elixir library including CHANGELOG updates, version bumping, quality checks, Hex.pm publishing, and git tagging. Use when user asks to "release", "publish to hex", "bump version", "create release", or "prepare for publishing".

AshCookieConsent Library Release Management

This skill guides you through releasing a new version of the ash_cookie_consent library to Hex.pm.

When to Use This Skill

Activate this skill when the user requests:

• "Release version X.Y.Z"
• "Publish to Hex.pm"
• "Prepare for release"
• "Bump version to X.Y.Z"
• "Create a new release"

Prerequisites Check

Before starting, verify:

1. Clean working directory:

   git status
   

   All changes should be committed.

2. On main branch and up to date:

   git branch --show-current  # Should show: main
   git pull origin main
   

3. User has Hex credentials:

   mix hex.user whoami
   

   If not authenticated, run: mix hex.user auth

Release Workflow

Step 1: Determine Version Number

Ask user for version number if not provided. Follow Semantic Versioning:

• MAJOR (X.0.0): Breaking changes, incompatible API changes
• MINOR (0.X.0): New features, backward compatible
• PATCH (0.0.X): Bug fixes, backward compatible

Pre-1.0 note: While version < 1.0.0, MINOR can include breaking changes.

Step 2: Update CHANGELOG.md

1. Read current CHANGELOG.md

2. Move all items from [Unreleased] section to new version section:

   ## [X.Y.Z] - YYYY-MM-DD
   
   ### Added
   - Feature descriptions from [Unreleased]
   
   ### Changed
   - Changes from [Unreleased]
   
   ### Fixed
   - Bug fixes from [Unreleased]
   

3. Add today's date (YYYY-MM-DD format)

4. Update comparison links at bottom of file

5. Ensure [Unreleased] section is empty but present

Quality check:

• All significant changes documented
• Breaking changes clearly marked
• User-facing language (not internal jargon)
• Issue/PR numbers referenced where applicable

Step 3: Bump Version in mix.exs

1. Read mix.exs
2. Update @version "X.Y.Z" at top of file
3. Verify no other version references need updating

Step 4: Run Quality Checks

Execute all quality checks and report results:

# 1. Tests
mix test

# 2. Formatting
mix format --check-formatted

# 3. Credo (strict mode)
mix credo --strict

# 4. Dialyzer
mix dialyzer

# 5. Documentation build
mix docs

Required: All must pass with 0 errors/warnings before proceeding.

If any fail:

• Fix issues
• Re-run checks
• Update changelog if fixes are significant

Step 5: Build and Review Package

# Build package
mix hex.build

Review package contents:

1. Check file list in output
2. Verify size is reasonable (should be ~30-40KB)
3. Confirm no test files included
4. Confirm no .claude directory included
5. List contents if needed: tar -tf ash_cookie_consent-X.Y.Z.tar

Step 6: Commit Version Bump

git add CHANGELOG.md mix.exs
git commit -m "Bump version to X.Y.Z"

Commit message format: Always use Bump version to X.Y.Z for consistency.

Step 7: Create and Push Git Tag

# Create annotated tag
git tag -a vX.Y.Z -m "Release vX.Y.Z"

# Push commits and tag
git push origin main
git push origin vX.Y.Z

Tag format: Always prefix with v (e.g., v0.2.0)

Step 8: Publish to Hex.pm

mix hex.publish

The command will:

1. Show package details
2. Show files to be included
3. Show dependencies
4. Prompt: "Proceed? [Yn]"

Action: Inform user to type y to confirm.

After publishing:

• Note the published version
• Save package checksum if shown

Step 9: Create GitHub Release

If gh CLI is available:

gh release create vX.Y.Z \
  --title "vX.Y.Z - Brief Description" \
  --notes "See [CHANGELOG.md](https://github.com/shotleybuilder/ash_cookie_consent/blob/main/CHANGELOG.md#vXYZ) for full details."

If gh not available:

• Provide manual instructions to create release on GitHub
• Include link: https://github.com/shotleybuilder/ash_cookie_consent/releases/new

Step 10: Post-Release Verification

Verify release succeeded:

1. Hex.pm package:

   open https://hex.pm/packages/ash_cookie_consent
   

   • Verify version shows correctly
   • Check documentation built

2. GitHub release:

   open https://github.com/shotleybuilder/ash_cookie_consent/releases
   

   • Verify release created
   • Check tag points to correct commit

Step 11: Post-Release Checklist

Present this checklist to user:

• Verify package published on Hex.pm
• Verify documentation built on hexdocs.pm
• Verify GitHub release created
• Announce on Elixir Forum (optional)
• Announce on Ash Discord (optional)
• Update roadmap/milestones (if applicable)

Troubleshooting

"mix hex.publish" fails with authentication error

Solution:

mix hex.user auth

Re-authenticate and try again.

Documentation fails to build

Solution:

1. Run mix docs locally
2. Fix any errors in module documentation
3. Commit fixes
4. Restart release process from Step 6

Tests fail during quality checks

Solution:

1. Fix failing tests
2. Add changelog entry under ### Fixed if user-facing
3. Restart release process from Step 2

Package size is too large

Solution:

1. Check files: list in mix.exs package config
2. Ensure test files, docs, and .claude excluded
3. Rebuild: mix hex.build

Quick Reference: Common Release Types

Patch Release (Bug Fix)

Example: 0.1.0 → 0.1.1

## [0.1.1] - 2025-11-XX

### Fixed
- Fix consent expiration calculation (#42)
- Correct cookie encoding for edge case (#43)

Minor Release (New Features)

Example: 0.1.0 → 0.2.0

## [0.2.0] - 2025-XX-XX

### Added
- Built-in database sync helpers
- Multi-language support (EN, ES, FR, DE)

### Changed
- Improved performance of cookie encoding (50% faster)

Major Release (Breaking Changes)

Example: 0.9.0 → 1.0.0

## [1.0.0] - 2025-XX-XX

### Added
- Stable API guarantee
- Comprehensive security audit

### Changed
- **BREAKING**: Renamed `consent_given?/2` to `has_consent?/2`
- **BREAKING**: Changed default cookie expiration from 365 to 180 days

### Migration Guide
...

Emergency Hotfix Process

If critical bug needs immediate fix:

1. Create hotfix branch:

   git checkout -b hotfix/X.Y.Z vX.Y.Z
   

2. Fix the bug:

   • Make minimal changes
   • Add regression test
   • Update CHANGELOG under ### Fixed

3. Bump PATCH version:

   • X.Y.Z → X.Y.Z+1

4. Test thoroughly:

   mix test
   mix credo --strict
   mix dialyzer
   

5. Merge and publish:

   git checkout main
   git merge hotfix/X.Y.Z+1
   # Then follow normal release process from Step 6
   

6. Retire vulnerable version (if security issue):

   mix hex.retire ash_cookie_consent X.Y.Z \
     --reason security \
     --message "Security fix in vX.Y.Z+1, please upgrade"
   

Reference Documents

• Full workflow: .claude/MAINTAINER_GUIDE.md
• Semantic versioning: https://semver.org
• Hex.pm publishing: https://hex.pm/docs/publish
• Keep a Changelog: https://keepachangelog.com

Success Criteria

Release is successful when:

• ✅ All quality checks pass (tests, credo, dialyzer, docs)
• ✅ Version bumped in mix.exs
• ✅ CHANGELOG updated with release date
• ✅ Git tag created and pushed
• ✅ Package published on Hex.pm
• ✅ GitHub release created
• ✅ Documentation built on hexdocs.pm
• ✅ No errors reported by users within first 24 hours

Notes

• Always be conservative with version bumps
• When in doubt about breaking changes, bump MINOR (pre-1.0)
• Document breaking changes thoroughly
• Test in real app before publishing if possible
• Can't unpublish from Hex after 1 hour or if downloaded