Merge pull request #54 from martosaur/am-2.0-migration-guide

Author: rafaeelaudibert

.github/workflows/ci.yml

@@ -13,26 +13,21 @@ jobs:
     # This is a complicated set of strategies, but Elixir has a complicated set of supported versions.
     # See https://hexdocs.pm/elixir/compatibility-and-deprecations.html
     # See https://hexdocs.pm/elixir/compatibility-and-deprecations.html#between-elixir-and-erlang-otp
-    #
-    # NOTE: We're intentionally not including Elixir 1.14.x + OTP 23.x
-    # because erlef/setup-beam@v1 doesn't support it.
     strategy:
       matrix:
-        elixir: ["1.14.x", "1.15.x", "1.16.x", "1.17.x", "1.18.x"]
+        elixir: ["1.15.x", "1.16.x", "1.17.x", "1.18.x"]
         otp: ["24.x", "25.x", "26.x", "27.x"]
         exclude:
           # Elixir 1.17 and 1.18 don't support OTP 24
           - elixir: "1.17.x"
             otp: "24.x"
           - elixir: "1.18.x"
             otp: "24.x"
-          # Elixir 1.14, 1.15 and 1.16 don't support OTP 27
+          # Elixir 1.15 and 1.16 don't support OTP 27
           - elixir: "1.15.x"
             otp: "27.x"
           - elixir: "1.16.x"
             otp: "27.x"
-          - elixir: "1.14.x"
-            otp: "27.x"
 
     steps:
       - uses: actions/checkout@v3

CHANGELOG.md

