Define plugin versioning approach

[felixarntz]

With our first stable release 1.0.0 going out on Monday, April 18, it's time to look at what's next. We need to define our versioning policy. It's probably not worth breaking our heads about this, but we should definitely define an approach and stick to it.

At a high level, I can think of a few options:

1. We follow WordPress core's versioning approach and increment the minor version until a maximum of 9 before incrementing the major version. Patch releases would only be used on demand for hot fix releases (e.g. critical bug fix, security fix).
   • Example: After 1.0.0 we release 1.1.0, 1.2.0, and so on. After 1.9.0 we release 2.0.0. Let's say there is a critical bug in 1.3.0, then we'll publish a hot fix release 1.3.1 with just that fix.
2. Very similar to 1., but we increase the minor version beyond 9. In this model, we will only increase the major version in case of an intentional breaking change, e.g. when bumping the minimum WordPress version requirement due to a module being removed after core merge (see our version support policy for context). The approach for patch releases would match 1. exactly.
   • Example: After 1.0.0 we release 1.1.0, 1.2.0 and so on. After 1.9.0 we release 1.10.0, 1.11.0, and so on. Let's say we put a breaking change after 1.14.0, that means the following release will be 2.0.0 instead of 1.15.0. That also could mean that we won't even get to 1.9.0 for example if we already had a breaking change after let's say 1.6.0.
3. This is based on 2., but we respect semver more by carefully determining for each release not only whether there are breaking changes but also where it is purely a bug fix release. If it's a bug fix release, we will only increment the patch version, basically similar to how in 1. and 2. it would only happen for on-demand hot fix releases.
   • Example: After 1.0.0 we release 1.1.0, 1.2.0 and so on as long as these releases always include enhancements. Let's say there is a development cycle where we only fix bugs after 1.2.0, that would mean the following release will be 1.2.1, even if it is within our regular release cadence (to be defined separately). After 1.9.0 we release 1.10.0, 1.11.0, and so on. Only an intentional breaking change is gonna increment the major version, e.g. to 2.0.0.

[felixarntz]

The main benefit of 1. is that it makes version numbers entirely predictable, we will know in advance what the next releases will be as the code changes we make don't affect the version number. The tradeoff is that it doesn't respect semantic versioning (which to be fair, WordPress core does not either).

The main benefit of 3. is that it respects semantic versioning. The tradeoff is that for every release we have to carefully evaluate what is going into it and based on that define the version number shortly before (basically after code freeze), which makes it a bit more maintenance work.

The benefit of 2. is that it is a middle ground between 1. and 3. It has the benefits and trade-offs of both, just to a lesser degree. The tradeoff here is that it's not really consistent as it doesn't follow either approach.

[bethanylang]

Please vote for this approach with the designated emoji. Voting will close on Monday, May 2 at 5pm UTC.

• 👍 for option 1, following WordPress core's versioning approach and increment the minor version until a maximum of 9 before incrementing the major version. Patch releases would only be used on demand for hot fix releases (e.g. critical bug fix, security fix).
• ❤️ for option 2, following WordPress core's versioning approach but we increase the minor version beyond 9 before incrementing the major version. In this model, we will only increase the major version in case of an intentional breaking change, e.g. when bumping the minimum WordPress version requirement due to a module being removed after core merge.
• 🚀 for option 3, the same approach as option 2 but we respect semver more by carefully determining for each release not only whether there are breaking changes but also where it is purely a bug fix release. If it's a bug fix release, we will only increment the patch version, basically similar to how in 1. and 2. it would only happen for on-demand hot fix releases.

[jeffpaul]

👍🏼 and additional thoughts... While I appreciate SemVer and wish more would follow that to keep version changes explicit in terms of what's included, keeping the same approach that both WordPress core and Gutenberg take is probably the easiest approach here.

[kasparsd]

The 💯 option seems to be missing from the selector:

Is that a user preference somewhere or a recent change? Or is the intention to use the comments instead?

[bethanylang]

@kasparsd Sorry about that! Please use 🚀 for option 3; I've updated the comment.

[bethanylang]

Voting is now closed.

Based on 10 thumbs up votes and no votes for the other options, we will follow WordPress core's versioning approach and increment the minor version until a maximum of 9 before incrementing the major version. Patch releases will only be used on demand for hot fix releases (e.g. critical bug fix, security fix).

[felixarntz]

I've updated the milestone name accordingly: https://github.com/WordPress/performance/milestone/6 is now "1.1.0". We can close this issue now that this has been decided.