V1dev release notes

AGENTS.md

@@ -0,0 +1,49 @@
+# OGM-Common Agent Instructions
+
+## Scope
+These instructions apply to OGM-Common and all OpenKNX modules that consume OGM-Common in this workspace.
+
+## Release Notes Policy
+Each module directory under `lib/` must provide `release_notes.md` in a machine-readable format.
+
+Required structure:
+
+```markdown
+# Release Notes
+
+## <version>
+### Breaking Changes
+- ...
+
+### Feature
+- ...
+
+### Bug
+- ...
+```
+
+Rules:
+- Use exactly the three category headings shown above.
+- Every version section must include all categories.
+- Category order per version is mandatory: `Breaking Changes`, then `Feature`, then `Bug`.
+- If no items exist in a category, write `- none`.
+- Version heading must match `version` from the module `library.json`.
+- Keep change items concise and suitable for automatic aggregation.
+
+## Dependency File Policy
+`dependencies.txt` lines may include an additional final field for module version.
+
+Expected fields:
+- commit hash
+- branch
+- module path
+- git remote URL
+- module version from `library.json`
+
+Restore scripts must remain backward compatible with 4-field and 5-field lines.
+
+## Aggregated Release Notes
+Main project release notes are generated by comparing old and new `dependencies.txt` snapshots. The output groups module changes by:
+- Feature
+- Bug
+- Breaking Changes

CLAUDE.md

@@ -133,3 +133,31 @@ Rules:
 - Keep READMEs in sync with the code — never leave them stale after a change
 - Do not create new README files unless the user explicitly asks
 - Do not add a "Changed in this session" or similar meta-section — just update the relevant content inline
+
+## Release Notes Instructions
+
+Each library project under `lib/` must contain a `release_notes.md` file in a machine-readable markdown format.
+
+Required format per version:
+
+```markdown
+# Release Notes
+
+## <version>
+### Breaking Changes
+- ...
+### Feature
+- ...
+### Bug
+- ...
+```
+
+Rules:
+- `## <version>` must match the semantic version from the module `library.json`.
+- All three categories are mandatory for each version section.
+- Category order per version is mandatory: `Breaking Changes`, then `Feature`, then `Bug`.
+- If a category has no entries, use `- none`.
+- Breaking changes must be listed only under `### Breaking Changes`.
+- Keep entries short and actionable for automated aggregation.
+
+For full authoring and migration guidance, see `doc/Release-Notes-Guide.md`.

doc/Release-Notes-Conversion.prompt.md

@@ -0,0 +1,62 @@
+# Prompt: Convert Legacy Release Notes To release_notes.md
+
+Use this prompt with an AI coding assistant to migrate historical release information into the machine-readable `release_notes.md` format.
+
+## Copy/Paste Prompt
+
+```text
+You are working in a repository with multiple module projects under lib/.
+
+Goal:
+Convert all legacy release information to the new machine-readable release notes format.
+
+Target format for each module file `release_notes.md`:
+
+# Release Notes
+
+## <version>
+### Breaking Changes
+- ...
+
+### Feature
+- ...
+
+### Bug
+- ...
+
+Requirements:
+1. Search all possible legacy sources for release history, including:
+   - CHANGELOG.md
+   - README.md sections like "Release Notes", "Changelog", "Änderungshistorie"
+   - application documentation files, e.g. doc/Applikationsbeschreibung*.md
+2. Merge all found history entries into each module's `release_notes.md`.
+3. Keep existing entries and only add missing information.
+4. Deduplicate identical entries.
+5. Map entries into categories:
+   - Feature: new functionality, improvements, refactorings, docs (if no bug context)
+   - Bug: fixes, hotfixes, error corrections
+   - Breaking Changes: incompatible behavior or migration-impacting changes
+6. If a category has no entries for a version, set `- none`.
+6a. Enforce heading order per version exactly as: Breaking Changes, Feature, Bug.
+7. Preserve version ordering from newest to oldest where possible.
+8. Keep wording close to original source text; do not invent new release facts.
+9. After migration, update README sections that still carry old release lists to a short pointer:
+   - "Die vollständige Historie liegt in [release_notes.md](release_notes.md)."
+10. Validate:
+   - every module under lib has `release_notes.md`
+   - each version has all three headings: Feature, Bug, Breaking Changes
+   - scripts/parsers consuming release_notes still work
+
+Output:
+- Apply all file edits directly.
+- Provide a final summary with:
+  - which modules were changed
+  - which legacy sources were consumed per module
+  - any ambiguities or entries that could not be classified safely
+```
+
+## Notes
+
+- Recommended usage scope: one repository at a time.
+- If module history is very long, migrate in phases (recent releases first, then older history).
+- Keep this prompt in sync with `Release-Notes-Guide.md`.

doc/Release-Notes-Guide.md

@@ -0,0 +1,83 @@
+# Release Notes Guide
+
+## Goal
+Provide machine-readable release notes for every module under `lib/`.
+
+## File Name
+Each module must contain:
+- `release_notes.md`
+
+## Required Format
+Use this exact section structure for each version.
+
+```markdown
+# Release Notes
+
+## 1.2.3
+### Breaking Changes
+- Renamed API ... to ...
+
+### Feature
+- Added support for ...
+
+### Bug
+- Fixed crash when ...
+```
+
+## Rules
+- Version heading `## <version>` must match module `library.json`.
+- Categories must be exactly:
+  - `### Breaking Changes`
+  - `### Feature`
+  - `### Bug`
+- Category order inside each version must be exactly:
+  1. `### Breaking Changes`
+  2. `### Feature`
+  3. `### Bug`
+- Keep bullet points short, one change per line.
+- If no entries are available in a category, use `- none`.
+- Put incompatible changes only in `Breaking Changes`.
+
+## Migration from Existing CHANGELOG.md
+1. Keep existing changelog files unchanged.
+2. Create or update `release_notes.md`.
+3. For each version, map entries into required categories.
+4. When category cannot be determined, default to `Bug` and refine later.
+
+## Reusable AI Prompt
+
+For migration in additional projects, use:
+
+- `doc/Release-Notes-Conversion.prompt.md`
+
+This prompt covers extraction from `CHANGELOG.md`, `README.md`, and application docs, then merges entries into the required machine-readable format.
+
+## Examples
+
+Example with no breaking changes:
+
+```markdown
+## 0.6.0
+### Breaking Changes
+- none
+
+### Feature
+- Added KNX reconnect diagnostics.
+
+### Bug
+- Fixed timezone offset handling for sunrise calculation.
+```
+
+Example with breaking changes:
+
+```markdown
+## 1.4.0
+### Breaking Changes
+- Changed KO numbering for core objects 2-19.
+
+### Feature
+- Added new GPIO abstraction for expanders.
+
+### Bug
+- Fixed memory layout overlap detection output.
+```