release-radar

Context and purpose

release-radar collects release notes from the tools it follows into one notification stream instead of requiring manual checks across many sites. It does more than discover a release: it summarises lengthy or fragmented notes in Turkish and delivers a Telegram notification that keeps a route back to the source.

The project is a long-running service that manages its own loop rather than a one-off scheduled job. Scan frequency, notification history, and retry behaviour stay inside the application.

How it works

On startup, the service reads its source configuration and runs an initial scan. When it sees a source for the first time, it stores current entries as a baseline without sending notifications. Later scans process only entries that have not been seen before.

For a new release, the service retrieves the RSS or Atom entry for the relevant source type; VS Code has a dedicated route that retrieves detailed Markdown notes. Gemini produces a Turkish summary, the message is split if it exceeds Telegram limits, and the entry is persisted only after successful delivery.

System design

The Python application brings together source loading, network retrieval, summarisation, and notification in its main scan loop. SQLite stores processed releases through a unique source-and-entry identifier.

The configuration file describes monitored sources and their types. Docker Compose mounts that configuration read-only while keeping the database in a persistent runtime directory. The source list can therefore change without turning notification history into repository content.

Key technical decisions

Creating a silent baseline on first scan prevents a flood of old releases. The composite source and guid key in SQLite prevents the same entry from being sent again after a container restart.

External network requests, Gemini calls, and Telegram delivery can fail temporarily. Requests use retry and backoff behaviour, and a release is not marked as seen until Telegram confirms delivery. Splitting long messages prevents one oversized release note from disappearing because of platform limits.

The service handles shutdown signals and uses interruptible sleep in its waiting loop, making Compose restarts more predictable between scans.

Validation and limits

Pytest coverage includes the SQLite schema, first-run baselining, duplicate prevention, and the rule that failed Telegram delivery must not mark an entry as processed. Ruff and Docker build checks are also part of continuous integration.

Summary accuracy depends on the source text and language-model output. Telegram delivery and the SQLite update are not one atomic operation, so an interruption between them can lead to a duplicate notification during a later scan. Removing persistent runtime data also rebuilds the baseline for each source.