Add contributing guide for Outpost SDKs #552

leggetter · 2025-10-28T12:21:14Z

Introduce a contributing guide to assist developers in contributing to the Outpost SDKs.

vercel · 2025-10-28T12:21:20Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
outpost-docs	Ready	Preview	Comment	Oct 28, 2025 0:21am
outpost-website	Ready	Preview	Comment	Oct 28, 2025 0:21am

Copilot

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.

Copilot · 2025-10-28T12:21:42Z

contributing/sdks.md

+   ```bash
+   cd spec-sdk-tests && rm -rf node_modules && npm install
+   ```
+3. Is Outpost running locally? Check `http://localhost:3333/healthz`


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.

Suggested change

3. Is Outpost running locally? Check `http://localhost:3333/healthz`

3. Is Outpost running locally? Check `http://localhost:8000/healthz`

http://localhost:3333/api/v1/healthz

Copilot · 2025-10-28T12:21:42Z

contributing/sdks.md

+go run cmd/outpost/main.go
+
+# Verify Outpost is running
+curl http://localhost:3333/healthz


Port mismatch: This references port 3333, but line 273 shows Outpost running on port 8000. The port should be consistent throughout the document.

Suggested change

curl http://localhost:3333/healthz

curl http://localhost:8000/healthz

alexluong

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

alexluong · 2025-10-31T16:39:59Z

contributing/sdks.md

+3. **Validate the specification**:
+   ```bash
+   # Use Speakeasy CLI to validate (if installed)
+   speakeasy validate -s docs/apis/openapi.yaml


➜ outpost git:(chore/sdk-generation-docs) ✗ speakeasy validate -s docs/apis/openapi.yaml unknown shorthand flag: 's' in -s

alexluong · 2025-10-31T16:40:22Z

contributing/sdks.md

+   # Or use the spec-sdk-tests validation
+   cd spec-sdk-tests
+   npm run validate:spec


➜ 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'

alexluong · 2025-10-31T16:40:54Z

contributing/sdks.md

+4. **Commit and push**:
+   ```bash
+   git add docs/apis/openapi.yaml
+   git commit -m "Update OpenAPI spec: <description>"


I don't think this commit message conform to conventional commit convention which we follow

alexluong · 2025-10-31T16:42:05Z

contributing/sdks.md

+   - 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


Should the version start with v or not? v1.2.3 vs 1.2.3

Do we try to keep the SDK version matching Outpost version?

alexluong · 2025-10-31T16:44:17Z

contributing/sdks.md

+
+### 1. Go SDK (`sdks/outpost-go/`)
+- **Location**: `sdks/outpost-go/`
+- **Package**: `github.com/hookdeck/outpost-go`


this is incorrect, the package is github.com/hookdeck/outpost/sdks/outpost-go

alexluong · 2025-10-31T16:47:52Z

contributing/sdks.md

+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
+   ```


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

alexluong · 2025-10-31T16:48:19Z

contributing/sdks.md

+   go run cmd/outpost/main.go
+
+   # Verify it's running
+   curl http://localhost:8000/healthz


default port is 3333, also /api/v1/healthz

alexluong · 2025-10-31T16:51:04Z

contributing/sdks.md

+   ```bash
+   cd spec-sdk-tests && rm -rf node_modules && npm install
+   ```
+3. Is Outpost running locally? Check `http://localhost:3333/healthz`


http://localhost:3333/api/v1/healthz

alexluong · 2025-10-31T16:52:04Z

contributing/sdks.md

+go run cmd/outpost/main.go
+
+# Verify Outpost is running
+curl http://localhost:3333/healthz


http://localhost:3333/api/v1/healthz

alexluong · 2025-10-31T16:52:12Z

contributing/sdks.md

+# Start Outpost locally for testing
+docker-compose -f build/dev/compose.yml up
+# OR
+go run cmd/outpost/main.go


leggetter · 2025-11-06T00:32:20Z

@alexluong - any chance you could edit the changes you know are wrong and leave anything you need clarification on?

fmvilas · 2025-11-07T15:55:22Z

contributing/sdks.md

+
+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.


Why is this? I mean, what would be wrong with releasing one version per each merged PR?

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.yaml has 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.

That's actually great news, @leggetter. I've created this issue to make sure we don't forget: #559.

chore: Add contributing guide for Outpost SDKs

0f121ee

Copilot AI review requested due to automatic review settings October 28, 2025 12:21

vercel bot deployed to Preview – outpost-website October 28, 2025 12:21 View deployment

Copilot AI reviewed Oct 28, 2025

View reviewed changes

vercel bot deployed to Preview – outpost-docs October 28, 2025 12:21 View deployment

leggetter requested a review from alexluong October 31, 2025 14:04

alexluong reviewed Oct 31, 2025

View reviewed changes

fmvilas added this to Outpost Releases Nov 7, 2025

fmvilas moved this to Todo in Outpost Releases Nov 7, 2025

fmvilas moved this from Todo to In Review in Outpost Releases Nov 7, 2025

fmvilas reviewed Nov 7, 2025

View reviewed changes

fmvilas mentioned this pull request Nov 11, 2025

Automatically generate SDKs #559

Open

	3. Is Outpost running locally? Check `http://localhost:3333/healthz`
	3. Is Outpost running locally? Check `http://localhost:8000/healthz`

	curl http://localhost:3333/healthz
	curl http://localhost:8000/healthz


		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.

Add contributing guide for Outpost SDKs #552

Are you sure you want to change the base?

Add contributing guide for Outpost SDKs #552

Uh oh!

Conversation

leggetter commented Oct 28, 2025

Uh oh!

vercel bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 28, 2025

Choose a reason for hiding this comment

Uh oh!

alexluong left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leggetter commented Nov 6, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Oct 28, 2025 •

edited

Loading