peerspeak/VERSIONING.md

PeerSpeak Versioning Standard

PeerSpeak is a full-mesh P2P voice app. Its "API contract" is not a library surface — it is the wire protocol two nodes use to talk. So versioning here tracks one question above all others:

Can a node on build X talk to a node on build Y?

There are two distinct version layers. Keep them straight.

---

Layer 1 — Release version (Cargo.toml)

The human-facing label you put on a build ("install this one").

Scheme: SemVer, pre-1.0 (0.MINOR.PATCH).

While we are pre-1.0 (friends-only, no stability promise yet):

Change	Bump	Example
Breaking wire/protocol change — peers on the old build can no longer interoperate; everyone must update	MINOR	0.4.2 → 0.5.0
Compatible change — bug fix, internal refactor, or a feature that does not change the wire (UI, local-only behavior, additive logic that old peers ignore safely)	PATCH	0.4.2 → 0.4.3

• Reaching 1.0.0: when PeerSpeak is first shared beyond the trusted-friends circle (a "public" release), and we are willing to commit to wire stability. After 1.0, MAJOR = wire break, MINOR = compatible feature, PATCH = fix (normal SemVer).
• Bump version in Cargo.toml as part of the change that warrants it, in the same commit. The number in Cargo.toml is the source of truth; surface it in the UI (e.g. an About/Settings line) so a user can read their build.

Rule of thumb: if you find yourself writing "all peers must rebuild" or "breaking gossip wire change" in a commit message (as S2 and W4 did), that is a MINOR bump, and it must also bump the relevant protocol version in Layer 2.

---

Layer 2 — Protocol compatibility (the one that actually breaks calls)

Wire incompatibility must fail fast and legibly — never as a silent signature/decode error that looks like a bug or an attack. We achieve this by embedding a protocol version into each transport plane, so incompatible peers are rejected at connect/subscribe time instead of mid-conversation.

PeerSpeak has three independent planes, each versioned separately — bump only the plane whose wire format actually changed (audio rarely changes; gossip changes often; they must not be forced to bump together).

ALPN naming convention

All peerspeak ALPNs use the form peerspeak/<plane>/<N> where <N> is that plane's protocol version (an integer, starts at 1). iroh refuses a connection whose ALPN does not match exactly, so two peers on different <N> for a plane simply cannot open that connection → we map that to a clean "peer is running an incompatible version" instead of garbage.

Plane	ALPN / mechanism	Bump when…
Audio	ALPN peerspeak/audio/<N>	the Opus/datagram framing, sequencing, or audio-handshake changes
Friends/presence	ALPN peerspeak/friends/<N>	the ControlMsg / presence ping-pong shape changes
Gossip	(see below — cannot use a custom ALPN)	GossipPayload / GossipMessage / PeerState shape, signing, or freshness rules change

Gossip is special

The gossip plane runs over iroh-gossip's own GOSSIP_ALPN, which we do not control, so we cannot version it via the ALPN. Instead, the gossip protocol version is bound in two places:

1. Topic namespacing (primary, fail-fast): the room's topic_id is a random 32 bytes carried in the ticket, but the topic we actually subscribe to is protocol::versioned_topic(topic_id) — a deterministic, dependency-free transform that folds GOSSIP_PROTO into the bytes. Peers on different gossip versions therefore derive different subscription topics from the same ticket and never share a swarm — the same isolation a versioned ALPN gives the other planes. The ticket format and the room identity (topic_id) are unchanged; only the subscribed topic is namespaced. (The transform is for isolation, not security — cryptographic separation is the signature domain below.)
2. Signature domain (cryptographic separation): the signing domain string (peerspeak-gossip-v<N>, bound into every signed payload) carries the version, so two versions that somehow met on a topic would fail each other's verification rather than misread it.

Bumping the gossip version = bump protocol::GOSSIP_PROTO (drives versioned_topic) and protocol::GOSSIP_SIG_DOMAIN together (a unit test in protocol.rs asserts the domain string matches GOSSIP_PROTO, so they can't drift).

Single source of truth for protocol versions

All protocol versions, ALPNs, the gossip signature domain, and versioned_topic live in src/protocol.rs. Every call site derives from there (e.g. crate::protocol::AUDIO_ALPN); never hand-write an ALPN literal inline. A unit test asserts each ALPN/domain string matches its integer version so a bump can't half-apply.

---

"I changed X — what do I bump?" (quick reference)

You changed…	Layer 2 (plane version)	Layer 1 (Cargo.toml)
Opus framing / audio datagram layout	peerspeak/audio/N → N+1	MINOR
ControlMsg / presence shape	peerspeak/friends/N → N+1	MINOR
GossipPayload/PeerState/signing	GOSSIP_PROTO_VERSION + sig domain → next	MINOR
UI, local config, recording, a fix that doesn't touch any wire	nothing	PATCH
An additive gossip field that old peers safely ignore	judgement call — if old peers misbehave without it, treat as breaking (MINOR + gossip bump); if truly ignorable, PATCH	PATCH or MINOR

When in doubt about "is this additive-safe?", assume breaking and bump. A false MINOR bump costs a coordinated rebuild; a false PATCH costs silent broken calls in the field.

---

Release checklist (per build handed to anyone)

1. Decide MINOR vs PATCH from the table above; bump Cargo.toml.
2. If MINOR for a wire reason, confirm the matching Layer-2 plane version(s) were bumped in the same change.
3. Note the version + "breaking?" in the commit / handoff.
4. Tag the commit (v0.x.y) so a given binary maps to a known commit.
5. Rebuild every peer that must interoperate (e.g. dopedart, staged friend releases) when the bump was a MINOR/wire break.

---

Current baseline (standard adopted + migrated, 2026-06-18, 0.2.0)

• Cargo.toml: 0.2.0 — the MINOR bump for the (deliberately breaking) migration to this standard. All peers must run ≥ 0.2.0 to interoperate (the ALPNs and gossip topics changed); the pre-standard 0.1.0-era build (e.g. an un-resynced dopedart) cannot talk to a 0.2.0 peer — by design, and it now fails cleanly at the handshake instead of silently.
• Protocol versions (all at 1): peerspeak/audio/1, peerspeak/friends/1, gossip peerspeak-gossip-v1 + versioned_topic. All sourced from src/protocol.rs.
• Remaining nicety (not blocking): surface env!("CARGO_PKG_VERSION") in the UI (an About/Settings line) and/or log it at startup, so a running build is self-identifying in the field. Small follow-up.