Skip to content

RELEASING.md

Latest commit

 

History

History
97 lines (75 loc) · 3.04 KB

RELEASING.md

File metadata and controls

97 lines (75 loc) · 3.04 KB

Releasing

This project uses date-based versions with daily sequence:

  • First release of a day: YYYY.M.D

  • Additional releases that same day: YYYY.M.D-N

  • YYYY.M.D: release date (no zero-padding; SemVer compatible)

  • N: release sequence number for that calendar day on master (2, 3, 4, ...)

Examples:

  • First release on March 4, 2026: 2026.3.4
  • Third release on March 4, 2026: 2026.3.4-3

Current Release State

Latest public release: v2026.3.6 (2026-03-06).

  • CHANGELOG.md contains release notes and current unreleased changes.
  • docs/PROJECT_HISTORY.md preserves pre-release implementation history and audit notes.

Local Release Workflow

  1. Prepare version fields: 
    bun run release:prepare
  2. Verify quality and security gates: 
    bun run release:verify
  3. Validate package launchers from packed tarball: 
    bun run release:dry-run
  4. Generate release notes draft: 
    bun run release:notes

Equivalent npm commands are available (npm run release:prepare, npm run release:verify, npm run release:dry-run, npm run release:notes), but Bun remains the primary package manager for this repository.

CI/CD Workflows

  • CI (.github/workflows/ci.yml)
    • lint, typecheck, build, unit tests
    • coverage artifact upload
    • packaged launcher smoke test (npx + bunx)
  • Security (.github/workflows/security.yml)
    • full history secret signature scan
    • CodeQL analysis for JS/TS
  • Release Dry Run (.github/workflows/release-dry-run.yml)
    • full release-quality gates + release notes preview artifact
  • Publish to npm (.github/workflows/publish.yml)
    • manual trigger only
    • supports dry-run and real publish
    • enforces master branch, valid YYYY.M.D[-N] version, and non-existing release tag
    • publishes with npm provenance
    • creates GitHub release notes for non-dry-run
  • Commit Quality (.github/workflows/commit-quality.yml)
    • enforces Conventional Commit-style PR titles

Required Repository Setup

  • NPM_TOKEN repository secret (required for real publish)
  • release GitHub Environment with approvers (recommended)
  • Branch protection on master (required checks: CI + Security)

npx + bunx Compatibility

Compatibility is enforced in automation:

  • scripts/release/dry-run.sh packs the package and tests:
    • npx --no-install hassio --help
    • bunx hassio --help

Standard Release Steps

  1. Run bun run release:verify locally.
  2. Trigger Release Dry Run workflow.
  3. Run bun run release:prepare and commit: 
    chore(release): vYYYY.M.D[-N]
  4. Push master.
  5. Trigger Publish to npm with dry_run=true.
  6. Trigger Publish to npm with dry_run=false.

Secret Hygiene

Before pushing release commits:

git diff --cached -U0 | rg -n '^\+.*(ghp_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{40,}|npm_[A-Za-z0-9]{36}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9._-]{10,}\.[A-Za-z0-9._-]{10,}|-----BEGIN (RSA|OPENSSH|EC|DSA|PGP) PRIVATE KEY-----|_authToken\s*=)'
bun run security:scan:history
bun run commit:audit