Semiotic Changelog

This specification defines changelogs interpreted as the trace operator G applied to versioned artifacts. It is a convention specification (per semiotic-specification) in the same family as semiotic-versioning, semiotic-git, and semiotic-markdown.

Specification category: convention specification. Canonicalization and wire-format determinism sections do not apply.

A changelog is not an administrative convenience appended to a release. It is the trace of an artifact’s development: the record of how the interaction surface moved between versions and why. The trace carries provenance. Without it, two artifacts at the same version number are indistinguishable even if they arrived there through different histories. The changelog makes the path visible.

0. Scope

This specification applies to changelogs for any versioned artifact in the emsemioverse: specifications, software releases, formal definitions, and content that carries stability commitments (per semiotic-versioning). It does not replace the Keep a Changelog convention (Lacan, 2017) but interprets it: Keep a Changelog’s rules are practical consequences of the semiotic model described here.

1. Semantic carrier

1.1 Changelog identity

A changelog is an ordered sequence of entries, each recording a transition between two states of an artifact’s interaction surface. The sequence is a named element of the trace comonad G applied to the artifact’s version history: it records not just where the artifact is but how it got there.

A changelog is intensional. Two artifacts with identical interaction surfaces but different changelogs have different provenance. The changelog carries the derivational history that the version number alone does not.

1.2 Changelog entries

A changelog entry is a record of one step in the trace. Each entry MUST contain:

• Version: the version identifier this entry describes (per semiotic-versioning section 1.3).
• Date: when the version was released (ISO 8601).
• Categories: one or more of the categories defined in section 2.

Each entry SHOULD contain:

• Summary: a one-line description of the release’s purpose.
• Migration guidance: for entries containing breaking changes, what dependents need to do.

1.3 Entry ordering

Entries MUST be ordered reverse-chronologically: the most recent version appears first. This follows Keep a Changelog convention and reflects the reader’s primary question: “what changed most recently?”

An Unreleased section MAY appear before the first versioned entry, collecting changes that have been made since the last release but not yet published under a version number.

2. Change categories

2.1 The five categories

Change categories classify how the interaction surface moved. They are not arbitrary labels; they are the exhaustive taxonomy of how a versioned commitment can change.

These categories are complete. Any change to a versioned artifact falls into exactly one of them:

• Added: the interaction surface grew. New relations, new behaviors, new commitments. Existing dependents are unaffected because nothing they relied on changed. MINOR increment.
• Changed: an existing element of the interaction surface was modified. If the modification preserves all existing dependencies (backward-compatible), it is MINOR. If it may violate existing dependencies, it is MAJOR.
• Fixed: a defect was corrected without changing the interaction surface. The surface was always supposed to work this way; now it does. PATCH increment.
• Removed: an element of the interaction surface was withdrawn. Dependents that relied on it will break. MAJOR increment.
• Deprecated: an element of the interaction surface is marked for future removal. The element still exists and functions; dependents are not yet broken. But the signal says: migrate. MINOR increment (the surface has not yet shrunk).

2.2 Category as surface diagnosis

The category of a change is determined by what happened to the interaction surface, not by what the developer did internally. A large refactoring that preserves the interaction surface is Fixed (or no entry at all). A one-line change that removes a public API endpoint is Removed.

This means the changelog author MUST think from the dependent’s perspective: what does a consumer of this artifact see differently? That is the only question that determines the category.

2.3 Changed requires qualification

The Changed category is ambiguous: it could be MINOR (backward- compatible modification) or MAJOR (breaking modification). A Changed entry MUST state whether the change is backward-compatible. If it is not, the entry MUST include migration guidance.

3. Modality and trace

3.1 The changelog as trace operator

In the semiotic universe, the trace comonad G records derivational history. Applied to versioning, G produces the changelog: the ordered sequence of interaction surface transitions.

Each changelog entry is a morphism in the version category: it maps from the previous version’s interaction surface to the current version’s. The full changelog is the composition of these morphisms back to the initial version.

This means the changelog carries information that no single version does: it records the path through version space, not just the destination. Two artifacts at version 2.3.1 with different changelogs are at the same point in version space but arrived via different paths.

3.2 Completeness

A changelog SHOULD be complete: every version SHOULD have an entry. Gaps in the changelog are gaps in the trace. A version without a changelog entry has undocumented provenance.

In practice, completeness may be relaxed for pre-1.0 development: draft-stability artifacts (per semiotic-versioning section 2.1) MAY omit changelog entries for rapid iteration. Once an artifact reaches stable status, its changelog MUST be complete from that point forward.

3.3 Immutability

Published changelog entries MUST NOT be retroactively modified. If a changelog entry was incorrect, the correction appears in a subsequent entry, not as an edit to the original. This follows the same principle as decision records (append-only) and reflects the trace’s role as an immutable derivational record.

An Unreleased section is mutable until it is published under a version number. Once published, it becomes immutable.

4. Operators and interactions

4.1 Changelog composition across dependencies

