Merge remote-tracking branch 'origin/main' into feat/android-exception-steps

# Conflicts:
#	posthog-samples/posthog-android-sample/src/main/AndroidManifest.xml
#	posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt
#	posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/NormalActivity.kt

Author: ioannisj

.changeset/hygiene.json

@@ -1,5 +1,6 @@
 {
     "transitiveReExports": {
-        "posthog": ["posthog-android", "posthog-server"]
+        "posthog": ["posthog-android", "posthog-server", "posthog-android-surveys-compose"],
+        "posthog-android": ["posthog-android-surveys-compose"]
     }
 }

.github/pull_request_template.md

@@ -19,3 +19,29 @@
 - [ ] Ran `pnpm changeset` to generate a changeset file
 
 <!-- For more details check RELEASING.md -->
+
+## 🤖 Agent context
+
+<!-- Fill this section if an agent co-authored or authored this PR. Remove it for fully human-authored PRs. -->
+
+<!-- Autonomy — keep one of the two options on the line below:
+     - "Human-driven (agent-assisted)" when a person directed the work — assign that person as the PR assignee (the DRI).
+     - "Fully autonomous" when no human drove it; leave the PR unassigned for the owning team to triage. -->
+
+**Autonomy:** Human-driven (agent-assisted) — or — Fully autonomous
+
+<!-- Keep this short: 1-3 short paragraphs or a handful of bullets — not an exhaustive log. Include:
+     - tools/agent used and link to session. List the agent and tool names used, but do not include tool call results.
+     - decisions made along the way (what was tried, rejected, chosen, and why)
+     - anything else that helps reviewers
+     Write reviewer-facing prose. Do not paste user prompts verbatim — paraphrase the intent in your own words.
+     DO NOT INCLUDE sensitive data that may have been shared in an agent session.
+-->
+<!-- Rules for agent-authored PRs:
+     - When a human directed the work, the PR must be attributable to that person, even if agent-assisted.
+     - If a human directed this work, assign them as the PR assignee (the DRI) — actually set the assignee, don't just name them here. Leave a PR unassigned only when it is fully autonomous with no human driver (set Autonomy to "Fully autonomous").
+     - Do not add a human Co-authored-by just for the sake of attribution — if no human was involved in the changes, own it as agent-authored.
+     - Agent-authored PRs always require human review — do not self-merge or auto-approve.
+     - Do NOT claim manual testing you haven't done.
+     - GitHub PR descriptions render markdown, not fixed-width text. Do not hard-wrap prose at a column width or use space-aligned tables — use real markdown tables, headings, and fenced code blocks, and let GitHub flow the text.
+-->

.github/workflows/build.yml

@@ -4,32 +4,41 @@ on:
     branches:
       - main
   pull_request:
-    paths-ignore:
-      - "**/*.md"
 
 permissions:
   contents: read
-
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 jobs:
+  detect-markdown-only:
+    uses: PostHog/.github/.github/workflows/detect-markdown-only.yml@ec25337d9fae0100622cbfea1bd5bd88284ac10b
+    permissions:
+      pull-requests: read
+
   build:
+    needs: detect-markdown-only
     name: Build Job
     runs-on: ubuntu-latest
 
     steps:
+      - name: Complete markdown-only PR check
+        if: needs.detect-markdown-only.outputs.markdown_only == 'true'
+        run: echo "Only Markdown files changed; no additional work is required for this check."
       - name: Git checkout
+        if: needs.detect-markdown-only.outputs.markdown_only != 'true'
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: 'Set up Java 17'
+        if: needs.detect-markdown-only.outputs.markdown_only != 'true'
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
           java-version: '17'
           distribution: 'temurin'
 
       - name: Cache Gradle packages
+        if: needs.detect-markdown-only.outputs.markdown_only != 'true'
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: |
@@ -40,7 +49,9 @@ jobs:
             ${{ runner.os }}-gradle-
 
       - name: Make compile
+        if: needs.detect-markdown-only.outputs.markdown_only != 'true'
         run: make compile
 
       - name: Make stop
+        if: needs.detect-markdown-only.outputs.markdown_only != 'true'
         run: make stop

.github/workflows/codeql.yml

@@ -28,13 +28,13 @@ jobs:
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@87557b9c84dde89fdd9b10e88954ac2f4248e463 # v4.36.1
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
           queries: security-and-quality
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@87557b9c84dde89fdd9b10e88954ac2f4248e463 # v4.36.1
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           category: '/language:${{matrix.language}}'

.github/workflows/gradle-wrapper-validation.yml

