Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
55 lines (35 loc) · 3.15 KB

CONTRIBUTING.md

File metadata and controls

55 lines (35 loc) · 3.15 KB
Raw

Contributing

Thanks for your interest in improving the PostHog Rust SDK.

Commit signing

This repo requires all commits to be signed. To configure commit signing, see the PostHog handbook. Set commit.gpgsign to true in your git config so that every commit is signed, not only the ones you sign by hand.

Prerequisites

  • Rust 1.78.0 or newer for the SDK library (see Cargo.toml). Development and test dependencies may require newer Rust.

CI checks the minimum with both async and blocking clients, including capture-v1, using the checked-in lockfile. Dependency ranges still allow customers on newer Rust to use newer releases. When updating the lockfile, keep the library's dependency graph compatible with Rust 1.78 and rerun both MSRV checks; dependency metadata alone can understate the required compiler version.

Development commands

From the repository root:

cargo build --verbose
cargo test --verbose
cargo test --verbose --features e2e-test --no-default-features
cargo fmt -- --check
cargo clippy -- -D warnings
scripts/check-public-api.sh

check-public-api.sh compares the public API in your working tree with the checked-in api/public-api.txt snapshot. If an API change is intentional, run scripts/check-public-api.sh --update and review the snapshot diff. It requires:

cargo install cargo-public-api --version 0.52.0 --locked
rustup toolchain install nightly-2026-06-12 --profile minimal

Running examples

See examples/README.md for the available example programs and the environment variables they use.

Public API changes

Public API is hard to change once it ships, so agree on it before writing the implementation. Our SDK guidelines explain how we design it.

This section is for external contributors. PostHog maintainers (members of the PostHog GitHub org) agree on API shape in the PR itself, so they don't need a separate issue.

  • Before you start: if you need something the SDK doesn't support and it would add or change a public option, method, or type, open an issue describing your use case. Wait for a maintainer to agree on the API shape there before you implement it. Context is more useful to us than code at this stage.
  • Already specified? If a published sdk-spec defines the API, that's the agreement, so you don't need an issue.
  • Already have a PR open? Don't stop or rewrite it. Call out the public API change at the top of the PR description, and link or open an issue so we can discuss the shape there.
  • Check first whether an existing option or hook, such as before_send, already covers the use case. We avoid offering two ways to do the same thing.
  • If a reviewer suggests a different API on your PR, confirm it with them before re-implementing. Treat it as a question, not an instruction.

A diff in api/public-api.txt (see "Development commands" above) means your change touches public API.

Pull requests

Please make sure the relevant build, test, formatting, and clippy checks pass before opening a PR.