Semantic Releases

Let’s talk about semantic versioning/releasing!

We are getting to the point where people are hopefully going to start running the core libraries on their own or in conjunction with other libraries. With that the ladybug-tools project is amassing an increasing number of contributors who can quickly see their changes implemented through Travis CI. All these things are amazing! But I am foreseeing issues when minor or breaking changes are implemented and how this will impact the requirements.txt of user’s codes. I also foresee issues between versions of insects that work together (ladybug/honeybee or dragonfly/uwg for example).

As such I propose we chat about using automated semantic versioning for the core libraries. There are a few ways to go about it, I reckon using commit syntax in combination with the semantic-release tool will make things easy.

Here’s some links:

For now the release can just be deployed to the git repository but once the project finds a naming scheme it’s happy to use for PiPy then we can also release straight to there.

What do you guys think?


I like the idea but as I’m writing this post I’m concerned with the implementation (e.g. how to get everyone to follow it!) but we must do what it takes to get everyone up to speed. @chris and I are already dealing with this issue with ladybug > honeybee updates and their effect on Grasshopper plugins. For now we manually keep the branches and PRs in order but it is not efficient.

I don’t usually use memes but this post is an exception!


Yep I know what you mean about implementation. I appreciate it has a chance of either scaring a few new contributors or disgruntling some longer standing ones.

Here are a few thoughts on the matter:

  • Using an open standard when committing (in this case I propose the Angular commit schema) means it’s well documented, that some might already know of it, is well tested and will benefit people contributing to other projects in the future
  • A few mechanisms could be put in place to implement this:
    1. Ask contributors to commit correctly every time/ask them to recommit with different commit text if they do not.
    2. Squash commit PRs and enforce commit name at that point
    3. Merge commit PRs, enforce commit name at that point but preserve commit history from forks
    4. Use master + dev branches where contributors PR to the dev branch and work on a regular release cycle to PR dev into master using semantic versioning at that point.

I would personally vote for mechanism 1 or 3 (preference for 1 obvies) as this allows an incredibly quick release cycle and will also reduce review load on the project admins (as people will be forced to piece meal their commits a bit more). It will also help keep track of bug fixes, new feature creation and migration work.

I have personally jumped on the bandwagon of this in my current work on found it relatively straightforward to get into.

We could test this on a smaller repository to start with if you want (I’m thinking Dragonfly core and potentially UWG as they both have a good start with CI implementation).

PS: this image resumes how semantic versioning will work based on commits (where type determines which of the three digits to increase => dragonfly 1.0.3 == dragonfly breaking_changes:features:bug-fixes)

FYI: Ladybug Tools on PyPI