@@ -1,3 +1,23 @@
+## 2.0.0 - 2025-09-30
+
+### Major Release
+
+`posthog-elixir` was fully reworked. Check [migration guide](MIGRATION.md#v1-v2)
+for some tips on how to upgrade.
+
+Huge thanks to community member [@martosaur](https://github.com/martosaur) for contributing this new version.
+
+### What's new
+
+- Elixir v1.15+ required
+- Event capture is now offloaded to background workers with automatic batching
+- [Context](README.md#context) mechanism for easier property propagation
+- [Error Tracking](README.md#error-tracking) support
+- New `PostHog.FeatureFlags` module for working with feature flags
+- [Test mode](`PostHog.Test`) for easier testing
+- Customizable [HTTP client](`PostHog.API.Client`) with Req as the default
+- [Plug integration](`PostHog.Integrations.Plug`) for automatically capturing common HTTP properties
+
 ## 1.1.0 - 2025-07-01
 
 - Expose `capture/2` `b077aba849126c63f1c7a82b6ad9d21945871a4a`
@@ -24,7 +44,7 @@
 
 - Elixir v1.14+ is now a requirement
 - Feature Flags now return a key called `payload` rather than `value` to better align with the other SDKs
-- PostHog now requires you to initialize `PostHog.Application` alongside your supervisor tree. This is required because of our `Cachex` system to properly track your FF usage.
+- PostHog now requires you to initialize `Posthog.Application` alongside your supervisor tree. This is required because of our `Cachex` system to properly track your FF usage.
   - We'll also include local evaluation in the near term, which will also require a GenServer, therefore, requiring us to use a Supervisor.
 - Added `enabled_capture` configuration option to disable PostHog tracking in development/test environments
 - `PostHog.capture` now requires `distinct_id` as a required second argument

MIGRATION.md

@@ -4,11 +4,42 @@ This is a migration guide for all major version bumps
 
 ## v1 -> v2
 
-TODO: New library
+Version 2.0 is a whole new library, so we encourage you to use this upgrade as
+an opportunity to revisit your PostHog usage in your application. Even the root
+level module was renamed from `Posthog` to `PostHog`.
+
+### Configuration
+
+Configuration has been completely reworked. We advise you to remove your
+existing configuration and follow [Getting Started](README.md#getting-started)
+section for setup.
+
+### Event Capture
+
+`PostHog.capture` signature has changed. It now accepts properties only as a
+map. `distinct_id` is now included in the properties.
+
+```elixir
+PostHog.capture("user_signed_up", %{
+  distinct_id: "distinct_id_of_the_user",
+  login_type: "email",
+  is_free_trial: true
+})
+```
+
+No additional options can be passed. PostHog now automatically offloads events to a
+pool of sender workers that will batch and send your events. This also means
+that `Posthog.batch` doesn't exist anymore and you should simply call `capture/2` for each of your events.
+
+### Feature Flags
+
+`Posthog.feature_flag` and `Posthog.feature_flag_enabled` functions were
+replaced with `PostHog.FeatureFlags` module. Check its docs for the new usage
+guidelines.
 
 ## v0 -> v1
 
-When we stabilized our library, we decided to pull some breaking changes, here are they and how you can migrate:
+When we stabilized our library, we decided to pull some breaking changes.
 
 ### Minimum Elixir version bumped to v1.14
 
@@ -19,9 +50,9 @@ The library previously supported Elixir v1.12+. You'll need to migrate to Elixir
 
 ### Decide v4 - Feature Flags
 
-PostHog is consistently upgrading our internal data representation so that's better for customers each and every time. We've recently launched a new version of our `/decide` endpoint called `v4`. This endpoint is slightly different, which caused a small change in behavior for our flags.
+PostHog is consistently upgrading our internal data representation so that it's better for users each and every time. We've recently launched a new version of our `/decide` endpoint called `v4`. This endpoint is slightly different, which caused a small change in behavior for our flags.
 
-`PostHog.FeatureFlag` previously included a key `value` that to represent the internal structure of a flag. It was renamed to `payload` to:
+`PostHog.FeatureFlag` previously included a key `value` to represent the internal structure of a flag. It was renamed to `payload` to:
 
 1. better represent the fact that it can be both an object and a boolean
 2. align it more closely with our other SDKs
@@ -43,7 +74,7 @@ def application do
   end
 ```
 
-2. Or, if you're already using an Application, you can add add `PostHog.Application` to your own supervision tree:
+2. Or, if you're already using an Application, you can add `Posthog.Application` to your own supervision tree:
 
 ```elixir
 # lib/my_app/application.ex

README.md

@@ -21,7 +21,7 @@ Add `PostHog` to your dependencies:
 ```elixir
 def deps do
   [
-    {:posthog, "~> 0.3"}
+    {:posthog, "~> 2.0"}
   ]
 end
 ```
@@ -37,7 +37,14 @@ config :posthog,
   in_app_otp_apps: [:my_app]
 ```
 
-Optionally, enable [Plug integration](`PostHog.Integrations.Plug`) for better Error Tracking
+For test environment, you want to enable test_mode:
+
+```elixir
+config :posthog,
+  test_mode: true
+```
+
+Optionally, enable [Plug integration](`PostHog.Integrations.Plug`).
 
 You're all set! 🎉 For more information on configuration, check the `PostHog.Config` module
 documentation and the [advanced configuration guide](advanced-configuration.md).
@@ -188,14 +195,17 @@ To run integration test suite that sends real events to the API:
 
 1. Create a test PostHog project and obtain an API key.
 2. Create `config/integration.exs` config that will be used for integration tests:
-  ```
-  cp config/integration.example.exs config/integration.exs
-  ```
+
+```
+cp config/integration.example.exs config/integration.exs
+```
+
 3. Put API key into `config/integration.exs`
 4. Run integration tests
-  ```
-  mix test --only integration
-  ```
+
+```
+mix test --only integration
+```
 
 If you want to play with PostHog events in IEx, you'll need to create
 `config/dev.exs` and configure your dev instance to your liking. Here a
@@ -207,4 +217,4 @@ import Config
 config :posthog,
   public_url: "https://us.i.posthog.com",
   api_key: "phc_XXXX"
-```
+```

mix.exs

@@ -52,7 +52,7 @@ defmodule PostHog.MixProject do
         Integrations: [PostHog.Integrations.Plug],
         Testing: [PostHog.Test]
       ],
-      skip_undefined_reference_warnings_on: ["CHANGELOG.md", "MIGRATION.md"]
+      skip_code_autolink_to: &String.starts_with?(&1, "Posthog")
     ]
   end