Semantic Versioning (SemVer)

A SemVer-compliant version is expressed as MAJOR.MINOR.PATCH (e.g., 2.1.15). Each component communicates a specific type of change:

• MAJOR (X.0.0): Incremented for incompatible API changes.
• MINOR (1.X.0): Incremented for new, backward-compatible functionality.
• PATCH (1.0.X): Incremented for backward-compatible bug fixes. This structure allows automated systems, like package managers and deployment orchestrators, to understand the risk profile of an update without manual inspection of changelogs.

SemVer provides strict guarantees about backward compatibility, which is critical for agent deployment observability and safe rollouts.

• PATCH versions must not break functionality; they are safe for automatic updates.
• MINOR versions must remain backward-compatible; they add features but do not break existing integrations.
• MAJOR versions explicitly signal breaking changes, requiring manual review and potential adaptation of dependent agents or tool calls. This enables predictable canary deployments and traffic splitting strategies based on version risk.

SemVer supports labels for development and build stages, essential for staging deployments and A/B testing.

• Pre-release versions append a hyphen and identifiers (e.g., 2.0.0-alpha.1, 2.0.0-beta). These are considered unstable and have lower precedence than stable releases.
• Build metadata appends a plus sign and identifiers (e.g., 2.0.0+build.20240321). Metadata is ignored for version precedence but useful for tracking specific builds. This allows DevOps teams to deploy -rc (release candidate) versions to a subset of infrastructure for final validation before promoting a stable 2.0.0 release.

Package managers like npm and pip use SemVer rules to resolve dependencies automatically, a core concern for agent deployment observability to ensure deterministic environments.

• Caret Ranges (^1.2.3): Allow updates that do not modify the left-most non-zero digit. ^1.2.3 allows MINOR and PATCH updates (>=1.2.3 <2.0.0).
• Tilde Ranges (~1.2.3): Allow PATCH-level changes only (>=1.2.3 <1.3.0).
• Exact Matching (=1.2.3): Pins to a specific version. These rules prevent unexpected MAJOR version upgrades that could break an agent's tool calling or reasoning loops, maintaining system stability.

The core of SemVer is the Public API, which must be clearly defined and documented. Any change to this API dictates the version increment.

• The Public API includes exported functions, classes, interfaces, configuration schemas, and command-line interfaces.
• Internal, private code changes that do not affect the Public API only warrant a PATCH increment. For agentic systems, the Public API includes the agent's prompt schema, expected input/output formats for tool execution, and the structure of its memory or context object. Changes here must be communicated via the MAJOR version.

The initial development phase (versions 0.y.z) is exempt from SemVer's stability guarantees.

• Anything may change at any time. The Public API is not considered stable.
• MINOR version increments may contain breaking changes. This convention signals to consumers, such as teams integrating a new agent framework, that the software is in a rapid iteration phase and should not be relied upon for production agentic SLI/SLO definition. Moving to version 1.0.0 formally declares the API stable.

A deployment strategy where a new version of an application is incrementally released to a small, controlled subset of users or infrastructure. This allows for real-world validation of stability and performance before a full rollout.

• Primary Use: Mitigating risk by detecting issues early with minimal user impact.
• Key Observability: Requires detailed monitoring of error rates, latency, and business metrics for the canary group versus the baseline.

A release strategy that maintains two identical, fully isolated production environments (blue and green). Traffic is routed entirely to one environment (e.g., blue) while the new version is deployed to the other (green).

• Primary Use: Enabling instantaneous rollback by switching all traffic back to the stable environment if issues arise.
• Key Observability: Focuses on health checks and smoke tests in the idle environment before the traffic cutover.

A software development technique that uses conditional toggles (flags) to enable or disable functionality in a production environment without deploying new code. This decouples deployment from release.

• Primary Use: Enabling trunk-based development, A/B testing, and killing features quickly.
• Key Observability: Monitoring flag evaluation rates and tracking performance/error metrics per feature variant is essential.

The practice of directing a defined percentage of user requests or network traffic to different versions of a service. It is the underlying mechanism for canary deployments and A/B tests.

• Primary Use: Controlling the exposure of a new release to measure its effect.
• Key Observability: Implemented via service meshes (e.g., Istio) or API gateways, requiring observability tools to trace requests per version.

The process of reverting a software deployment to a previous, known-stable version. This is a critical failure mitigation procedure triggered by automated alerts or manual intervention.

• Primary Use: Responding to critical bugs, performance regressions, or failed health checks detected post-deployment.
• Key Observability: Relies on clear deployment status tracking, health probes, and pre-defined rollback procedures to minimize downtime.

A periodic test performed by an orchestrator (like Kubernetes) to verify an application instance is functioning correctly. Specific types include:

• Readiness Probe: Determines if a pod is ready to serve traffic.
• Liveness Probe: Determines if a pod should be restarted.
• Startup Probe: For slow-starting containers.
• Primary Use: Ensuring only healthy instances receive traffic and automating recovery from failures.