How Should a Protocol Publish Revision History?
From the earlier reference collection. Read the current software blog.
A useful revision history records when a version changed, what changed, and how the change affects compatibility and implementers.
Record an identifiable revision
A revision history should let readers identify the document version they are using. Include a revision date or version identifier and keep older entries available when practical. If a file can be republished without changing its version label, say how readers distinguish editorial corrections from changes to the protocol contract.
A date alone is not enough if readers cannot tell which specification it applies to. Place the history with the reference or link it clearly from the versioned document. When a dataset or schema has a separate versioning scheme, distinguish that from the document’s own revision.
Describe changes concretely
Summarize changes by affected fields, messages, or rules. “Updated fare section” gives little help to a developer reviewing a parser. “Added an optional transfer condition field to the fare rule definition” points to the affected area and helps readers decide whether to inspect their implementation.
Keep entries concise but specific. State whether a new field is optional or required, whether a previous interpretation was corrected, and whether examples or validation expectations changed. If the document has an authoritative change log or revision section, connect the summary to the exact parts that changed.
Explain compatibility effects
Readers need to know whether existing producers and consumers can continue to interoperate. Classify the likely effect in clear language: for example, an optional field may be an additive change for readers that tolerate unknown fields, while making a previously optional field mandatory can require existing producers to change. Explain any assumptions behind the classification, since compatibility depends on how implementations handle extensions.
If a change alters the meaning of existing data, describe migration or version negotiation expectations. Do not call a change backward-compatible without considering older readers, newer writers, and systems that preserve or discard unknown information. A brief impact note can save teams from discovering a break only after deployment.
Make history useful over time
A revision entry should answer three questions: when did the change appear, what parts changed, and what should implementers review? Add links or anchors to modified sections when the publishing format supports them. Keep superseded versions accessible when readers may need to understand older data or reproduce a prior implementation.
Treat the history as part of the interface. A clear record helps operators connect an observed behavior to a specification revision, and gives implementers a focused review path. It also makes protocol evolution visible instead of hiding consequential changes in a rewritten document.