Module Upgrade Strategy
| Module | Micronaut | Allowed |
|---|---|---|
| Patch | Patch | ✅ |
| Patch | Minor | ✅ |
| Patch | Major | ✅ |
| Minor | Patch | 🚫 (1) |
| Minor | Minor | ✅ (1) |
| Minor | Major | ✅ |
| Major | Patch | 🚫 |
| Major | Minor | 🚫 or 🤔✅ (2) |
| Major | Major | ✅ |
(1) If a module's dependency upgrades a minor version. E.g. Elastic search module has the elastic search dependency to upgrade from 7.8 to 7.9, the module should release a new minor version and that minor version will be included in the next minor Micronaut version but not in the next Micronaut's patch version. Patch version will never update users' production dependencies. Note that this only applies to libraries that follow semantic versioning.
(2) If a module's dependency upgrades to a major version. A new major version of the module will be released. A major version of the module will be included in a minor version of Micronaut only if we are sure that the change will not introduce breaking changes in users apps. Note that this only applies to libraries that follow semantic versioning.
A couple of examples:
- A module in version 1.0.3 was built with Micronaut 1.3.8. Micronaut 2.0.0 shipped with version 1.0.3 of that module. The module is upgraded to be built with Micronaut 2.x and since that it is major change a new version of the module 2.0.0 is released. Micronaut 2.1 can include that module.
- A transitive dependency of the module has a major upgrade but we have a deep knowledge about the dependency and we are sure it will not introduce breaking changes for the users. E.g. new GORM major release. We could release a new major version of the module and include it in a next Minor version of Micronaut. This should be used with extreme care since it is difficult to have confidence and good knowledge about a such major upgrade. In case of breaking changes, doubts or lack of knowledge release the module major version but don't include in the next Micronaut minor version.
A couple of notes on third party libraries and module versions:
- If a module does not use semantic versioning, we should not assume any version change does not contain breaking changes.
- Each upgrade of the third party library should be examined to determine what kinds of changes it has.
- If the module only contains bugfixes or very minor improvements, it can be included in a patch release. If it contains new features that are not trivial then it should only be included in a new minor release of the module. If it contains breaking changes that have a real possibility of impacting our users, it should be included in the next major release of the module
- A non semantic library module upgrade must be examined with care and then make the best decision of what version of the module it should go into. The version change itself has no impact on this decision. For example if library xyz increases from version 5 to 6 but it only contains bugfixes, it should go into a patch release of our module.
This process of upgrading third party libraries is not clear or obvious, so we must use our best judgement.