Upgrade

Upgrade Process

1. Read ALL upgrade guides between current and target version. For example, upgrading from 0.15 to 0.18 requires reading v0.16, v0.17, and v0.18 guides.

2. Bump the dependency in mix.exs:

   {:backpex, "~> 0.18.0"}
   

3. Run mix deps.get to fetch the new version.

4. Apply breaking changes from each guide in order. Common categories:

   • Removed or renamed options
   • New required callbacks
   • Changed callback signatures
   • Moved or renamed components
   • Removed dependencies
   • New Gettext translation strings

5. Compile and fix warnings: mix compile --warnings-as-errors

6. Run tests to catch regressions.

Common Breaking Change Patterns

Callback replaces option

# Before (option)
use Backpex.LiveResource, layout: {MyAppWeb.Layouts, :admin}

# After (callback)
use Backpex.LiveResource, ...

@impl Backpex.LiveResource
def layout(_assigns), do: {MyAppWeb.Layouts, :admin}

New required callback added

Read the upgrade guide for the default value and implement it in affected modules.

Changed callback signature

Search your codebase for the old callback name and update all implementations.

Removed dependency

Check if your code directly uses the removed module/function and replace with the suggested alternative.

New Gettext strings

Each Backpex release may add new translatable strings. After upgrading:

1. Copy the updated Gettext template from the Backpex dependency into your application:

   cp deps/backpex/priv/gettext/backpex.pot priv/gettext/backpex.pot
   

   Alternatively, download it from GitHub at https://github.com/naymspace/backpex/blob/<VERSION>/priv/gettext/backpex.pot (replace <VERSION> with your target version tag).

2. Remove elixir-autogen comments from the copied .pot file. The Backpex source file contains #, elixir-autogen, elixir-format comment lines. If left in place, running mix gettext.extract --merge will delete all Backpex translations from your PO files (Gettext treats autogen entries as auto-generated and removes those not found in your source code). Strip them:

   sed -i '' 's/#, elixir-autogen, elixir-format/#, elixir-format/g' priv/gettext/backpex.pot
   

3. Merge the new strings into your existing PO files:

   mix gettext.merge priv/gettext
   

4. Translate any new msgid entries in your priv/gettext/<locale>/LC_MESSAGES/backpex.po files.

The .pot file on the develop branch may contain unreleased translations. Always use the version tag that matches your Backpex version.