Clarify OpenAPI spec and baseline update workflow

Author: Anonymous Committer

README.md

@@ -94,19 +94,35 @@ This repository only owns the Python SDK. The canonical OpenAPI document plus th
 - If `openapi/justserpapi.openapi.json` is committed, local generation is fully reproducible.
 - If it is not committed, CI can fetch and cache it by running `python scripts/sdkctl.py fetch-spec` with `JUSTSERPAPI_API_KEY` configured.
 
-Typical maintenance flow:
+If the API changes, update these files:
+
+- `openapi/justserpapi.openapi.json`: the current canonical spec used to validate and generate the SDK
+- `openapi/baseline/justserpapi.openapi.json`: the previous released spec snapshot used only for breaking-change checks
+
+Typical maintenance flow after an API change:
 
 ```bash
+cp /path/to/latest-openapi.json openapi/justserpapi.openapi.json
 python scripts/sdkctl.py validate-examples
-python scripts/sdkctl.py validate-spec --skip-generator-validate
+python scripts/sdkctl.py validate-spec
+python scripts/sdkctl.py breaking-check
 python scripts/sdkctl.py generate --clean
 ```
 
+If this new spec is the one you are about to release, update the baseline after validation:
+
+```bash
+cp openapi/justserpapi.openapi.json openapi/baseline/justserpapi.openapi.json
+```
+
 ## Release
 
 Official releases are tag-driven:
 
 ```bash
+python scripts/sdkctl.py validate-examples
+python scripts/sdkctl.py verify-release --tag vX.Y.Z
+python -m build
 python scripts/sdkctl.py verify-release --tag vX.Y.Z
 git push origin vX.Y.Z
 ```

openapi/README.md

@@ -1,26 +1,33 @@
 # Canonical OpenAPI Document
 
-This directory is the source of truth for every SDK repository.
+This directory is the source of truth for the Python SDK.
 
 Expected files:
 
-- `openapi/justserpapi.openapi.json`: the canonical OpenAPI document that drives Python, Java, and Go generation.
-- `openapi/baseline/justserpapi.openapi.json`: the last released spec snapshot used for breaking-change checks.
+- `openapi/justserpapi.openapi.json`: the canonical OpenAPI document that drives Python SDK validation and generation.
+- `openapi/baseline/justserpapi.openapi.json`: the previous released spec snapshot used for breaking-change checks.
 
 If the canonical spec is not committed, CI is expected to fetch it with `python scripts/sdkctl.py fetch-spec` and cache it as a workflow artifact.
 
-Bootstrap flow:
+When the API changes:
 
 1. Export or fetch the latest OpenAPI document into `openapi/justserpapi.openapi.json`.
 2. Run `python scripts/sdkctl.py validate-examples`.
 3. Run `python scripts/sdkctl.py validate-spec`.
-4. Run `python scripts/sdkctl.py generate --clean`.
-5. Run `python scripts/sdkctl.py sync-repos --push --tag` once the generated outputs look correct.
+4. Run `python scripts/sdkctl.py breaking-check` if `openapi/baseline/justserpapi.openapi.json` exists.
+5. Run `python scripts/sdkctl.py generate --clean`.
+6. If the spec is the next release candidate, copy it to `openapi/baseline/justserpapi.openapi.json` after validation.
 
 If the API spec is protected, fetch it with:
 
 ```bash
 JUSTSERPAPI_API_KEY=... python scripts/sdkctl.py fetch-spec
 ```
 
-The repo currently ships test fixtures under `tests/fixtures/` so CI can exercise the orchestration code even when the canonical spec must be fetched at workflow time.
+Release reminder:
+
+- `openapi/justserpapi.openapi.json` should describe the next release
+- `openapi/baseline/justserpapi.openapi.json` should describe the last published release
+- if `info.version` changes, keep `justserpapi/_version.py` in sync before tagging
+
+The repo ships test fixtures under `tests/fixtures/` so CI can exercise the tooling even when the canonical spec must be fetched at workflow time.

openapi/baseline/README.md

@@ -4,7 +4,13 @@ Store the previously released canonical OpenAPI document here.
 
 Recommended convention:
 
-- `openapi/justserpapi.openapi.json` is the next candidate spec.
-- `openapi/baseline/justserpapi.openapi.json` is the last published spec.
+- `openapi/justserpapi.openapi.json` is the next candidate spec you are validating now.
+- `openapi/baseline/justserpapi.openapi.json` is the last published spec already in production.
 
 `python scripts/sdkctl.py breaking-check` compares these two files and fails on obvious breaking changes such as removed operations, renamed `operationId` values, and newly required parameters.
+
+Update the baseline only after you have decided the current spec is the one you will release:
+
+```bash
+cp openapi/justserpapi.openapi.json openapi/baseline/justserpapi.openapi.json
+```