ash-library-release

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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
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:

```bash
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**:
```bash
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

```markdown
## [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

```markdown
## [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

```markdown
## [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