Skip to main content

Versioning & Changelog

Appgrammars accumulate a version history as they evolve. The changelog system lets authors document changes for forkers and subscribers.

Version History​

Each modification to an appgrammar's plan creates a version entry. View the version history (owner only):

GET /api/appgrammars/:id/versions?limit=10&offset=0

Returns versions in reverse chronological order with timestamps and metadata about what changed.

Publishing Changelog Entries​

Changelog entries are human-written summaries attached to your appgrammar. They appear on the appgrammar's detail page and can trigger broadcasts to subscribers.

Creating an Entry​

POST /api/appgrammars/:id/changelog
{
  "title": "v2.0 — Migrated to tRPC",
  "body": "Replaced REST endpoints with tRPC for end-to-end type safety. Breaking change: update all API client imports."
}

Only the appgrammar owner can publish changelog entries.

Updating an Entry​

PATCH /api/appgrammars/:id/changelog/:entryId
{
  "title": "Updated title",
  "body": "Updated body content"
}

Viewing the Changelog​

GET /api/appgrammars/:id/changelog?limit=10&offset=0

This endpoint is public -- anyone can view an appgrammar's changelog. Entries are returned in reverse chronological order.

In the web UI, the Changelog tab on the appgrammar detail page shows all entries.

Changelog and Broadcasts​

Changelog entries pair naturally with broadcasts. After publishing a changelog entry, send a broadcast to notify all subscribers and forkers:

{
  "source_appgrammar_id": "your-appgrammar-uuid",
  "message": "v2.0: Migrated from REST to tRPC. See changelog for migration details.",
  "type": "changelog",
  "severity": "breaking"
}

This ensures that everyone who depends on your appgrammar is aware of the change.