Skip to content

docs: sort the Android 4.0.0 migration guide by when you make each change - #973

Merged
turnipdabeets merged 19 commits into
chore/v4-remove-deprecatedfrom
docs/migration-guide-structure
Nov 13, 2026
Merged

turnipdabeets merged 19 commits into
chore/v4-remove-deprecatedfrom
docs/migration-guide-structure

Conversation

@gewenyu99

@gewenyu99 gewenyu99 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor
  • Fill missing docstring details from migration guides and old docs.
  • Make migration guides easier to read.

…ange

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gewenyu99
gewenyu99 requested a review from a team as a code owner November 12, 2026 17:00
@gewenyu99 gewenyu99 self-assigned this Nov 12, 2026
@veria-ai

veria-ai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
The posthog.com Android SDK page redirects to this reference once
4.0.0 ships, so its setup, how-to, and configuration sections now live
in docs/getting-started.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gewenyu99
gewenyu99 marked this pull request as draft November 12, 2026 17:36
gewenyu99 and others added 2 commits November 12, 2026 12:42
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 2eeb772)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit f7650a7)
gewenyu99 and others added 3 commits November 12, 2026 12:51
… other page has

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

posthog-android Compliance Report

Date: 2026-11-13T18:45:20.174685+00:00
Duration: 474998ms

✅ All Tests Passed!

232/232 tests passed


Capture_V1 Tests

✅ 105/105 tests passed

View Details
Test Status Duration
Endpoint And Method.Targets V1 Endpoint ✅ 337ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 31ms
Required Headers.Has Authorization Bearer Header ✅ 29ms
Required Headers.Has Content Type Json ✅ 27ms
Required Headers.Has Posthog Sdk Info Format ✅ 27ms
Required Headers.Has Posthog Attempt Header ✅ 28ms
Required Headers.Has Posthog Request Id ✅ 22ms
Required Headers.Has Posthog Request Timestamp ✅ 26ms
Required Headers.Has User Agent ✅ 21ms
Body Format.Body Has Created At And Batch ✅ 23ms
Body Format.No Api Key In Body ✅ 24ms
Body Format.No Sent At In Body ✅ 23ms
Event Format.Event Has Required Root Fields ✅ 22ms
Event Format.Event Uuid Is Valid ✅ 19ms
Event Format.Event Timestamp Is Rfc3339 ✅ 20ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 22ms
Event Format.Distinct Id Is String ✅ 22ms
Event Format.Distinct Id At Root Not Properties ✅ 25ms
Event Format.Custom Properties Preserved ✅ 27ms
Event Format.Set Properties Preserved ✅ 24ms
Event Format.Set Once Properties Preserved ✅ 26ms
Event Format.Groups Properties Preserved ✅ 22ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 26ms
Event Format.Event Has Required Root Fields Batch ✅ 32ms
Event Format.Event Uuid Is Valid Batch ✅ 28ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 29ms
Event Format.Distinct Id Is String Batch ✅ 32ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 31ms
Event Format.Custom Properties Preserved Batch ✅ 29ms
Event Format.Set Properties Preserved Batch ✅ 30ms
Event Format.Set Once Properties Preserved Batch ✅ 32ms
Event Format.Groups Properties Preserved Batch ✅ 27ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 35ms
Batch Behavior.Multiple Events In Single Batch ✅ 53ms
Batch Behavior.Batch Envelope Smoke ✅ 45ms
Batch Behavior.Flush With No Events Sends Nothing ✅ 15ms
Batch Behavior.Flush At Triggers Batch ✅ 1022ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 19ms
Deduplication.Generates Unique Uuids ✅ 40ms
Deduplication.Different Events Same Content Different Uuids ✅ 21ms
Deduplication.Preserves Uuid On Retry ✅ 7015ms
Deduplication.Preserves Timestamp On Retry ✅ 7015ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7020ms
Deduplication.No Duplicate Events In Batch ✅ 25ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 15ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 12026ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 7012ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2024ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 7015ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 16ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 21ms
Response Format Validation.Success No Retry After When All Ok ✅ 20ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 2008ms
Response Format Validation.Success No Retry After When Drop Only ✅ 19ms
Response Format Validation.Response Echoes Request Id ✅ 15ms
Retry Behavior.Retries On 408 ✅ 7014ms
Retry Behavior.Retries On 500 ✅ 7015ms
Retry Behavior.Retries On 503 ✅ 7024ms
Retry Behavior.Retries On 504 ✅ 7015ms
Retry Behavior.Retries On 404 ✅ 6016ms
Retry Behavior.Retries On 429 ✅ 6014ms
Retry Behavior.Retries On 502 ✅ 7016ms
Retry Behavior.Retryable Errors Have Retry After ✅ 4012ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 10025ms
Retry Behavior.Does Not Retry On 400 ✅ 4016ms
Retry Behavior.Does Not Retry On 401 ✅ 4017ms
Retry Behavior.Does Not Retry On 402 ✅ 4017ms
Retry Behavior.Does Not Retry On 413 ✅ 4016ms
Retry Behavior.Does Not Retry On 415 ✅ 4019ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 4014ms
Retry Behavior.Implements Backoff ✅ 14026ms
Partial Batch Handling.Handles 200 Full Success ✅ 2018ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3028ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3019ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3022ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 7012ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 7014ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 7015ms
Partial Batch Handling.Partial Retry Preserves Uuids ✅ 7014ms
Partial Batch Handling.Partial Retry Attempt Header Increments ✅ 7015ms
Partial Batch Handling.Partial Retry Request Id Preserved ✅ 7015ms
Partial Batch Handling.Respects Retry After On Partial ✅ 7023ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3021ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3026ms
Compression.Sends Gzip Content Encoding ✅ 14ms
Compression.No Content Encoding When Disabled ✅ 15ms
Compression.Compressed Body Is Decompressible ✅ 18ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 4015ms
Event Options.Cookieless Mode Override ✅ 14ms
Event Options.Disable Skew Correction Override ✅ 12ms
Event Options.Process Person Profile Override ✅ 11ms
Event Options.Product Tour Id Override ✅ 10ms
Event Options.Unset Options Omitted ✅ 10ms
Event Options.Options Override In Batch ✅ 17ms
Event Options.Unknown Option Passes Through ✅ 13ms
Event Options.Option Value Is Not Converted ✅ 14ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 15ms
Event Options.Option Wins Over Legacy Property ✅ 16ms
Event Options.Legacy Property Fills Unset Option ✅ 17ms
Event Options.Null Option Falls Back To Legacy Property ✅ 18ms
Property Layers.Caller Property Beats Registered Property ✅ 19ms
Property Layers.Before Send Runs Last ✅ 21ms
Fail Open.Empty Api Key Sends Nothing ✅ 3013ms
Fail Open.Personal Api Key Sends Nothing ✅ 3013ms
Geoip And Historical Migration.Historical Migration Absent By Default ✅ 13ms

