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:

   bash

   git status
   

   All changes should be committed.

2. •

   On main branch and up to date:

   bash

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

3. •

   User has Hex credentials:

   bash

   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:

   markdown

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

   bash

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

   • •Verify version shows correctly
   • •Check documentation built
2. •

   GitHub release:

   bash

   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:

   bash

   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:

   bash

   mix test
   mix credo --strict
   mix dialyzer
   

5. •

   Merge and publish:

   bash

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

   bash

   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