Skip to content

release_workflow.md

Latest commit

 

History

History
128 lines (96 loc) · 4.06 KB

release_workflow.md

File metadata and controls

128 lines (96 loc) · 4.06 KB

PocketSmith Release Workflow

Overview

This document outlines the steps to follow after making code changes to the PocketSmith integration.

When you push a version tag (e.g. v0.4.4), two GitHub Actions workflows fire automatically:

  1. Automatic Release (release.yml) — Creates a GitHub release and generates release notes from the commit messages between the new tag and the previous tag.
  2. Update Manifest Version (update-version.yml) — Strips the v prefix from the tag, updates the version field in manifest.json using jq, and commits the change back to main — but only if the version actually changed.

Release notes are built from your commit messages. GitHub compares commits between the new tag and the previous tag. Clear, conventional commit messages make better release notes, so write them with that in mind.

Working Directory

Always make changes in:

/config/home-assistant-pocketsmith/custom_components/ha_pocketsmith

Step 1 — Make Your Changes

Make your code changes using Claude Code or your editor of choice.

Step 2 — Commit with Conventional Commit Messages

Use the following format for all commit messages:

type: short description

Commit Types

Type Use For Example
feat: New features feat: add support for multiple accounts
fix: Bug fixes fix: handle 403 response correctly
chore: Maintenance chore: update dependencies
docs: Documentation docs: update README
refactor: Code improvements refactor: simplify sensor update logic

Commit Command

git add .
git commit -m "fix: your description here"
git push origin main

Step 3 — Test in Home Assistant

Restart Home Assistant and verify:

  • No errors in the logs
  • Sensors are showing correct data
  • Go to Developer Tools → States and search for pocketsmith

Step 4 — Create a Release Tag

Once you are happy with the changes, create a new version tag. The tag must start with v to trigger the workflows.

git tag v0.X.X
git push origin v0.X.X

Versioning Guide

Change Type Example
Bug fix or small improvement v0.2.8 → v0.2.9
New feature v0.2.8 → v0.3.0
Breaking change v0.2.8 → v1.0.0

Step 5 — Automated Workflows (Happens Automatically)

Once the tag is pushed, two workflows run in parallel.

Automatic Release (release.yml)

  • Triggers on any tag matching v*
  • Uses softprops/action-gh-release to create a GitHub release
  • Release notes are automatically generated by GitHub from the commit messages between the new tag and the previous tag — no manual changelog needed
  • Marks the release as the latest

Update Manifest Version (update-version.yml)

  • Triggers on any tag matching v*
  • Checks out the main branch
  • Strips the v prefix from the tag (e.g. v0.4.4 → 0.4.4) using shell parameter expansion
  • Updates the "version" field in custom_components/ha_pocketsmith/manifest.json using jq
  • Commits and pushes the updated manifest.json back to main as github-actions[bot] — only if the version field actually changed (the workflow skips the commit if the file is unchanged)

Monitor both workflows in the Actions tab on GitHub:

https://github.com/cloudbr34k84/home-assistant-pocketsmith/actions

Step 6 — Pull the Updated Manifest

After both workflows complete, pull the manifest.json version bump back to your local repo:

git pull origin main

Quick Reference

# 1. Commit your changes
git add .
git commit -m "feat: your description here"
git push origin main

# 2. Test in Home Assistant (restart and check sensors)

# 3. Create and push a release tag (must start with 'v')
git tag v0.X.X
git push origin v0.X.X

# 4. Wait for GitHub Actions to complete:
#    - Release created with auto-generated notes from commit messages
#    - manifest.json version bumped and committed back to main

# 5. Pull the updated manifest
git pull origin main