Broadcasts & Versioning

When you publish an appgrammar to the registry, others may fork it, star it, or use it within their teams. The broadcast system lets you notify all subscribers, forkers, and team members when something changes.

Overview

A broadcast is a one-to-many notification sent from an appgrammar to everyone who has a relationship with it: subscribers, forkers, and team members. Broadcasts carry a type, severity level, and a message of up to 2,000 characters.

This is the mechanism for communicating breaking changes, security vulnerabilities, new features, and general updates to everyone who depends on your appgrammar.

Sending a Broadcast

Call appgrammar_broadcast with the appgrammar ID, message, type, and optional severity:

{
  "source_appgrammar_id": "your-appgrammar-uuid",
  "message": "v2.0: Migrated from REST to tRPC. Update your API client imports.",
  "type": "update",
  "severity": "breaking"
}

The response includes a broadcast_id and recipient_count (e.g., "Broadcast sent to 42 recipients").

Only the appgrammar author or accepted team members can send broadcasts. The tool verifies ownership before sending.

Broadcast Types

Type	Use Case
changelog	Document what changed in a new version. Use for routine updates that don't require action.
update	Notify about a significant update. May require forkers to pull changes.
vulnerability	Report a security issue. Indicates that downstream appgrammars may be affected.
info	General announcements: deprecation notices, migration guides, or community updates.

Severity Levels

Severity is independent of type and indicates urgency:

Severity	Meaning
info	No action required. For awareness only.
update	Action may be needed. Review at your convenience.
breaking	Breaking change. Downstream appgrammars will need modification.
vulnerability	Security issue. Immediate review recommended.

If severity is omitted, the system defaults based on the appgrammar's configuration.

Who Receives Broadcasts

A broadcast is delivered to:

• Subscribers -- users who have starred the appgrammar
• Forkers -- users who have forked the appgrammar (their fork retains a lineage link)
• Team members -- if the appgrammar belongs to a team, all accepted team members receive the broadcast

The recipient_count in the response tells you how many users were notified.

Upstream Shield

The appgrammar_upstream_shield tool complements broadcasts from the consumer side. It analyzes an appgrammar's dependencies and known upstream changes to flag risks before they affect your builds. While broadcasts push notifications from authors to consumers, the upstream shield lets consumers proactively check for problems.

Best Practices

• Use changelog for every release, even minor ones. This builds a history that forkers can review.
• Reserve vulnerability severity for actual security issues. Overuse reduces trust.
• Include actionable information: what changed, what to do, and where to find migration details.
• For breaking changes, send a type: "info" deprecation notice first, then type: "update" with severity: "breaking" when the change ships.
• Keep messages concise. The 2,000-character limit encourages focused communication.