v0.4.0

Contributing to Podium

How to contribute to Podium today. License, DCO, code of conduct.

Thanks for your interest in Podium.

Ways to contribute

  • Open an issue or start a discussion. Questions, bug reports, missing use cases, and concrete suggestions are all welcome. File an issue or start a discussion.
  • Submit a pull request. For non-trivial changes, please open an issue or discussion first so we can align on direction before you invest time in code.
  • Fix typos and broken links. Small documentation PRs are welcome anytime. Keep them focused.

For what's most useful to contribute today, see Implementation status.

Development setup

Prerequisites

  • Go 1.26 or later for the registry, CLI, and MCP server.
  • Python 3.10 or later for the podium-py SDK.
  • Node.js 20 or later for the @lennylabs/podium-sdk TypeScript SDK.
  • GNU make.

Build

shell
go build ./...

This builds every Go binary in the module (podium, podium-server, podium-mcp) into the Go build cache. Pass -o to write a specific binary to disk:

shell
go build -o bin/podium ./cmd/podium

Test

The Go suite runs in a single lane:

shell
make test

The full suite completes in one to two minutes on a recent laptop. Two opt-in lanes exercise real external services:

shell
make test-live           # Postgres and MinIO, started by `make services-up`.
make test-live-external  # Managed vector backends and embedding providers.

make test-live points the suite at the local docker-compose services and sets PODIUM_POSTGRES_DSN and the PODIUM_S3_* variables. make test-live-external sets PODIUM_LIVE_EXTERNAL=1 and forwards the per-service credentials from the environment. Each live test self-skips with a reason when its service is not configured. The Sigstore live checks stay manual; RELEASING.md records the variables to set before a signing-path release.

The SDK suites run independently:

shell
cd sdks/podium-py
pip install -e .
pip install pytest
pytest

cd sdks/podium-ts
npm install
npm test

Spec coverage and matrix audit

Tests carry a // Spec: §X.Y annotation that ties them to a spec section. The reporters under tools/ use those annotations:

shell
make speccov         # Spec-section coverage report.
make speccov-drift   # Fail if any test cites a missing section.
make matrix-audit    # Audit per-cell coverage of the documented spec matrices.
make coverage-gate   # Run the full CI gate locally (lint + drift + matrix + coverage).

make help lists every target.

A new test should carry a // Spec: annotation pointing to the spec section it exercises. Multi-cite is supported via Spec: §A / §B — note. Tests that have no spec correspondence use Spec: n/a — <reason>.

Documentation site

The documentation pages live in docs/ as markdown. The site that publishes them is generated by the TypeScript package in site/, which needs Node 20 or later.

shell
make docs-dev     # Rebuild on change and serve on http://localhost:4321/podium/
make docs-check   # Run the validation gate and the generator's tests
make docs-build   # Write the full site into site/dist

make docs-check reports an unresolvable link, a missing anchor, an unknown frontmatter key, and an image with no alt text, among other rules. The same checks run on any pull request that touches docs/, site/, or README.md. site/README.md documents the frontmatter keys, the callout syntax, and how to add a component.

Ground rules

  • License. Podium is MIT-licensed. Contributions are accepted under the same license.
  • Developer Certificate of Origin (DCO). Sign off each commit with git commit -s. No separate CLA.
  • Code of Conduct. Participation is subject to the Contributor Covenant.
  • Security issues. Do not file public issues for vulnerabilities. See the security policy for the disclosure process.

Getting help