@@ -15,4 +15,4 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: gradle/actions/wrapper-validation@50e97c2cd7a37755bbfafc9c5b7cafaece252f6e # v6.1.0
+      - uses: gradle/actions/wrapper-validation@5e2ebd065dc2488b7a6ad670704656cbbe1e8f60 # v6.1.1

.github/workflows/release.yml

@@ -104,11 +104,13 @@ jobs:
                   # Sync package.json versions back to gradle.properties
                   CORE_VERSION=$(node -p "require('./posthog/package.json').version")
                   ANDROID_VERSION=$(node -p "require('./posthog-android/package.json').version")
+                  SURVEYS_COMPOSE_VERSION=$(node -p "require('./posthog-android-surveys-compose/package.json').version")
                   SERVER_VERSION=$(node -p "require('./posthog-server/package.json').version")
                   PLUGIN_VERSION=$(node -p "require('./posthog-android-gradle-plugin/package.json').version")
 
                   sed -i "s/^coreVersion=.*/coreVersion=$CORE_VERSION/" gradle.properties
                   sed -i "s/^androidVersion=.*/androidVersion=$ANDROID_VERSION/" gradle.properties
+                  sed -i "s/^surveysComposeVersion=.*/surveysComposeVersion=$SURVEYS_COMPOSE_VERSION/" gradle.properties
                   sed -i "s/^serverVersion=.*/serverVersion=$SERVER_VERSION/" gradle.properties
                   sed -i "s/^androidPluginVersion=.*/androidPluginVersion=$PLUGIN_VERSION/" posthog-android-gradle-plugin/gradle.properties
 
@@ -125,7 +127,7 @@ jobs:
             - name: Commit version bump
               id: commit-version-bump
               if: steps.check-changes.outputs.committed == 'true'
-              uses: planetscale/ghcommit-action@25309d8005ac7c3bcd61d3fe19b69e0fe47dbdde # v0.2.20
+              uses: planetscale/ghcommit-action@a6b150b81dca5dd027baa898604418eec9e11465 # v0.2.22
               with:
                 commit_message: "chore: update versions and changelogs [version bump] [skip ci]"
                 repo: ${{ github.repository }}
@@ -214,6 +216,11 @@ jobs:
                       make_dry_target: dryReleaseAndroid
                       make_release_target: releaseAndroid
                       changelog: posthog-android/CHANGELOG.md
+                    - name: posthog-android-surveys-compose
+                      tag_prefix: surveysCompose
+                      make_dry_target: dryReleaseSurveysCompose
+                      make_release_target: releaseSurveysCompose
+                      changelog: posthog-android-surveys-compose/CHANGELOG.md
                     - name: posthog-server
                       tag_prefix: server
                       make_dry_target: dryReleaseServer

AI_POLICY.md

@@ -0,0 +1,45 @@
+# AI contributions policy
+
+PostHog is built with plenty of AI assistance.
+This policy exists because of a growing volume of low-quality, AI-generated contributions that waste maintainer time.
+
+## The standard
+
+**You own what you submit.**
+Understand your code, test it, and be ready to explain why it's correct and how it interacts with the rest of the system (without re-prompting an LLM).
+This is no different from what we'd expect of any contribution; AI makes it easier to skip the work – please don't skip the work.
+
+**Prove it works.**
+Before submitting, please verify the change actually works end-to-end — don't rely on "it compiles" or "tests pass" alone.
+
+Add tests for new behavior, smoke test the change in an example project where applicable, and describe your test strategy in the PR description: what you tested, how you tested it, and what edge cases you considered.
+
+For changes with user-visible UI, include a short demo (screenshot, screen recording, or GIF) of the feature working in the PR description. Ideally you demo more than just the happy path.
+
+PRs that clearly weren't run or tested will be closed under this policy.
+
+**Disclose AI usage.**
+Our [PR template](.github/pull_request_template.md) includes an Agent context section — please use it (most agents will pick it up automatically).
+If an agent co-authored or authored your PR, say so and leave context about the tools and session.
+This helps reviewers calibrate.
+
+**Prefer PRs over AI-generated issues.**
+If AI helped you find a bug, fix it and open a pull request — don't paste the AI's output into an issue.
+Unreviewed, AI-generated bug reports and security disclosures will be closed without response.
+
+**Don't submit unsolicited AI-generated PR reviews.**
+If you didn't write the code and aren't a maintainer, don't point an LLM at someone else's PR and leave its output as a review comment.
+This is generally never helpful.
+
+## What happens when contributions don't meet this bar
+
+- **First time:** We'll close the PR/issue with a link to this policy and a brief explanation.
+- **Two or more closures:** We'll block the account.
+
+## Why we're not anti-AI
+
+We think the best contributions today often involve AI.
+A contributor who uses an LLM to help them understand unfamiliar code, draft a first pass, or catch edge cases they'd miss is probably _more_ productive than someone doing everything by hand.
+The key difference is that they're driving the AI, not the other way around.
+
+If you're new to open-source contributing and want to learn, we're genuinely happy to help — open an issue, ask questions, submit small PRs.

