You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7b1310e
Browse filesBrowse the repository at this point in the historyBrowse files
SPEC_VERSION=$(uv run python -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["tool"]["apify"]["openapi-spec"]["version"])')
177
+
SPEC_VERSION=$(uv run python -m scripts.openapi_spec recorded-version)
178
+
179
+
# A moved version stamp proves the specification changed. An unchanged one proves nothing: apify-docs
180
+
# bumps `components/version.yaml` in a follow-up commit marked `[skip ci]`, so a deploy publishes new
181
+
# specification content still carrying the previous stamp. Say which case this is rather than let the
182
+
# reviewer assume the stamp is a content identity.
183
+
if [[ "$SPEC_VERSION" == "$PREVIOUS_SPEC_VERSION" ]]; then
184
+
SPEC_LINE="- Specification version: \`${SPEC_VERSION}\` - **unchanged**. The published stamp lags its content by a deploy, so this diff is either an unstamped specification change or a codegen/formatter change - the diff itself is the only way to tell."
"- Regenerates the Pydantic models, TypedDicts, and literal aliases from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json), and records the version they were generated from in \`pyproject.toml\`." \
158
-
"- Specification version: \`${SPEC_VERSION}\`." \
191
+
"${SPEC_LINE}" \
159
192
"" \
160
193
"> [!IMPORTANT]" \
161
194
"> Retitle this pull request to \`fix:\` or \`feat:\` when the diff is user-facing, so that it lands in the changelog and triggers a release - \`chore:\` does neither." \
Copy file name to clipboardExpand all lines: .rules.md
+4-2Lines changed: 4 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -82,9 +82,11 @@ Each input-side TypedDict ships in two casings: snake_case (`RequestDict`) and c
82
82
- To regenerate locally:
83
83
- From the live published spec: `uv run poe generate-models`
84
84
- From a local spec file: `uv run poe generate-models-from-file path/to/openapi.json`
85
-
-`scripts/openapi_spec.py` downloads the spec once into git-ignored `tmp/openapi.json` (both codegen passes read that copy, so a spec redeployed mid-run can't leave the generated files describing two different inputs), and afterwards records the spec's `info.version` in `pyproject.toml` under `[tool.apify.openapi-spec]`. That version is **provenance only** — the spec is served latest-only, so it can't fetch that exact document back. It moves together with the generated files, so it stays behind the published spec whenever a spec change leaves the models unchanged
85
+
-`scripts/openapi_spec.py` downloads the spec once into git-ignored `tmp/openapi.json` (both codegen passes read that copy, so a spec redeployed mid-run can't leave the generated files describing two different inputs), and afterwards records the spec's `info.version` in `pyproject.toml` under `[tool.apify.openapi-spec]`
86
+
- That version is a **coarse marker, not a content identity**: the spec is served latest-only, so it can't fetch that exact document back, and apify-docs bumps `components/version.yaml` in a follow-up `[skip ci]` commit — so a deploy publishes new spec content still carrying the previous stamp. A moved value proves the spec changed; an unchanged value proves nothing
87
+
- The recording is unconditional; the nightly workflow is what keeps it honest, by committing nothing unless the models changed. So the recorded version lands together with the generated files and stays behind the published spec while spec changes leave the models unchanged. A local `generate-models` that only moves that line is the same case — drop it instead of committing it alone. `generate-models-from-file` deliberately leaves the line alone, so models generated from a candidate spec must not be committed
86
88
- In CI, the `Regenerate models` workflow (`on_schedule_regenerate_models.yaml`) runs nightly at 02:00 UTC: it regenerates from the published spec and opens a PR when the models change. It always generates on master and rebuilds its `ci/regenerate-models` branch from master instead of appending, so the PR diff is always "current spec vs current master". The PR opens with a mergeable `chore:` title — retitle it to `fix:`/`feat:` when the diff is user-facing, so it lands in the changelog and triggers a release
87
-
- The gate is the **generated models**, not the spec version: that version carries a build timestamp apify-docs bumps on every spec change, so a version bump on its own says nothing about whether the client is affected
89
+
- The gate is the **generated models**, not the spec version: the version is a build timestamp that moves on spec rebuilds regardless of client impact, and (per above) doesn't reliably move at all — so it can't decide whether to open a PR
88
90
- Manual regeneration is also possible from the GitHub Actions UI (`Regenerate models` workflow)
&& echo "Generated from $input_file - the version in [tool.apify.openapi-spec] still names the published specification, so do not commit these models."
0 commit comments