Best practice for plugin upgrade on major Craft releases

[matfish2]

With Craft 4 looming in the horizon I was wondering what is the best way to upgrade plugins for major releases.

I see two possible options:

Option 1

Building from scratch (or copying the code) on a separate repo for every major release. I see that's exactly what nystudio107 did with SEOmatic and Retour when migrating from Craft 2 to 3. A possible downside is that as long as the older version is not deprecated the plugin developer now has to maintain two separate repos. Also, star count is not carried over to the new version.

Option 2

Create a legacy version branch on the same repo with some sort of naming convention (e.g craft-v{x}), and then continue to upgrade to the new version on the master/main branch, and apply patches or bug fixes as necessary to the legacy version until it is deprecated. This depends on whether Craft supports updating the plugin branch on the same repo.

Questions regarding both options

1. How does Craft handle the same plugin for different major releases? e.g can both versions of the plugin co-exist in the store?
2. What is the acceptable period after which the older version can be completely deprecated, including bug fixes?

I think it would be helpful if the docs covered this aspect of development as well, so that plugin developers can all follow the same guidelines, and users of older versions will have a timeline after which they can no longer expect support.

[brandonkelly]

I would definitely recommend keeping the same repo. A new repo would also mean a new plugin handle (both must be unique), which really means it would be treated as a whole new plugin, which would drastically complicate the upgrade process.

1. How does Craft handle the same plugin for different major releases? e.g can both versions of the plugin co-exist in the store?

We keep track of which Craft version(s) each plugin/version is compatible with. The Plugin Store will only show plugins that have at least one version compatible with the current Craft version, and when you click Install, you will get the most recent compatible version.

So when Craft 4 is out, plugins can start releasing new versions that add Craft 4 compatibility, and then they will start showing up in the Plugin Store for Craft 4 installs. Meanwhile Craft 3 will continue showing the latest Craft 3-compatible version.

2. What is the acceptable period after which the older version can be completely deprecated, including bug fixes?

We will be supporting Craft 3 for one additional year, after Craft 4 comes out, plus one more year of addressing critical security vulnerabilities. Ideally plugin developers will follow suit, but we aren’t going to mandate it.