krkn-chaos / krkn-chaos/docsync-bot

[Feature] Release Notes & Blog Announcement Automation

Open
#22 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Python
Stars
1
Forks
1
Avg merge
1d 6h
Merged PRs (30d)
9

Description

**Use Case**:
[Krkn Blog](https://krkn-chaos.dev/blog/) is where the project announces news, but release announcements are entirely manual today: GitHub auto-generates a categorized PR changelog on each release (see `.github/release.yml` in krknctl/krkn/krkn-hub — 🚀 Features, 🐛 Bug Fixes, 🧰 Maintenance), but nothing turns that into a blog post, and nothing calls out breaking/API-spec changes distinctly. This issue tracks building that automation as a `docsync-bot` capability, in the same spirit as the parameter-drift sync already in place.

## Motivation

Every krkn-chaos release (`krkn`, `krkn-hub`, `krknctl`, `krkn-operator`) ends with a GitHub release page containing download links and an auto-generated, label-categorized PR list — useful to a developer, not to someone browsing [krkn-chaos.dev/blog](https://krkn-chaos.dev/blog/). Turning that into an announcement, and flagging the release's major callouts (e.g. an API-spec/breaking change), currently depends on someone remembering to write it by hand.

## Expected outcome

- A workflow triggers on `release: published` for one or more source repos, reusing the existing `*-template` trigger pattern in this repo (`krkn-hub-template`, `krkn-template`, `krkn-operator-template`).
- The bot reads the release body/tag plus the merged PRs since the previous tag, and deterministically classifies them (breaking/API-spec change vs. feature vs. fix) rather than leaving that judgment to the model.
- An LLM converts the classified, factual changes into announcement prose, following the bot's existing description-priority pattern: facts pulled from source first, the model fills only the narrative gaps, with a plain mechanical fallback if the model call is unavailable (same behavior as when `LLM_API_KEY` is unset today).
- The bot opens a **draft PR** on `krkn-chaos/website` with the announcement — never auto-merged, consistent with every other docsync-bot workflow.
- Decide and implement how the entry lands on the blog page. Today `layouts/blog/list.html` is hand-written HTML (category/type badges, filter pills) with no backing data file — so this needs either a small data-driven refactor (e.g. `data/blog/posts.yaml` that the layout loops over) or an agreed convention for how the bot appends a card, so this doesn't turn into repeated manual HTML edits.

## Suggested phasing

1. One source repo end to end — `krknctl` is a reasonable pilot given its release cadence — producing a draft PR with a basic announcement.
2. Major-callout detection (breaking/API-spec changes) surfaced as a highlighted section instead of a flat list.
3. Extend triggers to `krkn`, `krkn-hub`, `krkn-operator`; decide whether multi-repo releases in the same window batch into one post or stay separate.

Reuse what already exists rather than rebuilding it: `github_client.py` for PR/issue creation, the draft-PR and DCO/build-check gates already enforced on the website repo, and the same scoped/short-lived token model — no new auto-publish path.

## Out of scope

- Auto-publishing without human review.
- Cross-posting to Red Hat Blog, dev.to, or social channels — website blog only.
- Backfilling past releases; this covers releases going forward.

## Acceptance criteria

A tagged release on the pilot repo produces a draft PR on `krkn-chaos/website` with an accurate, readable announcement, correct links back to the release, and a distinct callout for any breaking/API-spec change — within minutes of the release being published.

**Skills required:** Python, GitHub Actions/webhooks, basic Hugo/Markdown, git/PR workflows.
**Good to have:** LLM API/prompt-engineering experience, familiarity with the `docsync-bot` codebase (`descriptions.py`, `github_client.py`).

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the existing krkn-hub-template, krkn-template, and krkn-operator-template triggers, then inspect descriptions.py and github_client.py for description generation and draft-PR patterns. Review .github/release.yml and layouts/blog/list.html before choosing how release data enters the website. Done means a pilot release creates an accurate draft website PR with release links and a distinct breaking/API-spec callout, while preserving the existing review gates.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, hugo, python
Domain
ci-cd, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.