Skip to content

docs: exempt maintainers from the public API issue-first rule #976

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
turnipdabeets merged 1 commit into from
Sep 21, 2026
+5 −4
Merged

docs: exempt maintainers from the public API issue-first rule #976

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Guidance for coding agents working in `posthog-python`.
- This repository contains the PostHog Python SDK, published as `posthog`.
- The main runtime package is `posthog/`; tests live under `posthog/test/`.
- The project uses `uv` for local development. See `CONTRIBUTING.md` for setup.
- 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.
- Public API changes (a diff in `references/public_api_snapshot.txt`): if the author is a PostHog maintainer (git email ends in `@posthog.com`), the PR is the discussion, so don't open or suggest an issue. Otherwise, follow "Public API changes" in [CONTRIBUTING.md](./CONTRIBUTING.md): if there's no agreed issue, stop and tell the user. If a PR already exists, add a public-API note to its description and draft an issue body for the user to post. Never open an issue yourself. For SDK design guidance, read https://posthog.com/handbook/engineering/sdks/guidelines.md.

@greptile-apps greptile-apps Bot Sep 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Unreliable maintainer identification

The exemption treats an author as a maintainer when their git email ends in @posthog.com, but Client Libraries maintainers commonly use GitHub noreply or personal addresses, while git email is locally configurable. This can send maintainers through the external-contributor workflow and let non-maintainers bypass it. Use authenticated GitHub team membership or explicit PR metadata instead.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: AGENTS.md
Line: 10

Comment:
**Unreliable maintainer identification**

The exemption treats an author as a maintainer when their git email ends in `@posthog.com`, but Client Libraries maintainers commonly use GitHub noreply or personal addresses, while git email is locally configurable. This can send maintainers through the external-contributor workflow and let non-maintainers bypass it. Use authenticated GitHub team membership or explicit PR metadata instead.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

@greptile-apps greptile-apps Bot Sep 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Snapshot trigger misses changes

Defining a public API change as a diff in the snapshot misses source changes until that file is explicitly regenerated. An agent can add or change an exported option, method, or type, see no snapshot diff, and skip this policy until CI reports the stale snapshot. Define the trigger as changing public API in source and describe the snapshot diff only as a detection signal.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: AGENTS.md
Line: 10

Comment:
**Snapshot trigger misses changes**

Defining a public API change as a diff in the snapshot misses source changes until that file is explicitly regenerated. An agent can add or change an exported option, method, or type, see no snapshot diff, and skip this policy until CI reports the stale snapshot. Define the trigger as changing public API in source and describe the snapshot diff only as a detection signal.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

@dustinbyrne dustinbyrne Sep 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor (non-blocking): Could we treat @posthog.com as one signal of maintainer status rather than the exclusive test? A confirmed Client Libraries maintainer can use a GitHub noreply address, which sends them through the external-contributor issue-first flow despite the exemption in CONTRIBUTING.md. Consider accepting independently confirmed maintainer identity too.

- Keep edits targeted and follow existing patterns. Prefer adding or updating tests near the behavior you change.

## Capture protocol (`capture_mode`)
Expand Down
7 changes: 4 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,10 +53,11 @@ This lets you test SDK changes fully locally inside the PostHog app stack. It ma

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.
This section is for external contributors. PostHog Client Libraries maintainers 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 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.
- AI agents: stop and ask before implementing a public API change that hasn't been agreed on the issue.

`make public_api_snapshot` regenerates `references/public_api_snapshot.txt`, and CI runs `make public_api_check` to catch an outdated snapshot. A diff in that file means your change touches public API.
Loading