RFC: Semantic Versioning
What changes will be made and why they would make a better Orfeo ToolBox?
Idea: change OTB version numbering to follow semantic versioning (https://semver.org/). SemVer is quickly becoming a standard best practice in software engineering. It allows better dependency management and control of backwards compatibility.
High level description
See the official website for the full spec: https://semver.org/. In summary:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
For example, for OTB if we adopt this starting at 7.0, it could look like:
| Type of release | Current plan | SemVer |
|---|---|---|
| Major | 7.0 | 7.0.0 |
| Minor (RC) | 7.2-rc1 | 7.1.0-rc1 |
| Minor | 7.2 | 7.1.0 |
| Bug fix only | 7.2.1 | 7.1.1 |
| Minor | 7.4 | 7.2.0 |
| Minor | 7.6 | 7.3.0 |
We almost do semver already, except that we skip odd minor numbers for some reason. Additionally, moving develop to the next version number continuously as feature branches are merged in would remove the systematic merge conflict we get when merging release branches into develop. Bug fix releases are still done on their respective minor release branches and backported where need. I don't think this affects our current gitflow.
We need also need to decide what counts as our "API": C++ interface, Python interface, application names, application parameters, etc.?
Risks and benefits
Risks:
- Break some scripts?
Benefits:
- Follow software engineering best practice
- Use formal spec for version number semantic. No more debate on "what is the next version number?".
- develop version number is always "next release", no more intermediate odd numbers.
- Fix the systematic merge conflict on release branch merge
Alternatives for implementations
NA
Who will be developing the proposed changes?
TBD
Feedback is welcome!