CHANGELOG.md

@@ -6,5 +6,6 @@ Changelogs can be found in the individual packages:
 
 - [posthog](./posthog/CHANGELOG.md)
 - [posthog-android](./posthog-android/CHANGELOG.md)
+- [posthog-android-surveys-compose](./posthog-android-surveys-compose/CHANGELOG.md)
 - [posthog-server](./posthog-server/CHANGELOG.md)
 - [posthog-android-gradle-plugin](./posthog-android-gradle-plugin/CHANGELOG.md)

Makefile

@@ -29,6 +29,9 @@ dryReleaseCore:
 dryReleaseAndroid:
 	./gradlew :posthog-android:publishToMavenLocal
 
+dryReleaseSurveysCompose:
+	./gradlew :posthog-android-surveys-compose:publishToMavenLocal
+
 dryReleaseServer:
 	./gradlew :posthog-server:publishToMavenLocal
 
@@ -44,6 +47,9 @@ releaseCore:
 releaseAndroid:
 	./gradlew :posthog-android:publishToSonatype closeAndReleaseSonatypeStagingRepository
 
+releaseSurveysCompose:
+	./gradlew :posthog-android-surveys-compose:publishToSonatype closeAndReleaseSonatypeStagingRepository
+
 releaseServer:
 	./gradlew :posthog-server:publishToSonatype closeAndReleaseSonatypeStagingRepository
 

README.md

@@ -3,62 +3,28 @@
 | Packages        | Maven Central                                                                                                                                                                                  | Min Version    |
 |-----------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
 | posthog-android | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android) | Android API 21 |
+| posthog-android-surveys-compose | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose) | Android API 23 · `0.x` |
 | posthog (core)  | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog)                 | Java 8         |
 | posthog-server  | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server)                 | Java 8         |
 | posthog-android-gradle-plugin  | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-gradle-plugin/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-gradle-plugin)                 | Java 8         |
 
-# PostHog Android & JVM SDKs
+# PostHog Android and JVM SDKs
 
 This repository contains PostHog's Android and JVM SDKs. PostHog is an open source platform for product analytics, feature flags, session replay, and more.
 
-## Packages
-
-### posthog-android
-
-Full-featured Android SDK with automatic screen tracking, session recording, and Android-specific features.
-
-```kotlin
-implementation("com.posthog:posthog-android:$latestVersion")
-```
-
-**Documentation:** [posthog-android/](./posthog-android/) | **Usage:** [posthog-android/USAGE.md](./posthog-android/USAGE.md)
-
-### posthog (core)
-
-Pure Kotlin/JVM library suitable for environment specific SDK integrations.
-
-```kotlin
-implementation("com.posthog:posthog:$latestVersion")
-```
-
-**Documentation:** [posthog/](./posthog/) | **Usage:** [posthog/USAGE.md](./posthog/USAGE.md)
-
-### posthog-server
-
-Pure Kotlin/JVM library suitable for server integrations.
-
-```kotlin
-implementation("com.posthog:posthog-server:$latestVersion")
-```
-
-**Documentation:** [posthog-server/](./posthog-server/) | **Usage:** [posthog-server/USAGE.md](./posthog-server/USAGE.md)
-
-### posthog-android-gradle-plugin
-
-Gradle plugin suitable for Android-specific features.
-
-```kotlin
-implementation("com.posthog:posthog-android-gradle-plugin:$latestVersion")
-```
+Please see the main [PostHog docs](https://posthog.com/docs).
 
-**Documentation:** [posthog-android-gradle-plugin/](./posthog-android-gradle-plugin/) | **Usage:** [posthog-android-gradle-plugin/USAGE.md](./posthog-android-gradle-plugin/USAGE.md)
+SDK usage examples and code snippets live in the official documentation so they stay up to date.
 
 ## Documentation
 
-Please see the main [PostHog docs](https://posthog.com/docs).
-
-Specifically, the [Android docs](https://posthog.com/docs/libraries/android) details.
+- [Android library docs](https://posthog.com/docs/libraries/android)
+- [Java/JVM library docs](https://posthog.com/docs/libraries/java)
 
 ## Questions?
 
 ### [Check out our community page.](https://posthog.com/posts)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and test instructions.