Improve CI and release flow

Author: Maksym Shtembuliak

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -8,7 +8,7 @@ assignees: groove-max
 
 ## Version And Metadata
 
-- [ ] Confirm the release scope and changelog summary.
+- [ ] Update `CHANGELOG.md` and confirm the release scope is reflected in the target version section.
 - [ ] Verify the version in `custom_components/eybond_local/manifest.json`.
 - [ ] Verify `hacs.json`, `README.md`, and public docs still reflect current installation/support guidance.
 - [ ] Verify `LICENSE` and repository metadata still match the intended publication state.
@@ -21,6 +21,7 @@ assignees: groove-max
 
 ## Release Notes
 
+- [ ] Render release notes from `CHANGELOG.md` with `python3 tools/render_release_notes.py vX.Y.Z --output .local/release-notes/vX.Y.Z.md`.
 - [ ] Summarize user-visible changes.
 - [ ] Call out any breaking changes or required reconfiguration.
 - [ ] Mention newly supported hardware, controls, or diagnostics if applicable.
@@ -31,7 +32,7 @@ assignees: groove-max
 - [ ] Create or verify the Git tag.
 - [ ] Publish the GitHub release.
 - [ ] Make sure the release title and tag are aligned.
-- [ ] Paste the release notes into the GitHub release body.
+- [ ] Use the rendered release notes file as the GitHub release body.
 
 ## Post-Release
 

.github/workflows/validate.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Hassfest validation
         uses: home-assistant/actions/hassfest@master
 
@@ -34,9 +34,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - name: Run project quality gate

CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is inspired by Keep a Changelog, with one practical rule for this repository:
+the GitHub release body should be rendered from the matching version section here.
+
+## [Unreleased]
+
+### Added
+
+- Add new user-visible features here.
+
+### Changed
+
+- Add behavior changes, refactors, or support expansions here.
+
+### Fixed
+
+- Add bug fixes and regressions here.
+
+### Docs
+
+- Add documentation-only changes here.
+
+## [0.1.43] - 2026-04-15
+
+### Added
+
+- First public GitHub release of EyeBond Local.
+- Built-in local support for SMG / Modbus and PI30-family collectors, plus experimental PI18 replay coverage.
+- Support Archive export workflow for unsupported or partially supported inverters.
+- SMG writable and readback coverage for registers `341`, `342`, and `343`.
+
+### Changed
+
+- Config-flow runtime copy now loads from private `flow_translations/` bundles while Home Assistant-validated translation files remain Hassfest-compatible.
+- Public release validation now passes HACS Validation, Hassfest, and the repository quality gate in GitHub Actions.
+
+### Fixed
+
+- Publication blockers around config schema exposure, manifest ordering, and unsupported translation key placement.
+
+### Docs
+
+- Public README and release metadata were aligned for the first published release.

docs/README.md

@@ -22,6 +22,7 @@ Start with the [Contributing guide](../CONTRIBUTING.md) for the project philosop
 Then dive into one of:
 
 - [Adding A New Driver / Profile](ADDING_DRIVERS.md) — fixture-first workflow for extending hardware support
+- [Releasing](RELEASING.md) — changelog-first release flow and GitHub release notes generation
 - [Tools And CLI Scripts](../tools/README.md) — probing, fixtures, validation, doc generation
 
 ## I'm reviewing project status

docs/RELEASING.md

@@ -0,0 +1,54 @@
+# Releasing
+
+This project uses a changelog-first release flow.
+
+The source of truth for release notes is [CHANGELOG.md](../CHANGELOG.md), not the GitHub release form.
+
+## Release Workflow
+
+1. Keep incoming work under `## [Unreleased]` in [CHANGELOG.md](../CHANGELOG.md).
+2. When cutting a release, move the relevant notes into a new version section whose number matches [custom_components/eybond_local/manifest.json](../custom_components/eybond_local/manifest.json).
+3. Run the public validation gate:
+
+```bash
+python3 tools/quality_gate.py
+```
+
+4. If public generated docs changed, refresh and commit them before tagging:
+
+```bash
+python3 tools/quality_gate.py --refresh-generated
+```
+
+5. Render the GitHub release body from the matching changelog section:
+
+```bash
+python3 tools/render_release_notes.py v0.1.43 --output .local/release-notes/v0.1.43.md
+```
+
+6. Create and push the tag:
+
+```bash
+git tag v0.1.43
+git push origin v0.1.43
+```
+
+7. Publish the GitHub release from the rendered notes:
+
+```bash
+gh release create v0.1.43 \
+  --title "v0.1.43" \
+  --notes-file .local/release-notes/v0.1.43.md
+```
+
+## Writing Good Release Notes
+
+- Keep release notes user-facing.
+- Prefer grouped bullets under `Added`, `Changed`, `Fixed`, and `Docs`.
+- Mention breaking changes or required reconfiguration explicitly.
+- Call out newly supported hardware, controls, diagnostics, or important workflow changes.
+- Keep purely internal refactors out unless they affect users, maintainers, or release safety.
+
+## Maintainer Checklist
+
+The maintainer checklist lives in [.github/ISSUE_TEMPLATE/release_checklist.md](../.github/ISSUE_TEMPLATE/release_checklist.md).

