Add contributing guide for Outpost SDKs #552
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a comprehensive contributing guide for Outpost SDKs, documenting the complete workflow for updating, generating, testing, and publishing the Go, Python, and TypeScript SDKs. The guide emphasizes that SDK generation is a manual process and highlights critical testing considerations, particularly around the TypeScript SDK's local file dependency race condition.
Key Changes:
- Establishes documentation for the SDK generation and publishing workflows
- Details versioning guidelines (BETA and post-BETA strategies)
- Documents critical testing procedures to avoid race conditions with the TypeScript SDK
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
contributing/sdks.md
Outdated
| ```bash | ||
| cd spec-sdk-tests && rm -rf node_modules && npm install | ||
| ``` | ||
| 3. Is Outpost running locally? Check `http://localhost:3333/healthz` |
There was a problem hiding this comment.
Port mismatch: Line 273 shows Outpost running on port 8000 (curl http://localhost:8000/healthz), but this troubleshooting step references port 3333. The port should be consistent throughout the document.
| 3. Is Outpost running locally? Check `http://localhost:3333/healthz` | |
| 3. Is Outpost running locally? Check `http://localhost:8000/healthz` |
contributing/sdks.md
Outdated
| go run cmd/outpost/main.go | ||
|
|
||
| # Verify Outpost is running | ||
| curl http://localhost:3333/healthz |
There was a problem hiding this comment.
Port mismatch: This references port 3333, but line 273 shows Outpost running on port 8000. The port should be consistent throughout the document.
| curl http://localhost:3333/healthz | |
| curl http://localhost:8000/healthz |
alexluong
left a comment
alexluong
left a comment
There was a problem hiding this comment.
Got a few issues here as I tried to follow the steps locally
Overall the guide makes sense. I wonder if a short TLDR in the beginning to give the full flow before going in-depth would be helpful.
flow:
- GHA to initiate SpeakEasy CI to generate new SDKs
-> PRs -> merge
-> GHA using SpeakEasy CI to publish SDK
| - Select the branch (typically `main`) | ||
| - **Optional inputs**: | ||
| - `force`: Force generation even if no OpenAPI changes detected (default: false) | ||
| - `set_version`: Set a specific SDK version (e.g., `1.2.3`). Leave empty to keep current version |
There was a problem hiding this comment.
- Should the version start with
vor not?v1.2.3vs1.2.3 - Do we try to keep the SDK version matching Outpost version?
|
@alexluong - any chance you could edit the changes you know are wrong and leave anything you need clarification on? |
|
|
||
| Outpost SDKs are automatically generated from the [OpenAPI specification](../docs/apis/openapi.yaml) using [Speakeasy](https://www.speakeasyapi.dev/). The SDK generation, testing, and publishing process is managed through GitHub Actions workflows, but requires manual triggering and careful coordination to ensure quality. | ||
|
|
||
| **Key Point**: SDK generation is a **manual process** that requires explicit workflow triggering and version management. This is intentional to maintain control over releases. |
There was a problem hiding this comment.
Why is this? I mean, what would be wrong with releasing one version per each merged PR?
There was a problem hiding this comment.
The current phrasing is misleading - it's not that manual control is intentionally better, it's that we just haven't fully thought through what complete automation looks like and gotten around to implementing it.
We could instead:
- Automatically trigger SDK generation when Outpost releases are published (we already have the release.yml workflow)
- Only generate SDKs if
docs/apis/openapi.yamlhas changed since the last release - Let Speakeasy handle versioning automatically (it detects breaking vs non-breaking changes), testing and releasing
Right now we don't auto-generate or version the OpenAPI spec.
Related: there's presently no checking that the OpenAPI spec is correct and we have had some bugs raised. However, there is the start of a test suite that generates the TS SDK, and makes calls to the API, then the TS SDK validates the responses.
There was a problem hiding this comment.
That's actually great news, @leggetter. I've created this issue to make sure we don't forget: #559.
|
@leggetter sorry for the delay, I fixed all the issues identified, just had a question left and we can merge this PR whenever! |
Introduce a contributing guide to assist developers in contributing to the Outpost SDKs.