From 3dc4653c51cb249d814ce3918bc39246783e5d99 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 11 Sep 2026 11:24:17 -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..c1e0a91 --- /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 development setup, the example app, CI-aligned checks, and pull requests. +- Read and follow [RELEASING.md](./RELEASING.md) when adding change intents (`pnpm change`) 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 cd71cbd..85c9fbe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,18 @@ curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar php phpcs.phar --standard=phpcs.xml --extensions=php . ``` +## 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. + +`composer api:update` regenerates `api/public-api.json`, and CI runs `composer api:check` to catch an outdated snapshot. A diff in that file means your change touches public API. + ## Pull requests Please follow the existing project conventions and include tests when you change behavior.