tests/test_render_release_notes.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+import textwrap
+import unittest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPT_PATH = REPO_ROOT / "tools" / "render_release_notes.py"
+
+_SPEC = importlib.util.spec_from_file_location("render_release_notes", SCRIPT_PATH)
+if _SPEC is None or _SPEC.loader is None:
+    raise RuntimeError("Could not load render_release_notes tool")
+_MODULE = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(_MODULE)
+
+
+class RenderReleaseNotesTests(unittest.TestCase):
+    def test_normalize_version_accepts_tag_prefix(self) -> None:
+        self.assertEqual(_MODULE.normalize_version("v0.1.43"), "0.1.43")
+        self.assertEqual(_MODULE.normalize_version("0.1.43"), "0.1.43")
+
+    def test_extract_release_notes_returns_requested_section_body(self) -> None:
+        changelog = textwrap.dedent(
+            """\
+            # Changelog
+
+            ## [Unreleased]
+
+            ### Added
+
+            - Future work.
+
+            ## [0.1.43] - 2026-04-15
+
+            ### Added
+
+            - First public release.
+
+            ### Fixed
+
+            - Workflow validation.
+
+            ## [0.1.42] - 2026-04-14
+
+            ### Fixed
+
+            - Earlier fix.
+            """
+        )
+
+        rendered = _MODULE.extract_release_notes(changelog, "v0.1.43")
+
+        self.assertEqual(
+            rendered,
+            "### Added\n\n- First public release.\n\n### Fixed\n\n- Workflow validation.\n",
+        )
+
+    def test_extract_release_notes_raises_for_missing_version(self) -> None:
+        changelog = "# Changelog\n\n## [0.1.43] - 2026-04-15\n\n### Added\n\n- First public release.\n"
+
+        with self.assertRaisesRegex(ValueError, "Version 0.1.44"):
+            _MODULE.extract_release_notes(changelog, "0.1.44")
+
+
+if __name__ == "__main__":
+    unittest.main()

tools/README.md

@@ -126,6 +126,22 @@ Refresh generated docs first, then run the quality gate:
 python3 tools/quality_gate.py --refresh-generated
 ```
 
+## I want to cut a release
+
+Render the GitHub release body for a version directly from `CHANGELOG.md`:
+
+```bash
+python3 tools/render_release_notes.py v0.1.43
+```
+
+Write the release body to a file for `gh release create --notes-file`:
+
+```bash
+python3 tools/render_release_notes.py v0.1.43 --output .local/release-notes/v0.1.43.md
+```
+
+The full maintainer flow is documented in [docs/RELEASING.md](../docs/RELEASING.md).
+
 ---
 
 ## I want to refresh generated documentation

tools/render_release_notes.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Render GitHub release notes for one version from CHANGELOG.md."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import re
+import sys
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+CHANGELOG_PATH = REPO_ROOT / "CHANGELOG.md"
+VERSION_HEADER_RE = re.compile(r"^## \[(?P<version>[^\]]+)\](?: - .+)?$", re.MULTILINE)
+
+
+def normalize_version(version: str) -> str:
+    normalized = version.strip()
+    if normalized.startswith("v"):
+        normalized = normalized[1:]
+    return normalized
+
+
+def extract_release_notes(changelog_text: str, version: str) -> str:
+    target = normalize_version(version)
+    matches = list(VERSION_HEADER_RE.finditer(changelog_text))
+
+    for index, match in enumerate(matches):
+        if normalize_version(match.group("version")) != target:
+            continue
+
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(changelog_text)
+        body = changelog_text[start:end].strip()
+        if not body:
+            raise ValueError(f"Changelog section for version {target} is empty")
+        return body + "\n"
+
+    raise ValueError(f"Version {target} was not found in {CHANGELOG_PATH.name}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("version", help="version or tag, for example 0.1.43 or v0.1.43")
+    parser.add_argument(
+        "--changelog",
+        default=str(CHANGELOG_PATH),
+        help="path to the changelog file",
+    )
+    parser.add_argument(
+        "--output",
+        help="optional output file path; prints to stdout when omitted",
+    )
+    args = parser.parse_args()
+
+    changelog_path = Path(args.changelog).expanduser()
+    try:
+        changelog_text = changelog_path.read_text(encoding="utf-8")
+        rendered = extract_release_notes(changelog_text, args.version)
+    except (OSError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    if args.output:
+        output_path = Path(args.output).expanduser()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+        print(output_path)
+        return 0
+
+    print(rendered, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())