Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(mobile): require physical-device pr screenshots (#125572)

Chris Volzer829db6c9161a
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 792ade45235b..d0beae1275b3 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -13,6 +13,7 @@
<!-- For each change a person can notice, say what they will now see or do differently, not only the code path that does it. Mark the rest as mechanical so a reviewer knows nothing user-visible is hiding in it. -->
<!-- If there are frontend changes, please include screenshots. For a new interaction that one screenshot cannot show, a short GIF or animated WebP of the flow can replace the after screenshot. -->
+<!-- For frontend or user-facing changes under products/mobile/, before-and-after screenshots from physical iOS AND Android devices are required. Prefer multiple screen sizes. See products/mobile/AGENTS.md for capture and device coverage requirements. -->
<!-- PostHog employees: `hogli pr:upload-image <file>` uploads to the public PostHog/pr-assets repo and prints markdown to paste here. Never upload customer data, secrets, or internal info. -->
<!-- If a reference design was involved, include a link to the relevant Figma frame! -->
diff --git a/products/mobile/AGENTS.md b/products/mobile/AGENTS.md
index 6053ebc7a836..956c2c9e1da3 100644
--- a/products/mobile/AGENTS.md
+++ b/products/mobile/AGENTS.md
@@ -7,3 +7,26 @@ The app is its own pnpm workspace. Run every command from `products/mobile`.
- Invoke `/requesting-mobile-releases` before you create or edit a file under `releases/requests/`, and when a change touches `package.json`, `pnpm-lock.yaml`, `app.config.ts`, `eas.json`, `plugins/`, `targets/`, `modules/` or any `expo-*` or `react-native-*` dependency. It decides whether the change can ship over the air or needs a native release. A merged request publishes without a human gate.
- Invoke `/running-mobile-demo-flows` before you report a change to a screen, navigation, the demo fixtures or a flow as done. CI does not run the simulator flows, so the local run is the only UI check.
+
+## Pull request screenshots
+
+Every PR touching `products/mobile/` must include before-and-after screenshots from **both a physical iOS device and a physical Android device** if it changes frontend or user-facing behavior.
+This includes layout, styling, copy, navigation, interactions, and loading, empty, or error states.
+Capture both platforms even when the intended change is platform-specific, so reviewers can check the other platform for regressions.
+PRs with no frontend or user-facing impact should explain why screenshots do not apply.
+
+1. Run the base revision on each device and capture the affected screens and states before the change.
+2. Run the proposed revision on the same devices and capture the same screens and states, with matching data and orientation.
+ For a new screen, capture the existing entry point or flow as the before state.
+3. Attach the screenshot pairs to the PR description, labeled **iOS before**, **iOS after**, **Android before**, and **Android after**.
+ Record each device's model, OS version, and screen size alongside its screenshots.
+4. Prefer repeating the comparison on multiple screen sizes per platform, including smaller and larger phones where available.
+ Record the sizes tested so reviewers can see the coverage.
+
+Use device screenshots or available device tooling, such as Argent or Device Hub, with the physical device selected explicitly.
+Simulator, emulator, and web screenshots are useful during development but do not satisfy the physical-device requirement.
+A recording may supplement the screenshot pairs to show an interaction.
+Before uploading screenshots, read the [repository PR guidance](../../AGENTS.md#pr-descriptions) for public asset requirements.
+Use demo or invented data.
+
+If a physical device or either platform's screenshots are unavailable, state the missing coverage in the PR and arrange device testing before marking it ready for review.