How to version modules that depend on different framework versions

Question

I work as a Website developer. We use a framework for building the backend of our sites. This framework recently released a new major version with lots of breaking changes. We have some sites using the old and many sites using the new major version.

I am currently tasked with writing a module that needs to work with both framework versions. This module needs to talk to an external API that we are maintaining, so if we change/update that API we need to update both modules. Since both versions of the framework are fairly different we need separate code bases to maintain the module.

My question is: How should I version the module to prepare for future major releases of the API while also keeping both framework versions separate Ideally while sharing code

What I have thought of:

• Use different package names: module-v1 and for the newer use module-v2
• Use a fourth version number 1|2.MAJOR.MINOR.PATCH where the first digit is the framework version (don't know if composer supports this)
• Use different branches (release/1, release/2)

Note: Specifically, we are using PHP and composer for managing packages.

Answer 1

If the two framework versions effectively require that you maintain two independent versions of the module, it is best to create two independent packages: module-framework_v1 and module-framework_v2.

That gives the clearest signal to everyone involved that if there are modifications or bug-fixes that need to be made to the module, that those changes might need to be made twice. Because what you are doing in reality is maintaining two modules that just happen to have very similar names and features.

Answer 2

Leveraging the idea of Semantic Versioning, incrementing the MAJOR version is justified when:

• There are significant internal changes (i.e. changing underlying frameworks)
• There are significant API changes

In short, incrementing a major version is a signal that users of the module should expect incompatibilities, whether by design or not. Many times, changing the underlying framework introduces constraints that can break expectations of the users.

My recommendation is:

• Keep the MAJOR version number the same on the older existing framework
• Increment the MAJOR version for the newer framework

You can see this pattern in several open source projects where even if the API or interfaces are the same, the internal architecture may not be. So you'll see the "new" branch in a 3.0.x range while the old branch is on 2.x.x.