From 347d66da9b3e41145b2370e32655ba335c542212 Mon Sep 17 00:00:00 2001 From: Glenn Jocher Date: Mon, 21 Sep 2026 07:13:01 +0100 Subject: [PATCH 1/3] Document Platform consumer release version ownership --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index dd514ab..fe0453f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,6 +36,16 @@ This repository is a standalone, general-purpose OpenAPI-to-SDK and API document - Keep consumer customizations reproducible through generation and synchronization. Never hand-edit generated output or make the converter depend on a consumer repository. - Review every change against this boundary. Relocate application-specific work to its owner instead of teaching the converter about one application. +## Platform API and SDK release version (CRITICAL) + +**`ultralytics/portal` owns the version in `scripts/generate-openapi.ts` (Alpha's `info.version`). The `ultralytics-platform` SDK version MUST equal its API contract version.** The SDK repository consumes the deployed contract through automation; it does not choose release versions. + +- NEVER set SDK `python.version`, independently bump its patch, or hand-edit generated versions. API `0.1.50` with SDK `0.1.52` is INVALID; `max(API, SDK)` and automatic SDK patch bumps do not coordinate releases. +- SDK-only CLI/help/auth fixes and generator improvements follow the same sequence: merge the source fix, bump the contract version in Portal, deploy Alpha, then let SDK automation synchronize and publish that version. Verify the live contract and published wheel's required behavior before updating a consumer dependency. +- If the SDK is already published ahead of the API, advance Portal's contract beyond every published SDK version and synchronize. Never downgrade, reuse a published version, or claim the offset will self-heal. Read Portal's `apps/alpha/AGENTS.md` and SDK's `AGENTS.md` before coordinating a release. + +This is the Ultralytics Platform consumer release policy; keep it out of the general-purpose converter and preserve version configuration for third-party APIs. + ## Commands and validation ```bash From 11e221a40e8af0b053c0898ddb7b98c829f20225 Mon Sep 17 00:00:00 2001 From: Glenn Jocher Date: Mon, 21 Sep 2026 07:18:10 +0100 Subject: [PATCH 2/3] Keep public release guidance scoped to the upstream API --- AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fe0453f..45446ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,11 +38,11 @@ This repository is a standalone, general-purpose OpenAPI-to-SDK and API document ## Platform API and SDK release version (CRITICAL) -**`ultralytics/portal` owns the version in `scripts/generate-openapi.ts` (Alpha's `info.version`). The `ultralytics-platform` SDK version MUST equal its API contract version.** The SDK repository consumes the deployed contract through automation; it does not choose release versions. +**The upstream Platform API contract's `info.version` owns the `ultralytics-platform` SDK release version. The SDK version MUST equal its API contract version.** The SDK repository consumes the deployed contract through automation; it does not choose release versions. -- NEVER set SDK `python.version`, independently bump its patch, or hand-edit generated versions. API `0.1.50` with SDK `0.1.52` is INVALID; `max(API, SDK)` and automatic SDK patch bumps do not coordinate releases. -- SDK-only CLI/help/auth fixes and generator improvements follow the same sequence: merge the source fix, bump the contract version in Portal, deploy Alpha, then let SDK automation synchronize and publish that version. Verify the live contract and published wheel's required behavior before updating a consumer dependency. -- If the SDK is already published ahead of the API, advance Portal's contract beyond every published SDK version and synchronize. Never downgrade, reuse a published version, or claim the offset will self-heal. Read Portal's `apps/alpha/AGENTS.md` and SDK's `AGENTS.md` before coordinating a release. +- NEVER set Platform SDK `python.version`, independently bump its patch, or hand-edit generated versions. API `0.1.50` with SDK `0.1.52` is INVALID; `max(API, SDK)` and automatic SDK patch bumps do not coordinate releases. +- SDK-only CLI/help/auth fixes and generator improvements follow the same sequence: merge the source fix, coordinate a contract version bump and deployment with the Platform API maintainers, then let SDK automation synchronize and publish that version. Verify the live contract and published wheel's required behavior before updating a consumer dependency. +- If the SDK is already published ahead of the API, the API maintainers must advance the upstream contract beyond every published SDK version and synchronize. Never downgrade, reuse a published version, or claim the offset will self-heal. Read the SDK's `AGENTS.md` before coordinating a release. This is the Ultralytics Platform consumer release policy; keep it out of the general-purpose converter and preserve version configuration for third-party APIs. From 64821c5b2af220eef2428b841b63379778be547f Mon Sep 17 00:00:00 2001 From: Glenn Jocher Date: Mon, 21 Sep 2026 07:19:32 +0100 Subject: [PATCH 3/3] Document the public release guidance boundary --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 45446ef..8cf32c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,7 @@ This repository is a standalone, general-purpose OpenAPI-to-SDK and API document **The upstream Platform API contract's `info.version` owns the `ultralytics-platform` SDK release version. The SDK version MUST equal its API contract version.** The SDK repository consumes the deployed contract through automation; it does not choose release versions. +- Keep public documentation and PR text scoped to the public upstream API contract. Do not include private repository names, internal paths, or private PR links. - NEVER set Platform SDK `python.version`, independently bump its patch, or hand-edit generated versions. API `0.1.50` with SDK `0.1.52` is INVALID; `max(API, SDK)` and automatic SDK patch bumps do not coordinate releases. - SDK-only CLI/help/auth fixes and generator improvements follow the same sequence: merge the source fix, coordinate a contract version bump and deployment with the Platform API maintainers, then let SDK automation synchronize and publish that version. Verify the live contract and published wheel's required behavior before updating a consumer dependency. - If the SDK is already published ahead of the API, the API maintainers must advance the upstream contract beyond every published SDK version and synchronize. Never downgrade, reuse a published version, or claim the offset will self-heal. Read the SDK's `AGENTS.md` before coordinating a release.