Capture_Ai_V1 Tests

✅ 110/110 tests passed

View Details
Test Status Duration
Endpoint And Method.Targets V1 Endpoint ✅ 14ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 12ms
Endpoint And Method.Capture Does Not Reroute Ai Named Events ✅ 12ms
Endpoint And Method.Capture Ai Does Not Reroute Non Ai Events ✅ 12ms
Lane Isolation.Failing Ai Lane Does Not Delay Analytics ✅ 7023ms
Required Headers.Has Authorization Bearer Header ✅ 15ms
Required Headers.Has Content Type Json ✅ 15ms
Required Headers.Has Posthog Sdk Info Format ✅ 13ms
Required Headers.Has Posthog Attempt Header ✅ 14ms
Required Headers.Has Posthog Request Id ✅ 15ms
Required Headers.Has Posthog Request Timestamp ✅ 15ms
Required Headers.Has User Agent ✅ 18ms
Body Format.Body Has Created At And Batch ✅ 22ms
Body Format.No Api Key In Body ✅ 19ms
Body Format.No Sent At In Body ✅ 21ms
Event Format.Event Has Required Root Fields ✅ 15ms
Event Format.Event Uuid Is Valid ✅ 15ms
Event Format.Event Timestamp Is Rfc3339 ✅ 21ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 20ms
Event Format.Distinct Id Is String ✅ 16ms
Event Format.Distinct Id At Root Not Properties ✅ 10ms
Event Format.Custom Properties Preserved ✅ 16ms
Event Format.Set Properties Preserved ✅ 15ms
Event Format.Set Once Properties Preserved ✅ 15ms
Event Format.Groups Properties Preserved ✅ 13ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 14ms
Event Format.Event Has Required Root Fields Batch ✅ 16ms
Event Format.Event Uuid Is Valid Batch ✅ 15ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 18ms
Event Format.Distinct Id Is String Batch ✅ 20ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 24ms
Event Format.Custom Properties Preserved Batch ✅ 23ms
Event Format.Set Properties Preserved Batch ✅ 27ms
Event Format.Set Once Properties Preserved Batch ✅ 21ms
Event Format.Groups Properties Preserved Batch ✅ 25ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 20ms
Batch Behavior.Multiple Events In Single Batch ✅ 23ms
Batch Behavior.Batch Envelope Smoke ✅ 23ms
Batch Behavior.Flush At Triggers Batch ✅ 1014ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 14ms
Deduplication.Generates Unique Uuids ✅ 24ms
Deduplication.Different Events Same Content Different Uuids ✅ 17ms
Deduplication.Preserves Uuid On Retry ✅ 7013ms
Deduplication.Preserves Timestamp On Retry ✅ 7015ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7015ms
Deduplication.No Duplicate Events In Batch ✅ 21ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 15ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 12015ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 7015ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2021ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 7020ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 12ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 16ms
Response Format Validation.Success No Retry After When All Ok ✅ 16ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 2008ms
Response Format Validation.Success No Retry After When Drop Only ✅ 17ms
Response Format Validation.Response Echoes Request Id ✅ 12ms
Retry Behavior.Retries On 408 ✅ 7013ms
Retry Behavior.Retries On 500 ✅ 7014ms
Retry Behavior.Retries On 503 ✅ 7020ms
Retry Behavior.Retries On 504 ✅ 7014ms
Retry Behavior.Retries On 404 ✅ 7014ms
Retry Behavior.Retries On 429 ✅ 7014ms
Retry Behavior.Retries On 502 ✅ 6010ms
Retry Behavior.Retryable Errors Have Retry After ✅ 4011ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 10014ms
Retry Behavior.Does Not Retry On 400 ✅ 4013ms
Retry Behavior.Does Not Retry On 401 ✅ 4016ms
Retry Behavior.Does Not Retry On 402 ✅ 4014ms
Retry Behavior.Does Not Retry On 413 ✅ 4015ms
Retry Behavior.Does Not Retry On 415 ✅ 4017ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 4016ms
Retry Behavior.Implements Backoff ✅ 14014ms
Partial Batch Handling.Handles 200 Full Success ✅ 2014ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3019ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3020ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3018ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 7014ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 7013ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 7013ms
Partial Batch Handling.Partial Retry Preserves Uuids ✅ 7014ms
Partial Batch Handling.Partial Retry Attempt Header Increments ✅ 7011ms
Partial Batch Handling.Partial Retry Request Id Preserved ✅ 7010ms
Partial Batch Handling.Respects Retry After On Partial ✅ 7016ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3019ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3025ms
Compression.Sends Gzip Content Encoding ✅ 14ms
Compression.No Content Encoding When Disabled ✅ 16ms
Compression.Compressed Body Is Decompressible ✅ 12ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 4012ms
Event Options.Cookieless Mode Override ✅ 12ms
Event Options.Disable Skew Correction Override ✅ 10ms
Event Options.Process Person Profile Override ✅ 14ms
Event Options.Product Tour Id Override ✅ 14ms
Event Options.Unset Options Omitted ✅ 13ms
Event Options.Options Override In Batch ✅ 18ms
Event Options.Unknown Option Passes Through ✅ 11ms
Event Options.Option Value Is Not Converted ✅ 14ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 13ms
Event Options.Option Wins Over Legacy Property ✅ 12ms
Event Options.Legacy Property Fills Unset Option ✅ 11ms
Event Options.Null Option Falls Back To Legacy Property ✅ 14ms
Event Size.Event Over Ceiling Is Not Sent ✅ 3316ms
Event Size.Over Ceiling Drop Is Reported Or Logged Without Content ✅ 2051ms
Event Size.Batches Close Before Byte Target ✅ 6070ms
Geoip And Historical Migration.Historical Migration Absent By Default ✅ 15ms
Property Layers.Caller Property Beats Registered Property ✅ 12ms
Property Layers.Before Send Runs Last ✅ 14ms
Fail Open.Empty Api Key Sends Nothing ✅ 1008ms
Fail Open.Personal Api Key Sends Nothing ✅ 1008ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 26ms
Request Payload.Flags Request Uses V2 Query Param ✅ 17ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 15ms
Request Payload.Flags Request Omits Authorization Header ✅ 15ms
Request Payload.Token In Flags Body Matches Init ✅ 15ms
Request Payload.Groups Round Trip ✅ 22ms
Request Payload.Groups Default To Empty Object ✅ 20ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 19ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 16ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 16ms
Request Lifecycle.No Flags Request On Init Alone ✅ 8ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 16ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 28ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 17ms
Retry Behavior.Retries Flags On 502 ✅ 315ms
Retry Behavior.Retries Flags On 504 ✅ 319ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 14ms

