Versioning & Compatibility

Module versioning in a multi-module system is a compatibility problem. Module A v2.0 emits events in a new format. Module B, still at v1.3, cannot parse the new format. The pipeline breaks. Versioning strategy determines whether module updates are smooth upgrades or cascading failures.

Semantic versioning is the minimum. Major versions break backward compatibility — consumers must adapt. Minor versions add capabilities without breaking existing consumers. Patch versions fix bugs without changing behavior. Beyond semver, the compatibility strategy requires: event schema versioning (events carry a version field so consumers can handle multiple formats), deprecation windows (old event formats continue for at least one minor version after the new format is introduced), and compatibility matrices (a published table showing which versions of which modules are tested together).