From 24174f0d4de0d980c2becf24476612f7244264aa Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 10:54:11 +0000 Subject: [PATCH 1/5] ci: review pull requests against the API, the JS client and the Python SDK `.github/review-references.yaml` names apify-core, apify-client-js and apify-sdk-python as the repositories the apify-factory review compares a pull request with, and what to compare in each. The stub pins the ai-developer branch that drafts the feature while it is evaluated. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017ocuAL43YR6VPaBRrRfBbL --- .github/review-references.yaml | 50 +++++++++++++++++++++++++++ .github/workflows/factory_review.yaml | 5 +++ 2 files changed, 55 insertions(+) create mode 100644 .github/review-references.yaml diff --git a/.github/review-references.yaml b/.github/review-references.yaml new file mode 100644 index 00000000..cb432630 --- /dev/null +++ b/.github/review-references.yaml @@ -0,0 +1,50 @@ +# Cross-repository references for the apify-factory review (apify/ai-developer, `review-references`). +# A change to this client is right when it matches what the Apify API does, keeps parity with the JS +# client it mirrors, and does not break the Python SDK built on it, so the reviewer gets those three +# repositories as source trees next to the pull request and compares. Read from the default branch, +# never from the pull request; gathered only for a pull request by a human member of the +# organization, on a branch of this repository. +version: 1 + +instructions: | + This repository is the Python client for the Apify API, a port of the JS client that the Python SDK + builds on. For every behaviour the pull request adds or changes, check three things: that it matches + what the API actually does, that it matches what the JS client does for the same operation, and that + every place the Python SDK uses the changed code still works. Only what a user of the client can + observe counts: method names and parameters, defaults, the request sent (path, method, query, body, + headers), how the response is parsed and what is returned, retries, timeouts, pagination, and the + exceptions raised. A difference from the JS client that the Python code or docs mark as intended is + not a finding. Back every finding with the reference file and line. + +references: + - repository: apify/apify-core + ref: latest-release + paths: + - src/api/** + - src/packages/** + instructions: | + The API the client calls. Entry points: the route handlers under `src/api/src/routes//` + (actors, actor_runs, actor_builds, actor_tasks, datasets, key_value_stores, request_queues, + webhooks, webhook_dispatches, logs, users, store); a resource's published fields in + `PUBLISHED_*_FIELDS` in `src/packages/-server/src//.server.ts`; a list + endpoint's own fields in `API_PUBLISHED_*_LIST_FIELDS` next to its route; constants and limits in + `src/packages/consts/`. Compare the request the client builds with what the handler accepts + (paths, methods, query and body parameters, defaults, limits) and what the client expects back with + what the handler returns (field names and types, pagination, status codes, error types). + - repository: apify/apify-client-js + instructions: | + The reference implementation this client mirrors: every resource client under + `src/apify_client/_resource_clients/` has a counterpart in `src/resource_clients/.ts` + and `_collection.ts`, the request pipeline (retries, timeouts, errors) lives in + `src/http_clients/` and `src/base/`, request-body compression in `src/http_compressors/`. Compare + the changed Python method with the JS method of the same name: parameters and defaults, the + request it sends, how it parses the response, what it returns, and how it handles errors. + - repository: apify/apify-sdk-python + instructions: | + The main consumer of this client. It uses the client from `src/apify/storage_clients/_apify/` + (dataset, key-value store and request queue clients built on this client's storage clients and + `_api_client_creation.py`), `src/apify/_actor.py`, `_charging.py`, `_proxy_configuration.py`, + `_webhook.py`, `_child_runs.py` and `_configuration.py`. Search for every use of the method, + parameter, class, return type or exception the pull request changes and check that each call + site still works: a renamed or removed parameter, a changed default, a changed return shape or a + new exception breaks the SDK. diff --git a/.github/workflows/factory_review.yaml b/.github/workflows/factory_review.yaml index 233d945e..45af7cb2 100644 --- a/.github/workflows/factory_review.yaml +++ b/.github/workflows/factory_review.yaml @@ -3,6 +3,9 @@ name: apify-factory review (AI review, and auto-approval) # Calls the apify-factory review and auto-approval pipeline (apify/ai-developer, wired up in # apify/workflows). Approvals additionally need the repository's `factory_auto_approve` custom # property set to true. +# +# `.github/review-references.yaml` names the repositories the reviewer compares a pull request with +# (the API, the JS client, the Python SDK); the pipeline reads it from the base branch. on: # Taken from the default branch, never from the pull request, so a pull request cannot rewrite # its own review pipeline. Pull request code is never checked out or executed. @@ -25,6 +28,8 @@ jobs: # Paths never auto-approved here, on top of the pipeline's defaults. Proposed from the # repository's layout when this workflow was added; edit them like any other code. with: + # The draft of the cross-repository references, under evaluation. Back to `main` once it lands. + ai-developer-ref: claude/review-references policy: | { "denyGlobs": [ From 8a97b8face87b37c19c2e678563f6eea753499d3 Mon Sep 17 00:00:00 2001 From: Josef Prochazka Date: Tue, 3 Nov 2026 13:13:56 +0100 Subject: [PATCH 2/5] Simplify the instructions --- .github/review-references.yaml | 39 +++++++-------------------- .github/workflows/factory_review.yaml | 3 --- 2 files changed, 9 insertions(+), 33 deletions(-) diff --git a/.github/review-references.yaml b/.github/review-references.yaml index cb432630..e7f730e3 100644 --- a/.github/review-references.yaml +++ b/.github/review-references.yaml @@ -1,20 +1,13 @@ # Cross-repository references for the apify-factory review (apify/ai-developer, `review-references`). -# A change to this client is right when it matches what the Apify API does, keeps parity with the JS -# client it mirrors, and does not break the Python SDK built on it, so the reviewer gets those three -# repositories as source trees next to the pull request and compares. Read from the default branch, -# never from the pull request; gathered only for a pull request by a human member of the -# organization, on a branch of this repository. version: 1 instructions: | This repository is the Python client for the Apify API, a port of the JS client that the Python SDK builds on. For every behaviour the pull request adds or changes, check three things: that it matches - what the API actually does, that it matches what the JS client does for the same operation, and that - every place the Python SDK uses the changed code still works. Only what a user of the client can - observe counts: method names and parameters, defaults, the request sent (path, method, query, body, - headers), how the response is parsed and what is returned, retries, timeouts, pagination, and the - exceptions raised. A difference from the JS client that the Python code or docs mark as intended is - not a finding. Back every finding with the reference file and line. + what the API actually does, that it matches what the JS client does for the same operation (ignore + differences caused by different language idioms and style), and that every place the Python SDK uses + the changed code still works. Back every finding with the reference file and line (create public + github link fixed to a commit you have seen). references: - repository: apify/apify-core @@ -23,28 +16,14 @@ references: - src/api/** - src/packages/** instructions: | - The API the client calls. Entry points: the route handlers under `src/api/src/routes//` - (actors, actor_runs, actor_builds, actor_tasks, datasets, key_value_stores, request_queues, - webhooks, webhook_dispatches, logs, users, store); a resource's published fields in - `PUBLISHED_*_FIELDS` in `src/packages/-server/src//.server.ts`; a list - endpoint's own fields in `API_PUBLISHED_*_LIST_FIELDS` next to its route; constants and limits in - `src/packages/consts/`. Compare the request the client builds with what the handler accepts + The API the client calls. Compare the request the client builds with what the handler accepts (paths, methods, query and body parameters, defaults, limits) and what the client expects back with what the handler returns (field names and types, pagination, status codes, error types). - repository: apify/apify-client-js instructions: | - The reference implementation this client mirrors: every resource client under - `src/apify_client/_resource_clients/` has a counterpart in `src/resource_clients/.ts` - and `_collection.ts`, the request pipeline (retries, timeouts, errors) lives in - `src/http_clients/` and `src/base/`, request-body compression in `src/http_compressors/`. Compare - the changed Python method with the JS method of the same name: parameters and defaults, the - request it sends, how it parses the response, what it returns, and how it handles errors. + The reference implementation this client mirrors. Compare the changed Python methods with the + matching JS methods: parameters and defaults, the request it sends, how it parses the response, + what it returns, and how it handles errors. - repository: apify/apify-sdk-python instructions: | - The main consumer of this client. It uses the client from `src/apify/storage_clients/_apify/` - (dataset, key-value store and request queue clients built on this client's storage clients and - `_api_client_creation.py`), `src/apify/_actor.py`, `_charging.py`, `_proxy_configuration.py`, - `_webhook.py`, `_child_runs.py` and `_configuration.py`. Search for every use of the method, - parameter, class, return type or exception the pull request changes and check that each call - site still works: a renamed or removed parameter, a changed default, a changed return shape or a - new exception breaks the SDK. + The main consumer of this client. Highlight the changes that will require updates to the SDK. diff --git a/.github/workflows/factory_review.yaml b/.github/workflows/factory_review.yaml index 45af7cb2..1ca80ef2 100644 --- a/.github/workflows/factory_review.yaml +++ b/.github/workflows/factory_review.yaml @@ -3,9 +3,6 @@ name: apify-factory review (AI review, and auto-approval) # Calls the apify-factory review and auto-approval pipeline (apify/ai-developer, wired up in # apify/workflows). Approvals additionally need the repository's `factory_auto_approve` custom # property set to true. -# -# `.github/review-references.yaml` names the repositories the reviewer compares a pull request with -# (the API, the JS client, the Python SDK); the pipeline reads it from the base branch. on: # Taken from the default branch, never from the pull request, so a pull request cannot rewrite # its own review pipeline. Pull request code is never checked out or executed. From 83d7722e47a8b2067538a11fec24e1d91e70f9e7 Mon Sep 17 00:00:00 2001 From: Josef Prochazka Date: Tue, 3 Nov 2026 13:25:44 +0100 Subject: [PATCH 3/5] Track develop in reviews --- .github/review-references.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/review-references.yaml b/.github/review-references.yaml index e7f730e3..e8ff2d98 100644 --- a/.github/review-references.yaml +++ b/.github/review-references.yaml @@ -11,7 +11,7 @@ instructions: | references: - repository: apify/apify-core - ref: latest-release + ref: develop paths: - src/api/** - src/packages/** From 865811dace92f91f3853f8f12191438b90b98ec3 Mon Sep 17 00:00:00 2001 From: Josef Prochazka Date: Tue, 3 Nov 2026 15:48:54 +0100 Subject: [PATCH 4/5] Add references to rules.md --- .rules.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.rules.md b/.rules.md index bba36456..fe5af239 100644 --- a/.rules.md +++ b/.rules.md @@ -42,3 +42,6 @@ The OpenAPI spec can lag behind the API and omit fields, and a live response onl - A single resource's fields are in `PUBLISHED_*_FIELDS` in `src/packages/-server/src//.server.ts`. - A list endpoint has its own, usually smaller, `API_PUBLISHED_*_LIST_FIELDS` in `src/api/src/routes//_list.ts`, and often builds each item inline. Don't assume a list item has the same fields as the single resource. + +### Additional context +The code in this repository is based on and integrated with code from other repositories. The most important references are defined in [review references](./.github/review-references.yaml) From f6145e8c683599f45812c5392950b026c08386bb Mon Sep 17 00:00:00 2001 From: Josef Prochazka Date: Tue, 3 Nov 2026 15:50:59 +0100 Subject: [PATCH 5/5] Markdown lint --- .rules.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.rules.md b/.rules.md index fe5af239..31a2c49d 100644 --- a/.rules.md +++ b/.rules.md @@ -44,4 +44,5 @@ The OpenAPI spec can lag behind the API and omit fields, and a live response onl - A list endpoint has its own, usually smaller, `API_PUBLISHED_*_LIST_FIELDS` in `src/api/src/routes//_list.ts`, and often builds each item inline. Don't assume a list item has the same fields as the single resource. ### Additional context + The code in this repository is based on and integrated with code from other repositories. The most important references are defined in [review references](./.github/review-references.yaml)