Merge pull request #201 from tompave/no_application

Remove the Application module

Author: tompave

.iex.exs

@@ -57,4 +57,16 @@ cacheinfo = fn() ->
   :ets.i(:fun_with_flags_cache)
 end
 
+# Start the FWF Supervision tree as a child of the IEx application.
+# This makes it a bit more convenient to visualize the supervision tree in the
+# observer tool. (`:observer.start()`)
+#
+Supervisor.start_child(IEx.Supervisor, {FunWithFlags.Supervisor, []})
+#
+# Or starting it directly also works:
+#
+# FunWithFlags.Supervisor.start_link(nil)
+
+# Enable this to work with telemetry events:
+#
 # FunWithFlags.Telemetry.attach_debug_handler()

CHANGELOG.md

@@ -4,10 +4,11 @@
 
 Work is in progress towards v2.0 of the package.
 
+* Start behaviour has changed. FunWithFlags v2.0 doesn't come with its own Application anymore, therefore its supervision tree should be started and managed manually. The ability to manually control FunWithFlags' supervision tree was initially introduced in [v1.7.0](https://github.com/tompave/fun_with_flags/blob/master/CHANGELOG.md#v170), and has now become the default and only way to use the package. ([pull/201](https://github.com/tompave/fun_with_flags/pull/201))
+
 Main goals:
 
 * [ ] Config overhaul. Stop using the config.exs file, and rather do something like what Ecto does. The host application should define its own module (like an Ecto repo) that provides the flag querying and toggling API. The package config should be provided with an init callback in the custom module.
-* [ ] Start behaviour. It should never start automatically, so the manual management of the supervision tree should become the default.
 * [ ] Stop relying on atoms. Use binaries wherever possible. Relying on atoms makes some things harder, especially when handling user input in the UI package.
 * [ ] Add metadata to the storage layer: timestamps, plus free form JSON for later use.
 

README.md

@@ -51,7 +51,6 @@ It stores flag information in Redis or a relational DB (PostgreSQL, MySQL, or SQ
 * [Extensibility](#extensibility)
   - [Custom Persistence Adapters](#custom-persistence-adapters)
 * [Telemetry](#telemetry)
-* [Application Start Behaviour](#application-start-behaviour)
 * [Testing](#testing)
 * [Development](#development)
   - [Working with PubSub Locally](#working-with-pubsub-locally)
@@ -520,11 +519,20 @@ def deps do
 end
 ```
 
-Using `ecto_sql` for persisting the flags also requires an ecto adapter, e.g. `postgrex`, `mariaex` or `myxql`. Please refer to the Ecto documentation for the details.
+Using `ecto_sql` for persisting the flags also requires an ecto adapter, e.g. `postgrex`, `myxql`, or `ecto_sqlite3`. Please refer to the Ecto documentation for the details.
 
-Since FunWithFlags depends on an Elixir more recent than 1.4, there is [no need to explicitly declare the application](https://github.com/elixir-lang/elixir/blob/v1.4/CHANGELOG.md#application-inference).
+FunWithFlags comes with its own supervision tree that needs to be started in order to use the package. This can be as simple as including `FunWithFlags.Supervisor` in the supervision tree of the host application:
 
-If you need to customize how the `:fun_with_flags` application is loaded and started, refer to the [Application Start Behaviour](#application-start-behaviour) section, below in this document.
+```elixir
+def start(_type, _args) do
+  children = [
+    FunWithFlags.Supervisor,
+  ]
+
+  ...
+```
+
+When using FunWithFlags in a Phoenix application, it's recommended to start `FunWithFlags.Supervisor` after the application's Ecto repo and `Phoenix.PubSub` process.
 
 ## Configuration
 
@@ -720,78 +728,6 @@ FunWithFlags is instrumented with [Telemetry](https://hex.pm/packages/telemetry)
 
 The full list of events emitted by FunWithFlags are documented in the [FunWithFlags.Telemetry](https://hexdocs.pm/fun_with_flags/FunWithFlags.Telemetry.html) module.
 
-## Application Start Behaviour
-
-As explained in the [Installation](#installation) section, above in this document, the `:fun_with_flags` application will start automatically when you add the package as a dependency in your Mixfile. The `:fun_with_flags` application starts its own supervision tree which manages all required processes and is provided by the `FunWithFlags.Supervisor` module.
-
-Sometimes, this can cause issues and race conditions if FunWithFlags is configured to rely on Erlang processes that are owned by another application. For example, if you have configured the `Phoenix.PubSub` cache-busting notification adapter, one of FunWithFlag's processes will immediately try to subscribe to its notifications channel using the provided PubSub process identifier. If that process is not available, FunWithFlags will retry a few times and then give up and raise an exception. This will become a problem if you're using FunWithFlags in a large application (e.g. a Phoenix app) and the `:fun_with_flags` application starts much faster than the Phoenix supervision tree.
-
-In these cases, it's better to directly control how FunWithFlags starts its processes.
-
-The first step is to add the `FunWithFlags.Supervisor` module directly to the supervision tree of the host application. For example, in a Phoenix app it would look like this:
-
-```diff
-defmodule MyPhoenixApp.Application do
-  @moduledoc false
-  use Application
-
-  def start(_type, _args) do
-    children = [
-      MyPhoenixApp.Repo,
-      MyPhoenixAppWeb.Telemetry,
-      {Phoenix.PubSub, name: MyPhoenixApp.PubSub},
-      MyPhoenixAppWeb.Endpoint,
-+     FunWithFlags.Supervisor,
-    ]
-
-    opts = [strategy: :one_for_one, name: MyPhoenixApp.Supervisor]
-    Supervisor.start_link(children, opts)
-  end
-
-  # ...
-```
-
-Then it's necessary to configure the Mix project to not start the `:fun_with_flags` application automatically. This can be accomplished in the Mixfile in a number of ways, for example: (**Note**: These are alternative solutions, you don't need to do both. You must decide which is more appropriate for your setup.)
-
-* **Option A**: Declare the `:fun_with_flags` dependency with either the `runtime: false` or `app: false` options. ([docs](https://hexdocs.pm/mix/1.11.3/Mix.Tasks.Deps.html#module-dependency-definition-options))
-
-```diff
-- {:fun_with_flags, "~> 1.6"},
-+ {:fun_with_flags, "~> 1.6", runtime: false},
-```
-
-If you use releases then you'll also need to modify the `releases` section in `mix.exs` so that it loads the `fun_with_flags` application explicitly (since `runtime: false` / `app: false` will exclude it from the assembled release).
-
-```diff
-def project do
-  [
-    app: :my_phoenix_app,
-+   releases: [
-+     my_phoenix_app: [
-+       applications: [
-+         fun_with_flags: :load
-+       ]
-+    ]
-  ]
-end
-```
-
-* **Option B**: Declare that the `:fun_with_flags` application is managed directly by your host application ([docs](https://hexdocs.pm/mix/1.11.3/Mix.Tasks.Compile.App.html)).
-
-```diff
-  def application do
-    [
-      mod: {MyPhoenixApp.Application, []},
-+     included_applications: [:fun_with_flags],
-      extra_applications: [:logger, :runtime_tools]
-    ]
-  end
-```
-
-The result of those changes is that the `:fun_with_flags` application won't be loaded and started automatically, and therefore the FunWithFlags supervision tree won't risk to be started before the other processes in the host Phoenix application. Rather, the supervision tree will start alongside the other core Phoenix processes.
-
-One final note on this topic is that if you're also using [`FunWithFlags.UI`](https://github.com/tompave/fun_with_flags_ui) (refer to the [Web Dashboard](#web-dashboard) section, above in this document), then that will need to be configured as well. The reason is that `:fun_with_flags` is a dependency of `:fun_with_flags_ui`, so including the latter as a dependency will cause the former to be auto-started despite the configuration described above. To avoid this, the same configuration should be used for the `:fun_with_flags_ui` dependency, regardless of the approach used (Option A: `runtime: false`, `app: false`; or Option B: `included_applications`).
-
 
 ## Testing
 

lib/fun_with_flags/application.ex

@@ -23,8 +23,7 @@ defmodule FunWithFlags.Mixfile do
 
   def application do
     # Specify extra applications you'll use from Erlang/Elixir
-    [extra_applications: extra_applications(Mix.env),
-     mod: {FunWithFlags.Application, []}]
+    [extra_applications: extra_applications(Mix.env)]
   end
 
   defp extra_applications(:test), do: local_extra_applications()

mix.exs

@@ -4,7 +4,6 @@ does_anything_need_redis = !(
   FunWithFlags.Config.persist_in_ecto? && FunWithFlags.Config.phoenix_pubsub?
 )
 
-
 if FunWithFlags.Config.phoenix_pubsub? do
   # The Phoenix PubSub application must be running before we try to start our
   # PubSub process and subscribe.
@@ -37,6 +36,9 @@ IO.puts "Notifications adapter: #{inspect(FunWithFlags.Config.notifications_adap
 IO.puts "Anything using Redis:  #{inspect(does_anything_need_redis)}"
 IO.puts "--------------------------------------------------------------"
 
+# Start the FWF Supervision tree.
+FunWithFlags.Supervisor.start_link(nil)
+
 if does_anything_need_redis do
   FunWithFlags.TestUtils.use_redis_test_db()
 end