Optional human-readable message attached to each publish, analogous to a git commit message. Stored on the Ref blob (signed, tamper-proof, permanent) and surfaced in the desktop publish UI, CLI, activity feed, and document versions panel.
Problem
Version history is opaque. When a user publishes a document, the only information recorded is the timestamp and the account that published. There is no way for the publisher to explain what changed or why. Collaborators browsing the activity feed or document versions panel see a flat list of updates with no context.
Solution
Add an optional message string field to the Ref blob. The message is set at publish time, included in the signed blob, and displayed wherever versions are shown.
Storage
The message lives on the Ref blob, not the Change blob. This is the correct location because:
Refs have a 1:1 relationship with versions (each publish creates exactly one Ref).
Refs are never garbage-collected, so the message is permanent.
Changes can be compacted or deduplicated; attaching the message there would risk losing it.
The field uses omitempty so existing Refs without a message remain valid. No migration is needed.
Stack
Proto: string message field on CreateRefRequest, CreateDocumentChangeRequest, and Ref.
Go daemon: threaded through NewRef, NewRefRedirect, CreateDocumentChange handler, and refToProto. Stored in extra_attrs JSON during indexing.
TypeScript client SDK: message parameter in ref.ts, change.ts, and client.ts.
CLI: --message / -m flag on document create and document update commands.
Desktop UI: textarea in the publish popover (publish-draft-button.tsx). Both daemon and seed-client publish paths forward the message.
Web client: create-web-universal-client.ts threads message through PublishDocumentInput.
Activity feed: loadRefEvent fetches the Ref via getRef, extracts the message. feed.tsx renders it as italic text below document-update events.
Document Versions panel: reuses the activity feed filtered to Ref events, so messages appear automatically.
Scope
Small feature, roughly two days of work across daemon, CLI, desktop UI, and feed display. Fully backward compatible.
Rabbit Holes
Change blob vs Ref blob storage. Considered storing the message on the Change blob, but Refs are the correct 1:1 representation of a published version and are never GC'd. Changes can be compacted, which would lose the message.
Rich text messages. Plain text is sufficient. Rich text adds complexity (rendering, sanitization, storage size) with no clear benefit for a short annotation.
Required vs optional. The message must be optional. Most publishes are quick saves that do not need an explanation. Making it required would add friction to the most common workflow.
No Goes
Comment threads on versions. Out of scope. This is a single annotation, not a discussion system.
Diff summaries. Generating a human-readable diff of what changed in the document is a separate feature.
AI-generated messages. Automatic summarization of changes is interesting but orthogonal. Can be layered on later by populating the same field.
Editing after publish. The message is part of the signed Ref blob. Changing it after the fact would require a new Ref, which changes the version identity. Not supported.
Do you like what you are reading?. Subscribe to receive updates.
Unsubscribe anytime