llm-gateway/CONTRIBUTING.md

Contributing

Thanks for helping improve LLM Gateway.

The project values changes that make AI routing safer, easier to understand, easier to run, and easier to verify.

Contribution Areas

Good first contribution areas:

• documentation improvements
• bridge health checks
• provider adapters
• tests for subscription discovery
• dashboard clarity
• metrics and observability
• local-first routing policies
• security hardening

Larger contribution areas:

• new subscription bridge implementations
• policy engine improvements
• context receipt support
• reproducible run records
• MCP tool support
• database-backed audit trails

Ground Rules

• Do not commit credentials, OAuth files, cookies, private keys, database dumps, training data, logs with account data, private hostnames, or local machine paths.
• Prefer explicit configuration through environment variables.
• Keep default behavior local and safe.
• Make operational state honest. Use unknown, config_needed, or degraded when the gateway lacks evidence.
• Add tests when changing routing, bridge behavior, authentication, or request validation.
• Keep public examples generic.

Development Setup

npm install
npm run dev

Build:

npm run build

Test:

npm test

Secret scan:

gitleaks dir . --redact

Branch And Commit Style

Use a short branch name:

feature/subscription-health
fix/bridge-timeout
docs/quickstart

Use concise commit messages:

docs: add subscription bridge guide
fix(gateway): handle bridge timeout
test(subscriptions): cover join flow

Pull Request Checklist

Before opening a pull request, confirm:

• the change has a clear purpose
• public docs do not contain private infrastructure details
• build or tests were run
• bridge or API changes have a smoke test
• no credentials or account artifacts are included
• the pull request explains risk and rollback if relevant

Adding A Provider

Provider changes should include:

• a descriptor or provider config entry
• health behavior
• model IDs
• expected auth state
• local test notes
• error handling for missing CLI or unreachable bridge

Adding Documentation

Documentation should be direct, testable, and operator-friendly.

Prefer:

• commands that can be copied
• exact endpoint names
• clear expected results
• explicit security notes

Avoid:

• private URLs
• screenshots with account data
• local usernames or paths
• long fake credentials
• claims that are not supported by code

Maintainer Review

The maintainer may ask for:

• smaller pull requests
• additional tests
• simpler defaults
• stronger security posture
• clearer docs
• removal of private data

That review is part of keeping the gateway usable and publishable.