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:

Clean working directory:
```
git status
```
All changes should be committed.

On main branch and up to date:

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

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

Read current CHANGELOG.md

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]

Add today's date (YYYY-MM-DD format)
Update comparison links at bottom of file
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

Read mix.exs
Update @version "X.Y.Z" at top of file
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:

Check file list in output
Verify size is reasonable (should be ~30-40KB)
Confirm no test files included
Confirm no .claude directory included
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:

Show package details
Show files to be included
Show dependencies
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:

Hex.pm package:
```
open https://hex.pm/packages/ash_cookie_consent
```
- Verify version shows correctly
- Check documentation built
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:

Run mix docs locally
Fix any errors in module documentation
Commit fixes
Restart release process from Step 6

Tests fail during quality checks

Solution:

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

Package size is too large

Solution:

Check files: list in mix.exs package config
Ensure test files, docs, and .claude excluded
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:

Create hotfix branch:
```
git checkout -b hotfix/X.Y.Z vX.Y.Z
```
Fix the bug:
- Make minimal changes
- Add regression test
- Update CHANGELOG under ### Fixed
Bump PATCH version:
- X.Y.Z → X.Y.Z+1

Test thoroughly:

mix test
mix credo --strict
mix dialyzer

Merge and publish:

git checkout main
git merge hotfix/X.Y.Z+1
# Then follow normal release process from Step 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

ash-library-release

AshCookieConsent Library Release Management

When to Use This Skill

Prerequisites Check

Release Workflow

Step 1: Determine Version Number

Step 2: Update CHANGELOG.md

Step 3: Bump Version in mix.exs

Step 4: Run Quality Checks

Step 5: Build and Review Package

Step 6: Commit Version Bump

Step 7: Create and Push Git Tag

Step 8: Publish to Hex.pm

Step 9: Create GitHub Release

Step 10: Post-Release Verification

Step 11: Post-Release Checklist

Troubleshooting

"mix hex.publish" fails with authentication error

Documentation fails to build

Tests fail during quality checks

Package size is too large

Quick Reference: Common Release Types

Patch Release (Bug Fix)

Minor Release (New Features)

Major Release (Breaking Changes)

Emergency Hotfix Process

Reference Documents

Success Criteria

Notes