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.

• Doc Brown: Also, if both modules still share a lot of similar code, one could still refactor these parts out into a third, common module and so reduce the duplicate maintenance at least to a certain degree.

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.

• Doc Brown: The drawback of this is approach is, if 2.x.x is still under evolvement for a longer period and requires a major change (though still based on the older framework), this would lead to a collision with V3.x.x which is already in use for the newer framework. So one could jump from V2.x.x to V4.x.x, but that has a certain risk to confuse the users, since it is not the successor of V3.x.x. So IMHO this is only an option if V2.x.x is just under minimal maintenance, and all further involvement goes into the variant V3.x.x with the newer framework.
• Berin Loritsch: It is the approach used when going from Python 2 to Python 3, as well as Ruby 1 to Ruby 2. You do happen to get to a point where your Minor version can get pretty high. Like 2.100.x, 2.101.x, etc. but there is precedent.
• Doc Brown: Ok, I agree, if the MAJOR version number is not used like usual in the Semver approach, but as an advertising version number, being an indicator for an almost complete new product line (like for Python, not sure about Ruby), then this will work.
• Berin Loritsch: It was the same for Ruby. As I said, there is precedent. Like all things, there are several correct answers... and there are also wrong answers. What is most correct is something the OP has to decide. My only goal was to show it wasn't necessary to be too fancy with it.