From bc3ef5846431529de126c64c7646b38b9dde5c3c Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 11 Sep 2026 11:24:12 -0400 Subject: [PATCH] docs: agree on public API changes before implementing them --- AGENTS.md | 6 ++++++ CONTRIBUTING.md | 12 ++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f2529ea --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,6 @@ +# Agent Instructions + +- Read and follow [CONTRIBUTING.md](./CONTRIBUTING.md) before contributing to the SDK. It covers local development, running the example, CI-aligned checks, and the Rails package. +- Read and follow [RELEASING.md](./RELEASING.md) when adding changesets or working on publishing. +- Before adding or changing public API, follow "Public API changes" in [CONTRIBUTING.md](./CONTRIBUTING.md): the API shape must be agreed on the issue first. For SDK design guidance, read https://posthog.com/handbook/engineering/sdks/guidelines.md. +- Keep shared development guidance in `CONTRIBUTING.md` and release guidance in `RELEASING.md` rather than duplicating it here. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c3bf6e..cd162f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,18 @@ The public API snapshot covers both `posthog-ruby` and `posthog-rails`. If you i bundle exec rake public_api:generate ``` +## Public API changes + +Public API is hard to change once it ships, so agree on it before writing the implementation. Our [SDK guidelines](https://posthog.com/handbook/engineering/sdks/guidelines) explain how we design it. + +- 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 first. At this stage, context is more useful to us than code. +- Wait for a maintainer to agree on the API shape on the issue before implementing it. +- 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. +- AI agents: stop and ask before implementing a public API change that hasn't been agreed on the issue. + +A diff in `public_api_snapshot.txt` (see "CI-aligned checks" above) means your change touches public API. + ## Rails package The `posthog-rails` package has its own package-specific guide in [posthog-rails/CONTRIBUTING.md](posthog-rails/CONTRIBUTING.md).