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 |
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/spec-test@1.0.0 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 |
Introduce a contributing guide to assist developers in contributing to the Outpost SDKs.