# Perform Release

> Perform a release for this repository. Use when the user asks to create, prepare, cut, tag, publish, bump or run a patch/minor/major release for the HACS Home Assistant Aiper integration by bumping repo versions and letting the CI/CD workflow tag and publish after validation passes. Use when this capability is needed.

- Skill: `tomevault-io/perform-release` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/perform-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/perform-release/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/perform-release

---


# Perform Release

Release this HACS integration by committing a version bump to `main`, waiting
for the `CI` and `Validate` workflows, and then pushing a matching version tag.
The tag-triggered `Release` workflow re-runs preflight checks and creates the
GitHub release archive.

## Release Type

- Default to `patch`.
- Use `minor` or `major` when the user asks for that release type.
- Use an explicit SemVer version when the user gives a target such as `0.9.0`
  or `v0.9.0`.

## Preconditions

1. Work from the repository root.
2. Check local state:
   ```bash
   git status --short --branch
   git fetch origin --prune --tags
   ```
3. Require local `main` to track `origin/main`.
4. If local `main` is behind `origin/main`, pull or ask before continuing.
5. If local `main` is ahead of `origin/main`, confirm those commits are intended
   to be released before pushing.
6. If there are unrelated uncommitted changes, stop and ask unless the user
   explicitly wants them included in the release commit.
7. Read current versions:
   ```bash
   rg -n '"version"|^version =|name = "ha-aiper"' custom_components/aiper/manifest.json pyproject.toml uv.lock
   ```
8. Require the existing versions in `custom_components/aiper/manifest.json`,
   `pyproject.toml`, and the `ha-aiper` stanza in `uv.lock` to match before
   bumping. If they differ, stop and fix that mismatch first.

## Bump Version

1. Determine the target version from the current version:
   - patch: increment `PATCH`
   - minor: increment `MINOR` and reset `PATCH` to `0`
   - major: increment `MAJOR` and reset `MINOR` and `PATCH` to `0`
2. Update all stored package versions:
   - `custom_components/aiper/manifest.json`: top-level `"version"`
   - `pyproject.toml`: `[project]` `version`
   - `uv.lock`: only the `version` in the `[[package]]` stanza where
     `name = "ha-aiper"`
3. Prefer `uv lock` after editing `pyproject.toml` so `uv.lock` stays
   mechanically consistent.
4. Confirm the new version is greater than the latest SemVer tag:
   ```bash
   git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=v:refname | tail -1
   ```

## Validate Locally

Run the local checks before committing:

```bash
uv sync --locked --group dev
uv run --frozen ruff check custom_components/
uv run --frozen mypy custom_components/
uv run --frozen pytest
```

If a check fails, fix it or report the blocker. Do not commit a release version
that has not passed local validation unless the user explicitly instructs that.

## Commit And Push

Commit only the intended release files and push `main`:

```bash
git diff -- custom_components/aiper/manifest.json pyproject.toml uv.lock
git add custom_components/aiper/manifest.json pyproject.toml uv.lock
git commit -m "Release X.Y.Z"
git push origin main
```

The push triggers `.github/workflows/ci.yml` and
`.github/workflows/validate.yml`. Wait for both before tagging the release:

```bash
gh run list -R kmich/ha-aiper --branch main --limit 10 --json databaseId,name,displayTitle,headSha,status,conclusion,createdAt,url
gh run watch -R kmich/ha-aiper RUN_ID --exit-status
```

After those checks pass, tag the release commit and push the tag:

```bash
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
```

The tag triggers `.github/workflows/release.yml`. Its preflight checks must
pass before it publishes the GitHub release. The release uses generated notes
so merged pull requests and contributor credit are visible on the release page.

The release asset must contain the contents of `custom_components/aiper` at the
zip root. Do not package the parent `custom_components/aiper` path inside
`aiper.zip`, or HACS will install it as
`/config/custom_components/aiper/custom_components/aiper`.

## Follow Release

Find the tag-triggered release run and watch it:

```bash
gh run list -R kmich/ha-aiper --workflow "Release" --limit 10 --json databaseId,displayTitle,headSha,status,conclusion,createdAt,url
gh run watch -R kmich/ha-aiper RUN_ID --exit-status
```

If it fails, inspect logs:

```bash
gh run view -R kmich/ha-aiper RUN_ID --log-failed
```

## Verify Release

After success:

1. Fetch refs:
   ```bash
   git fetch origin --prune --tags
   git status --short --branch
   git log --oneline --decorate -5
   ```
2. Verify the tag points at the release commit.
3. Verify GitHub release notes and `aiper.zip`:
   ```bash
   gh release view -R kmich/ha-aiper vX.Y.Z --json tagName,name,url,body,assets
   ```

## Final Response

Report:

- released version and tag
- release commit SHA
- CI/CD workflow result and URL
- GitHub release URL
- asset name/size
- warnings or follow-up issues

---
> Source: [kmich/ha-aiper](https://github.com/kmich/ha-aiper) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->