Contributing

Use this page to contribute code and docs with repository standards. It covers local setup, required checks, and pull-request expectations.

Use this guide when

You are preparing your first pull request to OngoingAI Gateway.
You are changing behavior in auth, proxy, trace, limits, or config code.
You are updating product docs under docs/.

Prerequisites

Go 1.24 (from go.mod)
git and make
Optional: local Postgres for Postgres-backed integration tests

Set up your local environment

Clone the repository and open the project directory.

Bash

git clone https://github.com/ongoingai/gateway.git
cd gateway

Build the gateway binary.
Bash
```
make build
```
Run the full test suite baseline.
Bash
```
make test
```
Run the gateway locally with default config.
Bash
```
make run
```

You should see startup logs with server address and configured providers.

Build and test workflow before a pull request

Create a feature branch from main.

Bash

git checkout main
git pull
git checkout -b BRANCH_NAME

Implement your change and update or add tests.
Format Go files.
Bash
```
make fmt
```
Run focused tests for changed areas first.
Bash
```
go test ./internal/auth/
```
Run full and race checks before opening your pull request.
Bash
```
make test
go test -race ./...
```

Placeholder:

BRANCH_NAME: Short branch name for your change, for example auth-deny-unmapped-routes.

Documentation contribution standards

If behavior changes, docs must change in the same pull request.

Requirements:

Product docs live under docs/ and must use .mdx.
Every page must include title and description frontmatter.
Writing must follow the Google developer documentation style guide.
Code and command examples should be copy/paste ready.

Frontmatter template:

YAML

---
title: Page title
description: One to two sentence page summary.
---

If your editor does not preview .mdx files by default:

JSON

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

Pull-request checklist

Scope is clear and focused to one concern when possible.
Security-sensitive paths remain fail-closed.
Tenant boundaries (org_id, workspace_id) remain enforced.
No secrets or raw API keys are logged or persisted.
Behavior changes include tests.
Docs and config examples are updated when behavior changes.
CI checks pass.

Common issues

Tests fail only in Postgres-backed packages

Symptom: Postgres integration tests fail or cannot connect.
Cause: Missing or invalid ONGOINGAI_TEST_POSTGRES_DSN.
Fix: Set a reachable Postgres DSN and rerun targeted tests: go test ./internal/configstore ./internal/trace.

Docs page preview looks unformatted in editor

Symptom: .mdx content does not render as markdown preview.
Cause: Editor does not map .mdx to markdown preview mode.
Fix: Add the files.associations setting shown above.

Pull request lacks required behavior coverage

Symptom: Review requests more tests or docs updates.
Cause: Behavior changed without corresponding tests or documentation.
Fix: Add regression tests and update affected docs in the same pull request.

Next steps

PreviousChangelog & Release Notes NextSecurity