When artifact A depends on artifact B (via requires: or extends:), a breaking change in B may propagate to A. The changelog of A SHOULD note such propagated changes, referencing the upstream changelog entry that caused them.

This makes dependency-propagated changes visible to A’s consumers, who may not read B’s changelog. The entry in A’s changelog says: “Changed (breaking): updated to B v3.0.0, which removed feature X. See B’s changelog for details.”

4.2 Changelog and the deprecation window

The deprecation window (per semiotic-versioning section 3.2) is the gap between a Deprecated entry and the subsequent Removed entry. The changelog makes this window explicit and measurable: the Deprecated entry marks the start, the Removed entry marks the end.

A Deprecated entry SHOULD state what replaces the deprecated element and when removal is planned. A Removed entry MUST reference the version in which the element was deprecated.

4.3 Audience

Changelogs are for humans, not machines (Keep a Changelog principle). Entries MUST describe changes in terms of what the reader will notice, not in terms of implementation details. The reader’s question is: “what does this mean for me?” The entry answers that question.

This does not prohibit technical specificity. An entry like “Added: stability field in specification frontmatter (per semiotic- specification section 1)” is precise and reader-oriented. An entry like “Refactored the YAML parser’s validation pipeline” is not — unless the refactoring changed observable behavior.

5. Application to this repository

5.1 Specification changelogs

Specifications that declare version: in frontmatter (per semiotic-specification) SHOULD maintain a changelog. The changelog MAY be:

• A ## Changelog section within the specification’s index.md (suitable for specifications with short change histories).
• A separate CHANGELOG.md file in the specification’s directory (suitable for specifications with long change histories).

The specification’s frontmatter does not need to reference the changelog location; by convention it is either inline or at CHANGELOG.md in the same directory.

5.2 Software changelogs

Scripts, MCP servers, and other software artifacts SHOULD maintain a CHANGELOG.md following Keep a Changelog format. The file lives in the artifact’s root directory.

5.3 Repository-level changelog

The repository as a whole MAY maintain a changelog at content/CHANGELOG.md. This records changes to the repository’s shared infrastructure: specifications, governance structures, directory conventions, and build pipeline changes. It does not record individual content additions (those are tracked by git history and by discipline-level activity).

5.4 Changelog format

Changelog entries MUST use the following markdown format:

## [version] - YYYY-MM-DD
 
Optional one-line summary.
 
### Added
- Description of new feature or capability.
 
### Changed
- Description of modification. (backward-compatible | breaking)
 
### Fixed
- Description of correction.
 
### Removed
- Description of withdrawal. (deprecated in version X.Y.Z)
 
### Deprecated
- Description of element marked for removal. Superseded by [X].

Omit categories that have no entries for a given version. The category order (Added, Changed, Fixed, Removed, Deprecated) is conventional and SHOULD be followed for consistency.

Glossary

• Changelog: the trace of an artifact’s version history — an ordered sequence of entries recording how the interaction surface changed between versions and why.
• Changelog entry: a record of one version transition, containing the version identifier, date, categorized changes, and optional migration guidance.
• Change category: one of five classifications (Added, Changed, Fixed, Removed, Deprecated) determined by what happened to the interaction surface.
• Deprecation window: the interval between a Deprecated entry and the corresponding Removed entry, during which dependents can migrate.
• Trace: the derivational record of how an artifact arrived at its current state — the path through version space, not just the destination.
• Unreleased section: a mutable section collecting changes not yet assigned a version number.

Rationale (non-normative)

Keep a Changelog is a practical convention that works. Its categories (Added, Changed, Fixed, Removed, Deprecated) are intuitive and widely adopted. This specification does not replace it but grounds it: the categories are not arbitrary — they are the exhaustive taxonomy of interaction surface transitions. Added is monotone extension, Removed is non-monotone reduction, Fixed is identity, Deprecated is a signal with no surface change, and Changed is the one category that requires qualification because it spans the MINOR/MAJOR boundary.

The trace interpretation adds something Keep a Changelog does not provide: a formal account of why changelogs matter. A changelog is not documentation of work performed. It is the derivational record that gives provenance to versions. Without the trace, versions are opaque points; with it, they are positions in a derivational history.

The immutability requirement follows from the trace’s role as a record. Editing a published changelog entry is rewriting history. The trace says “here is how we got here.” If we edit the trace, we lose the actual path and replace it with a preferred narrative. The correction mechanism (new entry, not retroactive edit) preserves the actual history while recording the correction.

Relationship to other specs

• Follows: semiotic-specification (this is a convention specification).
• Requires: semiotic-versioning (changelogs record version transitions; this spec depends on the versioning model).
• Requires: semiotic-markdown (changelogs are markdown documents).
• Interprets: Keep a Changelog 1.1.0 (Lacan, 2017) — the convention’s rules are practical consequences of the model here.
• Extends: semiotic-versioning section 2.2 (which defines changelog as trace G applied to versioning; this spec develops that identification into a full specification).