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.
| ```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` |
There was a problem hiding this comment.
| 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
| 3. **Validate the specification**: | ||
| ```bash | ||
| # Use Speakeasy CLI to validate (if installed) | ||
| speakeasy validate -s docs/apis/openapi.yaml |
There was a problem hiding this comment.
➜ outpost git:(chore/sdk-generation-docs) ✗ speakeasy validate -s docs/apis/openapi.yaml
unknown shorthand flag: 's' in -s| # Or use the spec-sdk-tests validation | ||
| cd spec-sdk-tests | ||
| npm run validate:spec |
There was a problem hiding this comment.
➜ outpost git:(chore/sdk-generation-docs) ✗ cd spec-sdk-tests
➜ spec-sdk-tests git:(chore/sdk-generation-docs) ✗ npm run validate:spec
> @outpost/[email protected] validate:spec
> swagger-cli validate ../apis/openapi.yaml
Error opening file "/Users/alexluong/git/hub/hookdeck/outpost/apis/openapi.yaml"
ENOENT: no such file or directory, open '/Users/alexluong/git/hub/hookdeck/outpost/apis/openapi.yaml'| 4. **Commit and push**: | ||
| ```bash | ||
| git add docs/apis/openapi.yaml | ||
| git commit -m "Update OpenAPI spec: <description>" |
There was a problem hiding this comment.
I don't think this commit message conform to conventional commit convention which we follow
| - 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?
|
|
||
| ### 1. Go SDK (`sdks/outpost-go/`) | ||
| - **Location**: `sdks/outpost-go/` | ||
| - **Package**: `github.com/hookdeck/outpost-go` |
There was a problem hiding this comment.
this is incorrect, the package is github.com/hookdeck/outpost/sdks/outpost-go
| 4. **Start Outpost locally** (in a separate terminal): | ||
| ```bash | ||
| # Using Docker Compose | ||
| docker-compose -f build/dev/compose.yml up | ||
|
|
||
| # Or run directly with Go | ||
| go run cmd/outpost/main.go | ||
|
|
||
| # Verify it's running | ||
| curl http://localhost:8000/healthz | ||
| ``` |
There was a problem hiding this comment.
we should encourage folks to use make up, or what I do personally is
make up/deps
make up/outpost
# also test infra to run test suite locally
make up/test
We can also refer people to the contributing/getting-started.md guide
| go run cmd/outpost/main.go | ||
|
|
||
| # Verify it's running | ||
| curl http://localhost:8000/healthz |
There was a problem hiding this comment.
default port is 3333, also /api/v1/healthz
| ```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.
| go run cmd/outpost/main.go | ||
|
|
||
| # Verify Outpost is running | ||
| curl http://localhost:3333/healthz |
There was a problem hiding this comment.
| # Start Outpost locally for testing | ||
| docker-compose -f build/dev/compose.yml up | ||
| # OR | ||
| go run cmd/outpost/main.go |
|
@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.
Introduce a contributing guide to assist developers in contributing to the Outpost SDKs.