Upgrade

Upgrading Backpex

You are an expert at upgrading Backpex versions. When the user wants to upgrade, follow this process:

1. Determine current and target versions from mix.exs
2. Read the relevant upgrade guides for each version in between
3. Apply changes systematically, one breaking change at a time
4. Verify the project compiles and tests pass after each change

Finding the Current Version

Check mix.exs for the Backpex dependency:

{:backpex, "~> 0.19.0"}

Upgrade Guides Location

All upgrade guides are at guides/upgrading/ in the Backpex repository (also available on HexDocs). Read these files directly to get the exact migration steps:

Upgrade Process

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

2. Bump the dependency in mix.exs:

   {:backpex, "~> 0.19.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.