From ba3740283a680125b93b739cf94f765eb73bf42a Mon Sep 17 00:00:00 2001 From: CometAPI Date: Mon, 27 Jul 2026 19:42:05 +0800 Subject: [PATCH] docs: record Registry Alpha release --- AGENTS.md | 50 ++++++++++++++++++++---------- ARCHITECTURE.md | 8 +++++ CHANGELOG.md | 5 ++- CONTRIBUTING.md | 8 ++--- README.md | 11 ++++--- RELEASING.md | 82 +++++++++++++++++++++++++++++-------------------- ROADMAP.md | 74 ++++++++++++++++++++++++++++++-------------- 7 files changed, 154 insertions(+), 84 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 573a0ae..6363511 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,17 +48,31 @@ proves only its own evidence layer. Never invent or mock missing evidence. Never reset, rebase, discard work, force-update refs, delete or recreate an existing `dev`, or push `dev` to recover. Report the exact state instead. -## Current milestone: Public Preview +## Current milestone: Registry Alpha -Public Preview ready; `0.1.0a1` Registry Alpha awaits explicit authorization. +Registry Alpha is complete: `cometapi==0.1.0a1` is publicly available and its +release and registry trust chain has been verified. Private Remote Validation, the sanitized first history, private initialization, -pre-visibility closeout, public visibility configuration, and Public Preview -readiness are completed historical steps and must not be repeated. The -canonical repository is public with protected branch and version-tag rules, -Private Vulnerability Reporting, immutable releases, protected environments, -public default-branch CI, and one authorized protected live-smoke result. No -tag, release, PyPI publication, or Registry Alpha claim exists. +pre-visibility closeout, public visibility configuration, Public Preview, and +the first Registry Alpha release are completed historical steps and must not be +repeated. The canonical repository is public with protected branch and +version-tag rules, Private Vulnerability Reporting, immutable releases, +protected environments, public default-branch CI, and protected release and +registry evidence. + +The accepted release evidence is: + +| Field | Value | +| --- | --- | +| Release commit | `31b68904141489ca04932edbf305ccf88af09372` | +| Recovery tag | `v0.1.0-alpha.1+recovery.1` | +| Tag object | `fdc4a6cce31f4534f83903f3f95e7757a4d4049f` | +| GitHub release | `https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0-alpha.1%2Brecovery.1` | +| Release workflow | `https://github.com/cometapi-dev/cometapi-python/actions/runs/30261746138` | +| PyPI release | `https://pypi.org/project/cometapi/0.1.0a1/` | +| Wheel SHA256 | `a6820347317943ca22f7632acbe354dd992f31a122a6172dfe45b57960e3a093` | +| Source SHA256 | `98d86829ef14771e8b7ec180d452c6638289f49c14a39b7207be5c47cb64cde7` | The accepted identity is: @@ -74,7 +88,7 @@ The accepted identity is: | Support and conduct | `support@cometapi.com` | | Security | `https://github.com/cometapi-dev/cometapi-python/security/advisories/new` | -At the Registry Alpha authorization gate: +Post-alpha invariants: 1. Treat the dependency dispositions recorded in `ROADMAP.md` as authoritative for the listed pull requests. Process newly opened dependency pull requests @@ -88,10 +102,13 @@ At the Registry Alpha authorization gate: 4. Treat the recorded public rules, security reporting, immutable releases, and protected environments as readiness invariants. Any drift invalidates the readiness claim until it is explicitly authorized, restored, and verified. -5. Stop before configuring the PyPI Trusted Publisher, changing release - documentation, enabling Release Please, creating a tag or release, making a - live release request, or publishing to PyPI unless the current maintainer - request separately authorizes the applicable action. +5. Keep the `pypi` environment approval assigned to the current release + approver with self-review allowed; the reviewer is GitHub configuration and + must not be hardcoded in repository files. +6. Treat the recovery tag, GitHub release, and PyPI distributions as immutable. + Any later live request, tag, release, Trusted Publisher change, publication, + or other registry mutation requires separate explicit maintainer + authorization. ## Repository independence @@ -259,14 +276,13 @@ passing. The gate must report every detected violation and fail until canonical identity, contacts, repository metadata, and durable public-facing content are complete. -Before preparing Registry Alpha, re-audit that `main` still requires pull +Before preparing any later release, re-audit that `main` still requires pull requests and blocking CI with zero required approvals, force pushes and deletion remain blocked, administrator bypass remains emergency-only, version tags remain protected, immutable releases and Private Vulnerability Reporting remain enabled, and the `live-smoke` and `pypi` environments retain their reviewed -protection boundaries. The one-time Public Preview live opt-in was reset to -false after its successful run; enable it again only for a separately authorized -monitoring request. +protection boundaries. `LIVE_SMOKE_ENABLED` is `false`; enable it only for a +separately authorized monitoring request. Verification reports must list exact commands and outcomes, failed or unavailable checks, and unverified remote, live, and registry evidence as diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index f6cb7e8..130b718 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -119,6 +119,14 @@ local mocked/package evidence -> public registry digest, provenance, install, import, and mocked smoke ``` +This complete trust chain executed successfully in +[release workflow run 30261746138](https://github.com/cometapi-dev/cometapi-python/actions/runs/30261746138) +for release commit `31b68904141489ca04932edbf305ccf88af09372`, recovery tag +`v0.1.0-alpha.1+recovery.1`, and PyPI version `0.1.0a1`. The public wheel and +source distribution matched the retained pre-publication digests, Trusted +Publisher provenance was verified, and the clean registry install/import/mocked +smoke passed. + The scheduled/manual default-branch smoke is an operational canary only; it does not prove the release commit. `COMETAPI_KEY` is exposed only to the protected exact-release live job. OIDC permission is exposed only to the diff --git a/CHANGELOG.md b/CHANGELOG.md index eebb482..cead319 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,10 @@ automation. ## [Unreleased] -No user-visible changes are currently recorded beyond the initial alpha scope. +### Changed + +- Release documentation now records completed Registry Alpha publication, + provenance, digest, clean-install, import, and mocked-call verification. ## [0.1.0a1] - 2026-07-27 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 575be3a..98757d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,9 @@ # Contributing to the CometAPI Python SDK -Thank you for helping improve the SDK. The repository is preparing the -unpublished `0.1.0a1` Registry Alpha candidate. Contributions must stay within -the supported 0.1 scope described in `README.md`, `ROADMAP.md`, and -`COMPATIBILITY.md`. The canonical repository is +Thank you for helping improve the SDK. The repository has released the +`0.1.0a1` Registry Alpha. Contributions must stay within the supported 0.1 +scope described in `README.md`, `ROADMAP.md`, and `COMPATIBILITY.md`. The +canonical repository is . ## Development setup diff --git a/README.md b/README.md index 3833529..4ccb62c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # CometAPI Python SDK -> **Pre-release:** `0.1.0a1` is approved for PyPI publication. Its API may -> change before `0.1.0`. +> **Pre-release:** `0.1.0a1` is available from PyPI. Its API may change before +> `0.1.0`. `cometapi` is a thin Python adapter over the official OpenAI SDK for the OpenAI-compatible CometAPI endpoint. It changes the default API key and base @@ -36,9 +36,10 @@ Install the exact alpha from PyPI with: python -m pip install --pre 'cometapi==0.1.0a1' ``` -Check the repository releases and -[PyPI project page](https://pypi.org/project/cometapi/) for current package -availability. +See the immutable +[GitHub prerelease](https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0-alpha.1%2Brecovery.1) +and exact [PyPI release](https://pypi.org/project/cometapi/0.1.0a1/) for the +published artifact. ## Authentication and configuration diff --git a/RELEASING.md b/RELEASING.md index b5a2796..0df7928 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -61,7 +61,7 @@ reason to repeat initialization. The fail-closed content and identity gate was required before the historical first remote push and passed again before Public Preview readiness. Keep running -it before Registry Alpha preparation and after public-document changes: +it before later releases and after public-document changes: ```bash uv run python scripts/check_version.py --require-public-preview-docs @@ -201,38 +201,31 @@ read-only by default; only the publishing job receives `id-token: write`. Publishing uses a protected `pypi` environment and concurrency control. Arbitrary-branch and manual publication are forbidden. -## Alpha release checklist +## Alpha release checklist (completed) For the current canonical repository, private initialization, pre-visibility closeout, public visibility, repository protection, environments, public -default-branch CI, and the one-time Public Preview live smoke are completed -historical prerequisites. Do not recreate or repeat them. The next external -actions prepare Registry Alpha and require separate explicit authorization. -This checklist defines dependency order, not standing permission: every remote -mutation, live request, release action, and registry action must be explicitly -authorized in the current maintainer request; stop otherwise. - -Before continuing, re-audit the recorded Public Preview invariants: protected -`main` and version tags, immutable releases, Private Vulnerability Reporting, -the `live-smoke` and `pypi` environment boundaries, `LIVE_SMOKE_ENABLED=false`, -absent `CODEOWNERS`, and disabled Release Please. Maintainers then execute the -remaining authorized steps in order: - -1. Confirm that the company-managed PyPI identity `dev@cometapi.com` owns or can - create the unscoped PyPI package `cometapi`, and configure the - Trusted Publisher for the exact repository, workflow, and `pypi` - environment. -2. Confirm the protected `COMETAPI_KEY`, the approved `COMETAPI_LIVE_MODEL`, - and explicit authorization for the documented four-request, 16-token, 30-second, - concurrency-one, stop-on-failure budget before creating the GitHub - prerelease. -3. Replace the pre-release availability notice and source-installation text in - `README.md` with the release-neutral, maintainer-confirmed sentence - “`0.1.0a1` is approved for PyPI publication.” Date the `0.1.0a1` heading in - `CHANGELOG.md`, remove its candidate/unpublished wording, and rerun every +default-branch CI, the one-time Public Preview live smoke, and Registry Alpha +are completed historical steps. Do not recreate or repeat them. This checklist +records the dependency order that was executed; it grants no standing +permission for later remote mutations, live requests, release actions, or +registry actions. + +The recorded Public Preview invariants were re-audited before release: +protected `main` and version tags, immutable releases, Private Vulnerability +Reporting, the `live-smoke` and `pypi` environment boundaries, +`LIVE_SMOKE_ENABLED=false`, absent `CODEOWNERS`, and disabled Release Please. +Maintainers then completed these steps in order: + +1. Confirmed company-managed PyPI ownership and configured the Trusted + Publisher for the exact repository, workflow, and `pypi` environment. +2. Confirmed the protected `COMETAPI_KEY`, approved live model, and explicit + authorization for the documented four-request, 16-token, 30-second, + concurrency-one, stop-on-failure budget. +3. Finalized the dated changelog and prerelease documentation and reran every candidate verification gate, including `uv run python scripts/check_version.py --expected 0.1.0a1 --require-changelog --require-releasable-docs`. -4. Review the exact candidate and create the immutable SemVer recovery tag +4. Reviewed the exact candidate and created the immutable SemVer recovery tag `v0.1.0-alpha.1+recovery.1` and corresponding GitHub prerelease. GitHub permanently reserved `v0.1.0-alpha.1` after its immutable release reached OIDC publication but failed before PyPI accepted any distribution. The @@ -241,12 +234,11 @@ remaining authorized steps in order: for later releases. Keep Release Please disabled until a separate reviewed and tested `last-release-sha` bridge establishes this recovery commit as its previous-release boundary. -5. Allow the release workflow to prove `immutable=true`, resolve the tag to the - checked-out commit, verify that commit is reachable from the protected - default branch, and run the bounded protected live suite against that exact - commit. Only successful completion makes the protected PyPI approval - eligible; approve that job after reviewing its retained artifact digests. -6. Verify publication, provenance, public artifact identity and digest, clean +5. The release workflow proved `immutable=true`, resolved the tag to the + checked-out commit, verified that commit was reachable from the protected + default branch, and ran the bounded protected live suite against that exact + commit before the protected PyPI approval was granted. +6. Verified publication, provenance, public artifact identity and digest, clean installation, import, and the public-registry mocked-call smoke. Missing credentials, model/budget approval, environments, publisher @@ -261,6 +253,28 @@ The version checker must normalize the SemVer tag and PEP 440 package spelling to the same `0.1.0a1` value across the tag, release manifest, package metadata, changelog, GitHub release, wheel, and source distribution. +### Completed Registry Alpha evidence + +- Metadata [PR #16](https://github.com/cometapi-dev/cometapi-python/pull/16) + merged as `6344c2d0e2e975360b42c887275c1950b82918ee`; recovery contract + [PR #17](https://github.com/cometapi-dev/cometapi-python/pull/17) merged as + release commit `31b68904141489ca04932edbf305ccf88af09372`. +- Annotated tag `v0.1.0-alpha.1+recovery.1` has tag object + `fdc4a6cce31f4534f83903f3f95e7757a4d4049f`, peels to the release commit, + and identifies the + [immutable GitHub prerelease](https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0-alpha.1%2Brecovery.1). +- [Release workflow run 30261746138](https://github.com/cometapi-dev/cometapi-python/actions/runs/30261746138) + passed the exact artifact gates, authorized protected live smoke, protected + environment approval, PyPI OIDC Trusted Publishing, provenance check, public + digest comparison, clean registry installation, imports, and mocked-call + smoke. +- The exact [PyPI release](https://pypi.org/project/cometapi/0.1.0a1/) has wheel + SHA256 `a6820347317943ca22f7632acbe354dd992f31a122a6172dfe45b57960e3a093` + and source-distribution SHA256 + `98d86829ef14771e8b7ec180d452c6638289f49c14a39b7207be5c47cb64cde7`. +- `LIVE_SMOKE_ENABLED=false`. Release Please remains disabled until a separate + reviewed and tested `last-release-sha` bridge is merged. + ## Stable release sequence ```text diff --git a/ROADMAP.md b/ROADMAP.md index 6afe2ec..4d540bf 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,9 +1,9 @@ # CometAPI Python SDK Roadmap -Status: `0.1.0a1` in progress +Status: `0.1.0a1` released Last updated: 2026-07-27 Repository contract: this roadmap is self-contained. -Current gate: Public Preview ready; `0.1.0a1` Registry Alpha awaiting explicit authorization. +Current gate: `0.1.0a1` Registry Alpha complete; `0.1.0` stable planned. ## Product target @@ -11,13 +11,12 @@ The SDK provides the shortest reliable path from an OpenAI Python integration to CometAPI while preserving official request, response, error, retry, timeout, sync, async, and streaming behavior. -Private Remote Validation and Public Preview are complete for the sanitized -public repository. Protected repository configuration, public default-branch -CI, and an authorized live smoke establish preview readiness. Public Preview -and the functional `0.1.0a1` prerelease remain separate evidence gates; the next -external actions require separate Registry Alpha authorization. Support and -release claims remain limited to the evidence defined in this roadmap and -`COMPATIBILITY.md`. +Private Remote Validation, Public Preview, and the functional `0.1.0a1` +Registry Alpha are complete for the sanitized public repository. Protected +repository configuration, public default-branch CI, exact-release live smoke, +PyPI OIDC publication, provenance, digest comparison, and public-registry smoke +provide separate evidence layers. Support and release claims remain limited to +the evidence defined in this roadmap and `COMPATIBILITY.md`. ## Milestones @@ -26,7 +25,7 @@ release claims remain limited to the evidence defined in this roadmap and | Repository foundation | Complete | Public files, offline gates, packaging checks, and self-containment are complete. | | Private Remote Validation | Complete | The sanitized private repository passes real credential-free default-branch CI; public-only controls and live tests remain disabled. | | Public Preview | Complete | The public repository has blocking CI, repository rules, security reporting, protected environments, immutable releases, and authorized live-smoke evidence. | -| `0.1.0a1` Registry Alpha | Awaiting authorization | Early adopters can install a functional prerelease from PyPI after every release and registry gate passes. | +| `0.1.0a1` Registry Alpha | Complete | Early adopters can install the functional prerelease from PyPI; every release and registry gate passed. | | `0.1.0` stable | Planned | Complete runtime, release-PR, example, provenance, and registry gates pass. | | `0.2.0` provider-native text | Planned | Optional official Anthropic and Gemini adapters. | | `0.3.0` CometAPI resources | Planned | First schema-backed typed CometAPI-specific resource. | @@ -117,8 +116,8 @@ described as unfinished. The milestone was established only after repository rules, Private Vulnerability Reporting, immutable releases, protected environments, public default-branch CI, the public-content gate, and an authorized protected -live smoke passed. Registry Alpha remains a separate authorization and evidence -gate. +live smoke passed. Registry Alpha remained a separate authorization and +evidence gate and was completed later the same day. Recorded pre-visibility dependency dispositions: @@ -313,8 +312,9 @@ Public Preview readiness evidence on 2026-07-27: `gpt-5.4` within the four-request, 16-output-token, 30-second-per-request, concurrency-one, zero-retry, stop-on-first-failure budget. The `LIVE_SMOKE_ENABLED` opt-in was reset to `false` after the run. -- No tag, GitHub release, Trusted Publisher, PyPI OIDC publication, provenance, - or public-registry installation was created or claimed. Release Please remains +- At this Public Preview checkpoint, no tag, GitHub release, Trusted Publisher, + PyPI OIDC publication, provenance, or public-registry installation existed. + Those later Registry Alpha actions are recorded below. Release Please remains disabled until a separately reviewed and tested `last-release-sha` bridge establishes the recovery alpha as its previous-release boundary. @@ -338,6 +338,8 @@ Public Preview remains ready only while: ## `0.1.0a1`: Registry Alpha +Registry Alpha completed on 2026-07-27. + ### User-visible scope - `CometAPI` and `AsyncCometAPI`. @@ -369,16 +371,16 @@ Public Preview remains ready only while: - CLI or Go SDK changes. - `CometClient` or `AsyncCometClient` compatibility aliases. -### Release gates +### Completed release gates -Before the alpha may be called released, maintainers must confirm package -ownership and PyPI pending Trusted Publisher configuration, authorize a -budgeted live smoke run, and review the release documentation. The release -workflow must then prove that the immutable tag target is the checked-out -commit and belongs to the protected default branch, run the protected live -suite against that exact commit, and only then make protected PyPI approval -eligible. Public artifact identity, digest, provenance, import, clean install, -and mocked calls remain separate post-publication evidence. +The alpha was not called released until maintainers confirmed package ownership +and PyPI Trusted Publisher configuration, authorized the budgeted live smoke, +and reviewed the release documentation. The release workflow proved that the +immutable tag target was the checked-out commit and belonged to the protected +default branch, ran the protected live suite against that exact commit, and +only then made protected PyPI approval eligible. Public artifact identity, +digest, provenance, import, clean install, and mocked calls were verified as +separate post-publication evidence. A mock never satisfies a live gate, static workflow validation never proves a remote run, and a successful upload never proves registry installation. @@ -391,6 +393,32 @@ approved recovery release therefore uses `v0.1.0-alpha.1+recovery.1`, whose SemVer build suffix leaves the PyPI package version at the required first public artifact `0.1.0a1`. +Accepted release evidence: + +- Metadata fix [PR #16](https://github.com/cometapi-dev/cometapi-python/pull/16) + merged as `6344c2d0e2e975360b42c887275c1950b82918ee`; recovery contract + [PR #17](https://github.com/cometapi-dev/cometapi-python/pull/17) merged as + release commit `31b68904141489ca04932edbf305ccf88af09372`. Final + [default-branch CI run 30261497883](https://github.com/cometapi-dev/cometapi-python/actions/runs/30261497883) + passed. +- Annotated tag `v0.1.0-alpha.1+recovery.1` has tag object + `fdc4a6cce31f4534f83903f3f95e7757a4d4049f` and peels to the release + commit. The corresponding + [immutable GitHub prerelease](https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0-alpha.1%2Brecovery.1) + is release `360377046`. +- [Release workflow run 30261746138](https://github.com/cometapi-dev/cometapi-python/actions/runs/30261746138) + passed exact artifact construction and validation, the authorized four-request + protected live smoke, protected `pypi` approval, OIDC Trusted Publishing, + provenance verification, public digest comparison, clean PyPI installation, + imports, and the public-registry mocked-call smoke. +- The exact [PyPI release](https://pypi.org/project/cometapi/0.1.0a1/) is public. + Its wheel SHA256 is + `a6820347317943ca22f7632acbe354dd992f31a122a6172dfe45b57960e3a093` and + its source-distribution SHA256 is + `98d86829ef14771e8b7ec180d452c6638289f49c14a39b7207be5c47cb64cde7`. +- `LIVE_SMOKE_ENABLED=false`. Release Please remains disabled pending a + separately reviewed and tested `last-release-sha` bridge. + ## `0.1.0`: OpenAI protocol foundation Stable 0.1 retains the alpha surface. Its additional exit criteria are: