Switch to semantic versioning

[bilalshaikh42]

@jreadey Is there any particular scheme that you are using for versioning? To better keep track of versions, it could be useful to switch to automated release and versioning through semantic versioning and semantic release. This will allow releases to be more frequent, smaller, and versioned to clearly indicate bug fixes, features, and breaking changes.

https://github.com/semantic-release/semantic-release gives an overview of the process.

[jreadey]

Scheme such as it is, is: 0.major.minor with a "beta" suffix for pre-release candidates. Long term goal is a release 1.0.0 that provides for full (or close to it) functional compatibility with the HDF5 lib.
I'm ok with semantic versioning, but would like to keep the general cadence of a major every 6-12 months on average. Can we do this with github semantic versioning?

I've been updating the releave version in setup.py and hsds/basenode.py manually. Is there a way to automate that?

[bilalshaikh42]

Semantic versioning uses the major.minor.patch-suffix scheme. The addition of new features (what you are referring to as major I believe) updates the minor release. Bug fixes for patch and suffix can be beta/alpha etc. The cadence is essentially set by the pace of development. So every time a feature is added would be a new minor update and whenever there are breaking changes would be a major version.

Over at biosimulations for example,since we are rapidly iterating, we have gone from version 1- version 10 within a few months, but avoiding breaking changes will keep the first part constant. Generally, following the semantic versioning scheme is considered to be giving a better representation of what has actually changed rather than depending on developers' interpretation of 'major" and "minor updates"

This can still be tied to a more consistent release schedule (say every 6 months) by not merging in the latest changes to whatever the "release" branch is designated as

[jreadey]

So let's say we go with 0.7.0 under the manual scheme (I've been using this version label in news blurbs and such discussing the new release). Any new feature (based on the commit message) after that would bump the version to 0.8.0?
I guess related to this is the policy for pushing changes from feature branches to master. Would this be automatic (i.e. when all the ci tests pass) or a manual step?

[bilalshaikh42]

yup exactly, And if that change has breaking changes, meaning something in the public API changes (removal of a parameter, removing a previously valid path), the next version would actually be 1.0

This is designed to happen automatically after all the CI passes. What you can do if you want to control the speed of releases, is designate some branch as a "beta" branch, let's say, master. Then any updates to the master will trigger a release with the next version number, but with a "-beta" suffix attached. Then you can create some other branch, let's say "release" that can be configured to be the main release version. So you could iterate on the beta branch, automatically creating new releases such as 0.8.0-beta1, 0.8.0-beta2 etc. Then when those changes are merged into "release", it would trigger version 0.8.0.
More here https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration

Generally, this is a more advanced setup, since a simpler approach is to allow for frequent and regular releases (several a day is considered just fine, and actually seen as a good practice since changes are small, atomic, and easy to trace if they cause any bugs) to happen automatically as code is added. The idea is that since all the unit tests, integration tests, and performance tests are running on every update, each little change is good enough and tested enough to trigger a release. Any experimentation, tweaking, testing etc should be done in a feature branch. Since feature branches will still have docker image built and tagged for them, you can have people deploy the images/ run tests before merging into master to be extra sure about stability before making a release