Flying with a Fledgling Phoenix

Phoenix is a living, breathing and active project. Prior to the release of a new major version, there is often a “release candidate” for people to test out and report issues. Getting and trying those pre-release versions isn’t straight forward. We’ll see at how to get an RC, try it out on a new project, and even how to compare differences with generated files created by different versions of Phoenix to better understand how to upgrade an existing project.

Problem

A new Phoenix release candidate has just landed and it includes some new features we want to try out. However, upgrading our existing project to the new release would be messy and time-consuming. We would encounter warnings, errors, and conflicts with other dependencies, and it would be difficult to see how the generators have changed.

To play with our new fledgling Phoenix release candidate without getting burned, it is best to create a new project. The Phoenix installation guides instructs us to run mix archive.install hex phx_new to install Phoenix, but this will not get the release candidate.

How do we install and manage a Phoenix release candidate? And once we have it, how can we compare the differences between a newly generated Phoenix project from a previous version?

Solution

Before we start messing with our Phoenix Installer version, let’s take note of our current version by running the following command:

mix phx.new --version

Phoenix installer v1.6.15

This is useful to know if we want to revert back to our original version later.

To try out a pre-release version like 1.7.0-rc.0, we use the command recommended in the Phoenix release candidate blog post:

mix archive.install hex phx_new 1.7.0-rc.0

We will be prompted to replace our existing Phoenix Installer. There can only be one installed at a time. Say “yes” to install and replace any existing version.

To confirm that we are now using the new Phoenix version, run the following command:

mix phx.new --version

Phoenix installer v1.7.0-rc.0

We’re ready to create a new app!

Generate a new app

Before we create a new app, let’s review the available flags to make sure we include the features we want. To see the available flags, run:

mix help phx.new

Now we can create a new Phoenix app to play with. For this example, let’s use the name my_app. We will come back to the benefits of this name choice later.

mix phx.new my_app

For this example, we want to check out how the phx.gen.auth changed in the new release, specifically that it now supports LiveView. For a deeper look at this new feature, check out Berenice Medel’s post Bringing Phoenix Authentication to Life.

Before we generate anything, let’s review the available flags by running:

mix help phx.gen.auth

With this knowledge, we can now generate something:

mix phx.gen.auth Accounts User users

Great! We now have a working and interactive example of the new feature we are interested in. Personally, I’m enjoying playing with the new authentication features and seeing how they render and feel! 😍

Compare against previous releases

It is helpful seeing a newly generated Phoenix app and the generated templates we care about! But how can we compare these changes to a project that’s been over a year in development with a whole team hacking on it? We could try directly comparing our existing app with the newly generated one, but that will be so noisy it’s not worth doing. I promise. Ouch.

Instead, we’ll generate another Phoenix app using the version that our project was based on. This makes it easier to see the relevant pieces that changed. Then we can adapt those changes to our project!

Before we start, let’s rename the generated project folder to help keep track of it. Previously, we named it my_app and a folder with the same name was created. Let’s rename the folder to phx_1_7_rc_0.

Now, we’re ready to generate an older Phoenix project. To prevent nearly every single file from being different, we’ll use the same name, my_app.

Let’s install the desired version of the Phoenix Installer. In this case, we’ll go with 1.6.15.

mix archive.install hex phx_new 1.6.15

Now generate an older project with the same name, my_app and include any relevant flags.

mix phx.new my_app

After generating the app, let’s rename the folder from my_app to phx_1_6_15 to make it easier to tell what we’re looking at.

We now have two different generated Phoenix applications named my_app in two different versions of Phoenix! Let the comparisons begin!

Comparing versions locally

Navigating and comparing two full projects may feel daunting. Never fear! Using a free, cross-platform tool like Meld, we can easily compare two complete directories to see what changed from one version to the next.

For this example, we are comparing the generated authentication templates, so we need to run the same generator on our older project. We need to mix get.deps and mix compile before the generator task is available. Then we can run it like this:

mix phx.gen.auth Accounts User users

Now we can compare the two projects using a directory comparison tool like Meld.

Select the directories with our projects.

Directories with nested contents are compared.

When a specific files was modified, we can open that file for a single-file comparison.

Now we can discover what changed and adapt those to our other projects.

Comparing versions online

For the impatient among us who want to quickly see the differences from one version to the next with different flags used when the projects were generated, there is a great community resource over on ElixirStream.dev created and maintained by David Bernheisel. The tool we’re talking about is the Generator Diff.

Generator Diff caches computed comparisons, so here’s a link to the phx.gen.auth generator differences between Phoenix 1.6.15 and Phoenix 1.7.0-rc.0. It also supports comparing the different flag options, so it’s very helpful!

If you just want to see the diff for two project versions, this is a great resource!

Summary

As Phoenix continues to advance and improve, we may want to quickly try out the new features and, when we’re ready, apply those changes to our projects to keep them up-to-date with current conventions.

We started off by generating a fresh Phoenix app with the new features we want to explore and safely play with that enticing fledgling Phoenix release without getting ourselves burned in the process!

We then saw how we can generate multiple versions of a Phoenix app locally. The benefits of this is we use the development tools we already know to inspect the projects. We can run and interact with these local projects too. This is a great way to try out and see how a new approach feels rather than inferring based on the code.

We introduced the free, cross-platform tool Meld that helps us visually compare complete directories.

We also covered how we can use online community resources like ElixirStream’s Generator Diff tool to quickly compare file diffs for changes from one version to another.

With options like these available, we have the tools needed to keep our projects feeling fresh both inside and out!

Now, I’m off to play with the new LiveView authentication before applying the changes to my project. 🤩 What are you most excited to play with?