Release

---
name: release
description: Release automation skill for version bumping and tagging. Use when creating a new release, bumping version, tagging release, pushing release tag, or synchronizing version numbers across files. Handles package.json, README.md, SKILL.md, Dockerfile, and docker-compose files.
---

# Release Automation Skill

## Purpose

Automate the release process for the Madeinoz Knowledge System, including version synchronization across all files, git tagging, and triggering the CI workflow.

## When to Use

Use this skill when:
- Creating a new release (major, minor, or patch version)
- Bumping the version number
- Tagging a release commit
- Pushing a release to trigger CI workflow
- Synchronizing version numbers across multiple files

## Version Sync Locations

The following files MUST be updated with the new version:

### Primary Version Files

1. **package.json** (line 3)
   ```json
   "version": "X.Y.Z"
   ```

2. **docker/Dockerfile** (line 8)
   ```dockerfile
   LABEL version="X.Y.Z"
   ```

3. **README.md** (line 6)
   ```yaml
   pack-id: madeinoz67-madeinoz-knowledge-system-core-vX.Y.Z
   ```

4. **src/skills/SKILL.md** (line 3)
   ```yaml
   version: X.Y.Z
   ```

### Production Docker Compose (Manual Update)

5. **src/skills/server/docker-compose-production.yml** (line 85)
   ```yaml
   image: ghcr.io/madeinoz67/madeinoz-knowledge-system:X.Y.Z
   ```

**Note:** All other docker-compose files use `:latest` tag and do NOT need updates.

### Do NOT Edit

- **CHANGELOG.md** - Auto-generated by git-cliff workflow
- Modifying this file will conflict with automated changelog generation

## Pre-Release Checklist

Before creating a release, verify:

```bash
# 1. Check you're on main branch
git branch --show-current  # Should output: main

# 2. Pull latest changes
git pull origin main

# 3. Verify working tree is clean (no uncommitted changes)
git status  # Should show: "nothing to commit, working tree clean"

# 4. Verify latest CI passed
gh run list --limit 1  # Check status is "completed success"
```

## Release Workflow

### Step 1: Update Version Numbers

Manually edit the version files listed above. For example, bumping from `1.8.0` to `1.9.0`:

```bash
# Edit package.json
# Edit docker/Dockerfile
# Edit README.md
# Edit src/skills/SKILL.md
# Edit src/skills/server/docker-compose-production.yml
```

### Step 2: Commit Version Changes

```bash
git add package.json docker/Dockerfile README.md src/skills/SKILL.md src/skills/server/docker-compose-production.yml
git commit -m "chore: bump version to X.Y.Z"
```

### Step 3: Create Annotated Tag

```bash
# Single-line description
git tag -a vX.Y.Z -m "Release vX.Y.Z"

# OR multi-line description (opens editor)
git tag -a vX.Y.Z
```

In the editor, use this format:
```
Release X.Y.Z

Summary of what's in this release:
- Feature one
- Bug fix two
- Improvement three
```

### Step 4: Push Tag to Trigger CI

```bash
git push origin vX.Y.Z
```

This triggers the CI workflow which:
- Generates changelog from git-cliff
- Updates CHANGELOG.md on main branch
- Builds and pushes multi-arch Docker image to GHCR
- Creates GitHub Release with formatted release notes
- Deploys documentation to GitHub Pages

## Verification

After pushing the tag:

```bash
# Watch workflow run
gh run watch

# Confirm release created
gh release view vX.Y.Z

# Verify Docker image on GHCR
# https://github.com/madeinoz67/madeinoz-knowledge-system/pkgs/container/madeinoz-knowledge-system
```

## Common Pitfalls

### DO NOT Use `gh release create` Directly

❌ **Wrong:** `gh release create vX.Y.Z --notes "Release notes"`

This creates the tag via GitHub API without triggering the CI workflow. The release job will never run, leaving a broken release (no Docker image pushed, no docs deployed).

✅ **Correct:** `git push origin vX.Y.Z`

This triggers the `push` event for the tag, which runs the CI workflow.

### DO NOT Edit CHANGELOG.md

❌ **Wrong:** Manually editing CHANGELOG.md

This file is auto-generated by git-cliff during the CI workflow. Manual edits will be overwritten.

✅ **Correct:** Use conventional commit messages. The changelog is generated from commit history.

### Version Inconsistency

Ensure all version files use the exact same version string:
- package.json: `"version": "1.9.0"`
- Dockerfile: `LABEL version="1.9.0"`
- README.md: `pack-id: madeinoz67-madeinoz-knowledge-system-core-v1.9.0"`
- SKILL.md: `version: 1.9.0`

### Production Compose Version

The `docker-compose-production.yml` file pins specific versions. Remember to update this file when releasing, as it's used for production deployments.

## Release Types

| Type | Example | When |
|------|---------|------|
| **Major** | 1.8.0 → 2.0.0 | Breaking changes |
| **Minor** | 1.8.0 → 1.9.0 | New features, backward compatible |
| **Patch** | 1.8.0 → 1.8.1 | Bug fixes, small improvements |

## Quick Reference

```bash
# Full release workflow (replace X.Y.Z with actual version)
# 1. Edit version files
vim package.json docker/Dockerfile README.md src/skills/SKILL.md src/skills/server/docker-compose-production.yml

# 2. Commit changes
git add package.json docker/Dockerfile README.md src/skills/SKILL.md src/skills/server/docker-compose-production.yml
git commit -m "chore: bump version to X.Y.Z"

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

# 4. Push tag to trigger CI
git push origin vX.Y.Z

# 5. Verify
gh run watch
gh release view vX.Y.Z
```

## Related Documentation

- [CLAUDE.md](../../CLAUDE.md) - Release checklist (critical section)
- [.github/workflows/ci.yml](../../.github/workflows/ci.yml) - CI workflow definition
- [docs/reference/releases.md](../../docs/reference/releases.md) - Release documentation