Write github Release for libs

[mumenthalers]

When publishing new versions of the libraries, write a proper github release so it's easier to see the latest changes and the history of versions. Also it enables agents to easier access this information

[mumenthalers]

Problem Statement

When a Release Run publishes updated libraries, there is no consolidated GitHub Release artifact that clearly communicates what changed. This makes it harder to quickly discover the latest Package Version Set, review version history, and let humans or agents consume release context efficiently.

Solution

Create one GitHub Release per Release Run. The release uses a dedicated Release Tag format (release-YYYYMMDD-HHMM-<pr-tag> for PR runs and release-YYYYMMDD-HHMM for main), marks PR runs as Pre-release and main runs as Stable Release, and includes a concise summary, Package Version Set, and Changelog Link entries.

User Stories

1. As a package consumer, I want one GitHub Release per Release Run, so that I can see a single source of truth for each publication event.
2. As a maintainer, I want Release Tags that clearly encode run time and PR context, so that I can quickly identify where a release came from.
3. As a maintainer, I want PR-based releases marked as Pre-release, so that consumers do not mistake them for stable publications.
4. As a maintainer, I want main-branch releases marked as Stable Release, so that downstream teams can trust the release channel.
5. As a maintainer, I want every GitHub Release to include a summary, so that I can understand the intent of the Release Run immediately.
6. As a maintainer, I want every GitHub Release to include the full Package Version Set, so that I can see exactly which packages changed and to what versions.
7. As a maintainer, I want Changelog Links for each changed package, so that I can jump directly to detailed change narratives.
8. As a reviewer, I want release notes generated consistently regardless of package count, so that communication quality does not degrade for large runs.
9. As a release engineer, I want release creation to happen in the existing publish flow, so that release communication cannot be forgotten.
10. As a release engineer, I want release creation to tolerate runs where only a subset of packages changed, so that the process remains useful and accurate.
11. As a release engineer, I want the Release Tag logic to behave predictably on PR and main, so that release naming is deterministic.
12. As an engineer debugging version history, I want each Release Run linked to one GitHub Release record, so that I can trace when versions were introduced.
13. As an operations teammate, I want a stable release body structure, so that automation can parse release metadata safely.
14. As a documentation consumer, I want historical releases to be chronologically readable, so that I can inspect evolution over time.
15. As an automation agent, I want machine-readable package/version bullets in release notes, so that I can extract latest release state without scraping unrelated content.
16. As a contributor, I want release generation to avoid changing package publication behavior, so that communication improvements do not alter distribution semantics.
17. As a maintainer, I want release notes to be concise but complete, so that the release history stays high-signal.
18. As a maintainer, I want release generation failure to be visible, so that missing release communication is not silent.

Implementation Decisions

• Keep the primary seam at the publish command domain (publish-lib) and extend it to produce release metadata and create the GitHub Release for each Release Run.
• Preserve the current publication responsibility split (versioning/publishing remains as-is) and add release communication as an adjacent concern in the same flow.
• Introduce deterministic Release Tag composition:
  • PR flow: release-YYYYMMDD-HHMM-<pr-tag>
  • Main flow: release-YYYYMMDD-HHMM
• Derive <pr-tag> from existing PR stage semantics already used for pre-release handling.
• Enforce channel semantics:
  • PR Release Run => prerelease=true
  • Main Release Run => prerelease=false
• Standardize release body sections in fixed order:
  1. Summary
  2. Package Version Set
  3. Changelog Links
• Build Package Version Set from versions computed/published in the same Release Run rather than from a separately inferred history source.
• Build Changelog Link entries per changed package and version, targeting repository-visible changelog anchors or files.
• Ensure release creation uses existing GitHub authentication context already present in CI (no new external system).
• Keep behavior explicit on failure: if release creation cannot complete, surface a hard failure instead of silently skipping.

Testing Decisions

• Good tests assert externally observable behavior: generated Release Tag shape, prerelease/stable flag selection, and rendered release body sections; they do not assert internal helper call ordering unless behavior depends on it.
• Primary tests should target the publish seam where release decisions are made, using mocked command/IO boundaries.
• Add focused tests for:
  • PR Release Tag with suffix
  • Main Release Tag without suffix
  • Pre-release vs Stable Release flag mapping
  • Package Version Set rendering format
  • Changelog Link rendering
  • Failure propagation when GitHub Release creation fails
• Reuse the repository’s existing script/package testing style for helper scripts (unit-style command behavior tests at package level) rather than adding a new test framework or integration harness.

Out of Scope

• Replacing current package versioning strategy (lerna behavior remains unchanged).
• Reworking changelog generation semantics beyond linking to existing changelog artifacts.
• Introducing per-package GitHub Releases.
• Backfilling historical releases for previously published versions.
• Changing branching conventions or the existing prerelease stage derivation model.

Further Notes

• Domain language captured in CONTEXT.md should be used consistently in implementation and review discussion (Release Run, Release Tag, Pre-release, Stable Release, Package Version Set, Changelog Link).
• The communication enhancement should remain low-friction and run automatically wherever publishing already occurs.