How to manage breakpoint releases when updating Craft via composer

Question

When logged in to Craft, the "Utilities" tab will show you all the latest releases you can update to. In some cases, it will report that you have reached a breakpoint release:

You’ve reached a breakpoint! More updates will become available after you install Craft CMS 3.1.34.3.

If I'm updating to Craft 3.2 via composer, to ensure the all the migrations get run properly and respect that breakpoint, I believe that I would need to upgrade on the command line in two steps:

• Run composer require craftcms/cms:3.1.34.3
• Run db migrations
• Run composer require craftcms/cms:3.2.0 (or whatever the latest is)
• Run db migrations

Over time, as Craft has multiple breakpoint releases it's possible that there are several breakpoint steps that need to be hit while updating from composer directly and, as far as I know, the only place to get information on breakpoint releases is via the Control Panel.

It is also possible for plugins to add breakpoint releases. So, there is a potential scenario that you have to know of and respect both Craft and plugin breakpoints. I'm not sure how Craft handles plugin breakpoints in the CP as I have not seen any do that yet, but I believe the awareness of them would also be necessary if you are doing everything from the command line.

So, it's possible if we have an older site upgrading through several breakpoints we need to do something like:

• Run composer require craftcms/cms:3.0.41.1
• Run db migrations
• Run composer require craftcms/cms:3.1.34.3
• Run db migrations
• Run composer require plugin/some-plugin:1.2.3
• Run db migrations
• Run composer require craftcms/cms:3.2.0 (or whatever the latest is)
• Run db migrations

So, my questions:

1. If we are upgrading to Craft 3 for the first time, should we be targeting the first breakpoint release as the initial version that we upgrade to?
2. Is there any good way to know which breakpoint releases exist in Craft (aside from just seeing the next breakpoint on the CP utilities tab)?
3. Is there any good way to know which breakpoint releases exist in Plugins?
4. Can you summarize the potential issues that would arise if someone skipped breakpoints while upgrading?

Answer 1

So far, Craft 3 hasn’t had any “real” breakpoint releases in the way that Craft 1 and 2 had, yet – where you would have a real issue if you were to update past them before updating to them.

Craft 1 and 2 had a handful of them, which we took as opportunities to clear out the migrations/ folder, and clean up some PHP code. If you were to (somehow) update past one in Craft 1/2, Craft would actually stop you in your tracks before you were able to run migrations, and tell you to downgrade to the breakpoint your skipped first.

If/when we release a real breakpoint release in Craft 3, Craft will do the same.

To date, Craft 3 has only had 2 “faux” breakpoints:

• When updating from > 3.0.0-alpha.1 && < 3.0.41.1, the built-in updater will have you update to 3.0.41.1 before going past it. This is because Craft 3.1 was a pretty huge update that revealed some bugs in the 3.0 updater. So 3.0.41.1 was released with some fixes to the updater, to ensure people could update to 3.1 more gracefully. Not an issue if you were using composer update to update though.

• When updating from >= 3.1.20 && < 3.1.34.3, the built-in updater will have you update to 3.1.34.3 before going past it. This is because there were a couple bugs in the project-config/rebuild command (added in 3.1.20) that we fixed in 3.1.34.3 which could create trouble for the 3.2 update, had the command been used. So adding the faux breakpoint combined with a suggestion in the 3.2 release notes to re-run project-config/rebuild was just a way to reduce potential support for 3.2 updates. If you were to composer update without following those directions, either the 3.2 update would work or it wouldn’t; in the latter case we’d end up steering you right in support.

Regarding plugins, we don’t currently offer support for plugin breakpoints, and aren’t very likely to add it, unless a really good use case comes up.