Versioning & Updates

Versioning Strategy

The testing-api follows Semantic Versioning 2.0.0 (SemVer). This ensures that integrations with the Supervised AI platform remain stable and predictable as the testing structure evolves.

Versions are expressed in the MAJOR.MINOR.PATCH format:

• MAJOR: Incremented for incompatible API changes or structural shifts in the testing schema.
• MINOR: Incremented for backward-compatible functionality, such as adding new optional fields or testing metadata.
• PATCH: Incremented for backward-compatible bug fixes or documentation clarifications.

Breaking Changes Protocol

A "breaking change" is defined as any modification that requires users to update their implementation to maintain existing functionality. Examples include:

• Removing or renaming existing fields in the API response.
• Changing a field's data type (e.g., converting a string to an array).
• Increasing strictness in validation logic for incoming test payloads.
• Modifying the required sequence of API calls for test execution.

Transition Process

When a breaking change is necessary, the following protocol is observed:

1. Deprecation Notice: Affected features are marked as deprecated in the documentation and, where applicable, via header warnings in API responses.
2. Major Version Bump: The changes are released under a new Major version (e.g., v1.x.x to v2.0.0).
3. Support Window: The previous Major version enters a maintenance phase for a designated period (typically 3-6 months) before reaching End-of-Life (EOL).

Backward Compatibility

We strive to maintain backward compatibility within the same Major version. You can safely update to any Minor or Patch release without modifying your integration code.

// Example: Adding a new field (Minor Update)
// Old Schema
{
  "test_id": "uuid-123",
  "status": "passed"
}

// New Schema (Backward Compatible)
{
  "test_id": "uuid-123",
  "status": "passed",
  "duration_ms": 450 // New optional field
}

Update Notifications

To stay informed about updates and breaking changes:

• Changelog: All changes are documented in the CHANGELOG.md file in the root of the repository.
• GitHub Releases: We recommend "Watching" the repository for new releases to receive automated notifications regarding version bumps.
• Platform Announcements: Critical updates affecting the Supervised AI platform ecosystem are communicated via the official developer mailing list.