Read a hill chart's progress updates

Merged
JE
2d ago
+4487-49

Adopts bc3#13620, "Expose hill chart progress updates in the API", into every SDK.

Card: [API→SDK] Expose hill chart progress updates in the API (bc3#13620)
Gap entry: spec/api-gaps/hill-chart-progress-updates.md, now absorbed-in-sdk.

What's added

Modeled from doc/api/sections/hill_charts.md and app/views/api/todosets/hills/ on bc3 master.

  • ListHillChartVersions: GET /todosets/{todosetId}/hills/versions.json, Link-paginated, newest first. HillCharts listVersions (Go HillCharts().ListVersions, Python/Ruby/Rust list_versions).
  • GetHillChartVersion: GET /todosets/{todosetId}/hills/versions/{versionId}. HillCharts getVersion (Go GetVersion, get_version).
  • HillChartVersion: the recording envelope plus the note as rich text (description, description_attachments) and dots.
  • HillChartVersionDot: separate from HillChartDot because its id is null, and url/app_url are absent, once the todolist has been permanently deleted or moved to another project. HillChartDot.id stays required.
  • versions_url on HillChart, present only when the chart has a progress update. It is the last member, so Kotlin's positional constructor order doesn't change.
  • Go wrapper with the usual list options and result (HillChartVersionListOptions, HillChartVersionListResult). Neither operation joins the grouped client; both are recorded under not_grouped.
  • The two route-allowlist entries are deleted. The bc3 pin does not move.

Tests

  • Fixtures: bc3's three documented examples are shared fixtures under spec/fixtures/hill_charts/ (get.json is refreshed to the current example, which carries versions_url). A fourth, version_todolist_gone.json, has a dot with id: null and no URLs. All four are in the fixture manifest, and HillChartVersion and HillChartVersionDot are covered schemas.
  • Conformance: the new conformance/tests/hill_chart_versions.json has 4 cases: list path, read by id with body assertions, a gone todolist's dot decoding, and 404 as not_found. All four pass in all seven runners (Go 332/334, TypeScript 391/393, Ruby 315/334, Python 334/334, Rust 334/334, Kotlin 331/334, Swift 333/334; the skips are the runners' existing declared skips). It has rows in SPEC §19 and Appendix D.
  • Unit tests, each covering the happy path and a 404, with the gone-dot case wherever a decoder is typed:
    • Go: 7 new tests in hill_charts_test.go, including Link-page following and a marshal round trip of the null id.
    • TypeScript: 7 new tests in hill-charts.test.ts, 11/11 in the file.
    • Ruby: 7 new tests, 15/15 in the file.
    • Python: new test_hill_charts_service.py, 9/9, sync and async.
    • Rust: 3 wire tests and 2 error cases in tests/services.rs.
    • Kotlin: HillChartVersionsTest (jvmTest), 5/5.
    • Swift: HillChartVersionTests, 4/4 on macOS.
  • Checks: every per-language drift check passes, as do go-check-wrapper-drift, the grouped-client, operation-assignment and service-inventory parity checks, check-fixture-coverage, validate-api-gaps, doc-constants-check, bc3-route-parity, check-idempotency-parity (union 241 to 243, both reads), check-replay-decoder-parity and Rust guarantees. The pinned operation counts move from 292 to 294, readonly from 138 to 140, and Link-paginated from 62 to 63. I'll post the result of a full local make check in a comment.

Semver impact

Breaking, in the way #1053 and #1057 were. For callers the change is additive: two new methods and an optional field. But Go's generated ClientInterface and ClientWithResponsesInterface gain methods that hand-written mocks must implement, and a trailing field on Go's HillChart structs breaks unkeyed struct literals. Kotlin's HillChart constructor and copy signatures change at the binary level, so consumers need to recompile. MIGRATING.md has an # Unreleased section for this.

Release notes: Breaking Changes and Features. Labels: breaking, enhancement.

Summary by cubic

Adds reading a hill chart's progress updates to every SDK, adopting bc3#13620.

  • Adds ListHillChartVersions (Link-paginated, newest first) and GetHillChartVersion to the HillCharts service (listVersions/getVersion; Go ListVersions/GetVersion), plus the HillChartVersion and HillChartVersionDot shapes and an optional versions_url on HillChart present only when the chart has a progress update.
  • Keeps a separate dot shape because a version dot's id is null once its todolist is deleted or moved to another project; HillChartDot.id stays required. The OpenAPI projection types that nullable id like MyNote.id: TypeScript reads number | null, Python int | None, Go *int64.
  • Exports ListVersionsHillChartOptions from the TypeScript package root, like the other list options, with a public-import type test.
  • Adds conformance tests for both operations across all seven runners and per-SDK unit tests.

Breaking changes

Breaking only for Go code that implements the generated client interfaces (which gain the two methods) and for unkeyed Go struct literals and Kotlin binary consumers due to the trailing versions_url field. MIGRATING.md covers the details.