Sync SDK with latest documented Fizzy API surface#35
Conversation
There was a problem hiding this comment.
Pull request overview
This PR establishes a formal framework for tracking Fizzy's API documentation as upstream inputs to the SDK spec maintenance workflow. It creates infrastructure to keep the Smithy specification aligned with changes to upstream API docs, routes, controllers, and views in the Fizzy repository.
Changes:
- Adds a new
spec/README.mdthat documents the spec layout, grounding model, and maintenance conventions - Updates
spec/api-provenance.jsonandgo/pkg/fizzy/api-provenance.jsonto track split API doc paths alongside existing routes, controllers, and views tracking - Improves the
make sync-statustarget to display API-doc and app-surface changes from upstream instead of just commit drift, with better error handling and authentication checks - Adds "Syncing to Upstream Fizzy" section to
CONTRIBUTING.mdwith recommended workflow steps - Updates
AGENTS.mdto prepend upstream source review to the development workflow and adds a detailed "Upstream Reference Sources" section
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| spec/README.md | New documentation explaining the spec directory structure, grounding model against upstream sources, and maintenance conventions |
| spec/api-provenance.json | Added api_docs_index and api_docs_sections path tracking to formally declare API docs as upstream sources |
| go/pkg/fizzy/api-provenance.json | Mirrors the changes to spec/api-provenance.json to maintain provenance sync |
| Makefile | Enhanced sync-status target to filter for API-doc and app-surface changes with improved error handling and authentication validation |
| CONTRIBUTING.md | Added new section documenting the recommended workflow for syncing to upstream Fizzy changes |
| AGENTS.md | Updated development workflow to prioritize reviewing upstream sources and added dedicated "Upstream Reference Sources" section |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
robzolkos
changed the title
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 43 out of 107 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
7 issues found across 104 files (changes from recent commits).
Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed. cubic prioritises the most important files to review.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="swift/Sources/Fizzy/Generated/Services/CardsService.swift">
<violation number="1" location="swift/Sources/Fizzy/Generated/Services/CardsService.swift:175">
P2: Array-style query filters (`...[]`) are implemented as single `String` values, so multi-value filtering cannot be represented correctly.</violation>
</file>
<file name="swift/Sources/FizzyGenerator/Utilities.swift">
<violation number="1" location="swift/Sources/FizzyGenerator/Utilities.swift:14">
P2: Strip only a trailing `[]` marker instead of removing all `[]` substrings globally.</violation>
</file>
<file name="go/pkg/fizzy/webhooks_service.go">
<violation number="1" location="go/pkg/fizzy/webhooks_service.go:48">
P3: Update the doc comment to describe the correct resource; this method returns webhook deliveries, not webhooks.
(Based on your team's feedback about deriving generated Go service doc comments from the actual service resource/action.) [FEEDBACK_USED]</violation>
</file>
<file name="go/pkg/fizzy/boards_service.go">
<violation number="1" location="go/pkg/fizzy/boards_service.go:42">
P3: Update the method comment to describe `ListBoardAccesses` correctly; it currently says it returns boards, which is misleading for this exported API.</violation>
</file>
<file name="spec/fizzy.smithy">
<violation number="1" location="spec/fizzy.smithy:1392">
P2: The `ListActivities` operation is tagged `@tags(["Cards"])` but should be `@tags(["Activities"])` to match its section and the inventory in AGENTS.md. This will cause the operation to be mis-grouped in generated OpenAPI output and downstream SDK docs.</violation>
</file>
<file name="go/pkg/fizzy/users_service.go">
<violation number="1" location="go/pkg/fizzy/users_service.go:23">
P3: Update the doc comment to describe creating a user data export; it currently states this method creates a user.</violation>
<violation number="2" location="go/pkg/fizzy/users_service.go:64">
P3: Fix the doc comment to indicate this method returns a user data export, not a user.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
|
Fixed — addressed the cubic-identified generator/docs issues: corrected Go service doc comments, fixed Swift repeated [] query filters and trailing [] name normalization, and retagged ListActivities under Activities. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 108 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
1 issue found across 5 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="kotlin/generator/build.gradle.kts">
<violation number="1" location="kotlin/generator/build.gradle.kts:12">
P1: This module now targets Java 25, but repository CI runs Kotlin jobs on Java 17, causing generator/conformance builds to fail.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
|
Fixed — set the Kotlin generator and conformance JVM targets back to Java 17 so they match repository CI, and make check now passes. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 46 out of 110 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Summary
Sync the SDK and spec to the latest documented upstream Fizzy API so the generated clients stay aligned with the public Rails API surface and response payloads. This brings the Smithy source of truth up to date, regenerates downstream artifacts, and closes drift that had accumulated between the SDK and canonical upstream docs/routes/controllers/views/models.
Changes
ListCardsquery modeling to match the current upstream filtersboard_ids[]Notes