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 dc06b74
Browse filesBrowse the repository at this point in the historyBrowse files
SPEC_VERSION=$(uv run python -m scripts.openapi_spec recorded-version)
178
167
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.
168
+
# A moved stamp proves the specification changed; an unchanged one proves nothing, because apify-docs bumps
169
+
# `components/version.yaml` in a follow-up `[skip ci]` commit and a deploy can publish new content under
170
+
# the old stamp. Say which case this is instead of letting the reviewer read it as a content identity.
183
171
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."
172
+
SPEC_LINE="- Specification version: \`${SPEC_VERSION}\` - **unchanged**, which doesn't rule out a specification change: the published stamp can lag its content by a deploy. Only the diff tells."
"- 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\`." \
178
+
"- Regenerates the Pydantic models, TypedDicts, and literal aliases from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json), and records its version in \`pyproject.toml\`." \
191
179
"${SPEC_LINE}" \
192
180
"" \
193
181
"> [!IMPORTANT]" \
@@ -203,9 +191,8 @@ jobs:
203
191
--assignee "$ASSIGNEE" \
204
192
--label "$LABEL"
205
193
206
-
# Alert the team when a scheduled run fails. Without this a broken sync stops model regeneration silently:
207
-
# for a scheduled workflow GitHub only notifies whoever last touched the cron, and this workflow is not part
208
-
# of the checks that releases wait on. Skipped on manual dispatch so ad-hoc triggers don't spam the channel.
194
+
# Without this a broken sync stops regeneration silently: GitHub only notifies whoever last touched the cron, and
195
+
# no release waits on this workflow. Skipped on manual dispatch so ad-hoc triggers don't spam the channel.
Copy file name to clipboardExpand all lines: .rules.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -82,11 +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]`
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
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
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
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 — then records its`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, and apify-docs bumps `components/version.yaml` in a follow-up `[skip ci]` commit, so a deploy can publish new content under the old stamp. A moved value proves the spec changed; an unchanged value proves nothing
87
+
-Recording is unconditional; the nightly workflow keeps it honest by committing nothing unless the models changed. A local `generate-models` that only moves that line should be dropped, not committed alone. `generate-models-from-file` leaves the line alone, so models from a candidate spec must not be committed
88
+
- In CI, the `Regenerate models` workflow (`on_schedule_regenerate_models.yaml`) runs nightly at 02:00 UTCand 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". Retitle the `chore:`PR to `fix:`/`feat:` when the diff is user-facing, so it lands in the changelog and triggers a release
89
+
- The gate is the **generated models**, not the spec version — which moves on rebuilds regardless of client impact, and doesn't reliably move when the content does
90
90
- Manual regeneration is also possible from the GitHub Actions UI (`Regenerate models` workflow)
0 commit comments