Skip to content

chore(skills): snapshot the 3.x Android, 3.x iOS and 5.x Flutter flag, error tracking and logs pages - #471

Closed
turnipdabeets wants to merge 3 commits into
chore/legacy-docs-snapshotsfrom
chore/legacy-android-flag-snapshots
Closed

turnipdabeets wants to merge 3 commits into
chore/legacy-docs-snapshotsfrom
chore/legacy-android-flag-snapshots

Conversation

@turnipdabeets

@turnipdabeets turnipdabeets commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Problem

The Android feature flag variants install posthog-android 3.x, but they read two pages live: feature-flags/adding-feature-flag-code.md (a group shared_docs entry) and feature-flags/installation/android.md. When posthog-android 4.0 ships, PostHog/posthog.com#21808 changes the Android snippet on the first page to PostHog.onFeatureFlags { loaded -> … }, which 3.x doesn't have. The second page renders the in-app onboarding, which moves to projectToken and posthog-android:4.+. The next build after that would hand 3.x installs 4.0-only code.

The same goes for iOS (PostHog/posthog.com#21807, merged in from #478), and for the Android error tracking, logs and upload mappings pages and the Flutter feature flag, error tracking and logs install pages. Those reuse the product analytics onboarding steps that the posthog-android 4.0 and posthog_flutter 6.0 onboarding changes rewrite, so they must stay at 3.x/5.x.

Stacked on #454, which adds the legacy snapshots and repo-file docs_urls. Like #454, it must be released before those pages change.

Changes

  • context/docs-snapshots/legacy/feature-flags/: copies of both pages, taken 2026-11-04 while they still describe 3.x (apiKey, posthog-android:3.+, the onFeatureFlags config option). They sit in a subfolder so the install page keeps its android.md reference name next to the library page snapshot. The README lists them.
  • Also snapshotted, with every config that read them live pointed at the copy (standalone, integration-v2 step and omnibus skills):
    • iOS (from chore: snapshot the iOS 3.x feature flag, error tracking and logs docs #478): feature-flags/ios.md, error-tracking/ios.md, logs-installation/ios.md, and the iOS flag variants read the flag code page snapshot.
    • Android: error-tracking/android.md, logs-installation/android.md, upload-mappings/android.md (also read by the Flutter upload variant). Taken 2026-11-06 (posthog-android:3.+, apiKey).
    • Flutter: feature-flags/flutter.md, error-tracking/flutter.md, logs-installation/flutter.md. Taken 2026-11-06 (posthog_flutter: ^5.x).
  • A variant's shared_docs entry now replaces the group's entry that writes the same reference file, in place. Before, both were fetched and the later one overwrote the file. No variant declares shared_docs today, so nothing else changes.
  • feature-flags and integration-v2/feature-flags-step: the android variant reads both snapshots. All other variants still read the flag code page live.
  • omnibus/instrument-feature-flags: reads the Android install page snapshot. It keeps the live flag code page, because that one skill covers every platform. The 4.0 Android snippet on that page has a note for 3.x readers.

Test plan

  • pnpm test: 228 passed. New tests cover the in-place replacement and that both Android flag variants get the snapshot instead of the live page. Every snapshotted page is in the list of pages no config may fetch live.
  • Generated feature-flags-android, integration-v2-feature-flags-step-android and omnibus-instrument-feature-flags. Both Android skills' adding-feature-flag-code.md reference is byte-identical to the snapshot. The snapshots match the live pages today, so the output is unchanged until the pages move.

LLM context

Written with Claude Code (Opus 5.5) at the request of the posthog-android maintainer.

🤖 Generated with Claude Code

The Android flag variants install posthog-android 3.x, but read the
live flag code page and the Android flag install page, which move to
4.0 on release day. They now read 2026-11-04 snapshots of both pages.

The flag code page is a group shared doc, so a variant's own
shared_docs entry now replaces the group's one with the same file name.
Every other variant still reads it live.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets turnipdabeets self-assigned this Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown

🧙 Wizard CI

Run the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands:

Test all apps:

  • /wizard-ci all

Test all apps in a directory:

  • /wizard-ci ai-observability
  • /wizard-ci basic-integration
  • /wizard-ci feature-flags
  • /wizard-ci mcp-analytics
  • /wizard-ci replay-vision
  • /wizard-ci revenue
  • /wizard-ci self-driving
  • /wizard-ci warehouse
  • /wizard-ci warehouse-seeded

Test an individual app:

  • /wizard-ci ai-observability/anthropic
  • /wizard-ci ai-observability/google-adk
  • /wizard-ci ai-observability/groq
Show more apps
  • /wizard-ci ai-observability/manual-capture
  • /wizard-ci ai-observability/openai
  • /wizard-ci ai-observability/openai-agents
  • /wizard-ci ai-observability/opentelemetry
  • /wizard-ci ai-observability/vercel-ai
  • /wizard-ci basic-integration/android
  • /wizard-ci basic-integration/angular
  • /wizard-ci basic-integration/astro
  • /wizard-ci basic-integration/django
  • /wizard-ci basic-integration/fastapi
  • /wizard-ci basic-integration/flask
  • /wizard-ci basic-integration/flutter
  • /wizard-ci basic-integration/javascript-node
  • /wizard-ci basic-integration/javascript-web
  • /wizard-ci basic-integration/laravel
  • /wizard-ci basic-integration/next-js
  • /wizard-ci basic-integration/nuxt
  • /wizard-ci basic-integration/python
  • /wizard-ci basic-integration/rails
  • /wizard-ci basic-integration/react-native
  • /wizard-ci basic-integration/react-router
  • /wizard-ci basic-integration/sveltekit
  • /wizard-ci basic-integration/swift
  • /wizard-ci basic-integration/tanstack-router
  • /wizard-ci basic-integration/tanstack-start
  • /wizard-ci basic-integration/vue
  • /wizard-ci feature-flags/django
  • /wizard-ci feature-flags/next-js
  • /wizard-ci mcp-analytics/custom-dispatcher
  • /wizard-ci mcp-analytics/typescript-sdk
  • /wizard-ci replay-vision/javascript-node
  • /wizard-ci replay-vision/next-js
  • /wizard-ci replay-vision/react-vite
  • /wizard-ci revenue/stripe
  • /wizard-ci self-driving/astro
  • /wizard-ci self-driving/fastapi
  • /wizard-ci self-driving/nuxt
  • /wizard-ci self-driving/react-router
  • /wizard-ci self-driving/sveltekit
  • /wizard-ci warehouse/monorepo-env
  • /wizard-ci warehouse/multi-source-next
  • /wizard-ci warehouse/stripe-node
  • /wizard-ci warehouse/zero-source
  • /wizard-ci warehouse-seeded/next-stripe
  • /wizard-ci warehouse-seeded/next-stripe-declined

Test against a wizard branch:

  • /wizard-ci all wizard:my-branch

Add wizard:<branch> to any command above to pin the wizard branch. It defaults to main.

Results will be posted here when complete.

#478)

* chore(skills): snapshot the 3.x iOS flag, error tracking and logs pages

posthog-ios 4.0 moves the iOS install snippets to SPM `from: "4.0.0"` and
drops CocoaPods (posthog.com#21807, posthog#129618), and changes the iOS
section of the flag code page. The iOS variants install 3.x, so they read
copies taken while the pages still describe it.

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

* docs: name the logs snapshot's 3.59.3 pin in the README

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…g, logs and flag pages

The Android error tracking, logs and upload mappings pages and the Flutter
feature flag, error tracking and logs install pages reuse the product
analytics onboarding steps that the posthog-android 4.0 and posthog_flutter
6.0 onboarding changes rewrite. The variants install 3.x/5.x, so they read
copies taken while the pages still describe those majors.
@turnipdabeets turnipdabeets changed the title chore(feature-flags): snapshot the 3.x Android flag pages chore(skills): snapshot the 3.x Android, 3.x iOS and 5.x Flutter flag, error tracking and logs pages Nov 6, 2026
@eli-r-ph

eli-r-ph commented Nov 7, 2026

Copy link
Copy Markdown

This is stacked on #454, which won't land: the Wizard team is replacing that approach. Can you rebase it onto main, or check with Edwin and Vincent how they want the 3.x and 5.x pages kept for legacy installs?

@turnipdabeets

Copy link
Copy Markdown
Contributor Author

This is stacked on #454, which won't land: the Wizard team is replacing that approach. Can you rebase it onto main, or check with Edwin and Vincent how they want the 3.x and 5.x pages kept for legacy installs?

I think this will go away too. Leaving for the @PostHog/team-wizard-docs to reference, merge or close.

@johncwaters johncwaters 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.

LGTM, one med item

Note

Automated review by Glimmervoid, not written by a human. Approved by hand after checking it.

- https://posthog.com/docs/feature-flags/installation/elixir.md
- https://posthog.com/docs/feature-flags/installation/android.md
- https://posthog.com/docs/feature-flags/installation/ios.md
- context/docs-snapshots/legacy/feature-flags/android.md

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.

Note

Automated review. Not written by a human.

[code/consistency] MEDIUM

This skill now reads the 3.x Android and iOS install snapshots, but its group shared_docs (line 8) still reads the live adding-feature-flag-code.md. After the SDK releases it pairs 3.x install steps with 4.0 flag code, which is what the standalone and integration-v2 variants were changed to avoid.

The description says that's fine for Android because the 4.0 snippet has a note for 3.x readers. Does posthog.com#21807 add the same kind of note for iOS (the 3.x reloadFeatureFlags block and didReceiveFeatureFlags fallback the README mentions)? If not, the omnibus probably needs the snapshot too. Nothing tests this skill's flag code page either way.

@hpouillot hpouillot 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.

🤖 Automated review.

Status first: #454 is closed and main has neither context/docs-snapshots/ nor repo-file docs_urls, so this branch can't land as is (as noted above). The notes below are meant as input for whichever approach replaces it, since the same gaps would come back.

[P2] The Swift error tracking step loses its error tracking reference. integration-v2/error-tracking-step swift lists legacy/error-tracking/ios.md and legacy/ios.md. urlToFilename returns the basename for both, so both are written to references/ios.md, and the library page overwrites the 3.x error tracking install page. The collision already existed with the live URL. Renaming one snapshot, or keying references by path, would fix it.

[P2] The Flutter flag variants still pair a pinned install page with live flag code. feature-flags / feature-flags-step flutter read the 5.x install snapshot but inherit the live adding-feature-flag-code.md. When the posthog_flutter 6.0 docs change rewrites the Flutter snippet, 5.x installs get 6.0 code. The new it.each only covers android and ios, so no test would catch it. The fix is the same override the android variant got. (The omnibus case is already covered in the existing thread.)

Optional: fail the build on duplicate reference file names. mergeSharedDocs handles one case of basename collisions. A check in the generator that throws when two docs map to the same file would have caught the Swift case above and would catch the next one, whatever snapshot mechanism ends up on main.

Scope: I reviewed the generator change, the swift, Flutter and omnibus configs and the new tests at 6350639c. I spot-checked the snapshot contents and ran no tests.

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.

4 participants