-
Notifications
You must be signed in to change notification settings - Fork 0
JCoRe Versioning and Releases
This page elaborates on JCoRe conventions on version numbering and release handling.
JCoRe version numbers follow the basic Maven conventions illustrated, for example, here. Further, in addition to the major version, JCoRe also requires a minor and bugfix version number always to be present (possibly be 0, e.g. 2.1.0). We currently do not use build numbers and the only qualifier in use is SNAPSHOT.
Major version number bumps should reflect rather dramatic, compatibility breaking changes such as severe API changes or major shifts in usability conventions. Minor versions still may break compatibility but should not change the project dramatically. Usually, minor versions will collect all former bug fixes but also introduce new components. New components should not be added within an already released JCoRe version but are always added to the next minor - or major - version as long as it is still in SNAPSHOT state.
Maven allows to specify version number ranges for dependencies, e.g. [2.1,3). This technique is widely discouraged due to unforseen conflicts that may arise. In JCoRe, we also try to refrain from using version ranges. They may be used, however, to cover all bugfix versions within a minor release since bugfixes should not break compatibility.
In JCoRe there are two kinds of releases. The more conventional type is the common GitHub release mechanism that creates a tag for the repository in the respective release state. For such releases, all JCoRe repositories are assigned the same version, a release tag and are finally deployed to Maven Central.
It is also possible for individual components to be released due to a bugfix. Thus, such component releases
- do only advance the bugfix version
- do not cause the whole of JCoRe to adapt the new bugfix version and do not require a release tag
- deploy only the bugfixed component to Maven Central.
According to the JCoRe versioning contract, the bugfix must not break compatibility within its minor JCoRe release. Thus, new bugfix versions of components should always just be "better" than former versions and should be usable within a minor release no questions asked. Other components depending on the bugfixed component may either refer exactly to the new version number which would make a bugfix version of the dependent component necessary as well. To circumvent a process where one component is advanced in its bugfix version only due to a bugfix of its dependencies, a version range up until to, but not including, the next minor release number may be specified. For example, if a component is bugfixed from version 2.1.0 to 2.1.1, dependent components might just specify the version range [${jcore-version},2.2).
Complete JCoRe releases which span all JCoRe-related repositories, typically only happen for major and minor version bumps. Each major and minor JCoRe version has its own branch in each JCoRe repository. After a release, the repositories have to be prepared for the next release cycle. This is done by
- creating a new branch for the next intended release version and
- setting all POMs of all JCoRe projects to this version.
Since JCoRe has quite a number of modules, we employ scripts to help with quick and easy setting of new version numbers. There exists a python script in the project to JCoRe Misc repository to do this.