@gewenyu99 gewenyu99 mentioned this pull request Nov 12, 2026
3 tasks done
@gewenyu99
gewenyu99 marked this pull request as ready for review November 12, 2026 18:49

@posthog posthog Bot left a comment

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.

PostHog Review · Standard · reviewed f65ba63: 1 Should fix.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

Comment thread bin/docs_scripts/generate_markdown.py Resolved
gewenyu99 and others added 5 commits November 13, 2026 10:57
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	.changeset/server-keep-on-feature-flags.md
#	MIGRATION.md
#	bin/docs_scripts/generate_markdown.py
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…es and semicolons

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Move "Upgrade your dependencies" and "Upgrade posthog-server" to During:
  both come down to declaring posthog-android 4.0.0.
- Give the PostHogStateless break its own During section and checklist item.
- Drop "Check timestamps and IDs": nothing in it changes but the request ID
  header, which the proxy section covers.
- Say what staying on capture costs for $ai_* events, scope the intro to
  analytics and AI events, and say why follow ups can wait.
- disableGeoIp exists now (main's #971), so the guide no longer says there's
  no GeoIP setting. Name the real remote config path.
- Regenerate references/posthog-android-migration.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread MIGRATION.md Resolved
Comment thread bin/docs_scripts/generate_markdown.py Resolved
turnipdabeets and others added 4 commits November 13, 2026 13:32
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… categories

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets
turnipdabeets merged commit b8e5ca7 into chore/v4-remove-deprecated Nov 13, 2026
12 checks passed
@turnipdabeets
turnipdabeets deleted the docs/migration-guide-structure branch November 13, 2026 19:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants