Module Versioning Development

Just added a new branch to the dashboard module - ‘stable’ which is consistent with the branch naming protocol of the core emoncms repo and follows on from earlier discussions with @pb66

The advantage of having this is discussed in the posts here, and enables us to manage the module versioning better. Currently using just one branch for each module, means that with every commit, we should advance the version following the merge, which is not really sustainable or practical.

By using 2 branches, we can continue to merge PR’s and make changes to the master branch without updating the version tag. We can then continue to test the changes within the master branch, and at a time we feel that nothing is broken & there are no obvious bugs, we can merge the ‘master’ branch into the ‘stable’ branch, update the version, and also the changelog with all of the changes.

No action is needed by users at this time, but hopefully @glyn.hudson will consider changing the emonpi update script to begin cloning the dashboard ‘stable’ branch, instead of ‘master’, so emonpi users get the most stable version and best experience.
Non-emonpi users, can use either stable or master branch, but if like emonpi users they want the most stable version, then use the stable branch.

I share the same view as @pb66, and had several long discussions about this with Glyn a couple of years ago. Maybe this is an opportunity to review the branch naming protocol.


1 Like

Should that be ‘master branch’ or have I missed which is which?

//Thanks - post amended! - PR

Fantastic, thanks a lot @Paul. This is great :smiley:

1. emonPi / emonBase Default Branch

Good idea, done:

When a user next initiates an emonPi update via the local Emoncms admin interface the emonPi Emoncms Dashboards branch will be changed to stable. All new emonPi’s will be shipped already on the stable branch since an emonPi update is ran in the factory before an emonPi is shipped.

2. Change log

I personally would prefer to just have the change log just on the Github releases page like the Emoncms core releases page rather than a dedicated file. It’s easy to forget to update one or the other and errors could creep in having the same information in two separate locations. However, I don’t really mind too much and I’m well aware that most of the work maintaining the module is currently undertaken by @Paul to which we’re most grateful. I’m happy to let you decide. It looks like it’s possible to automatically generate a chagelog from git release / commits/ PR’s using:

Although at this stage it’s probably not worth the effort to set up such an automated system since we only do releases occasionally it’s not too much of an overhead.

3. Git tag version number format

To match Emoncms core I would prefer git tag version numbers to be without the leasing v at the beginning of the git tag. e.g v1.0.0 > 1.0.0. However, I’ve just tried to rename the tags on the Dashboard module, however there seems to be no easy way to rename a tag once created. This is not a problem, we will just stick with using a leading v for dashboard module git tags :slight_smile: . I’m mentioning this since those of you who follow the repo will probably have received a few release emails as I have tried to rename the tag! Apologise for this.

4. Emoncms module version number

As discussed previously it would be great to have the module version number displayed on the Emoncms admin page. While it would technically be possible to phase the file (assuming we have one), I think it could get messy and easily broken if we don’t stick to the correct format. I think a bulletproof method would be to have a module.json file using the same template as the package.json used by node red. The module.json file could contain the following:

    "name"         : "Dashboard",
    "version"      : "1.0.2",
    "description"  : "Dashboard module for emoncms",
    "homepage"     : "",
    "license"      : "GNU Affero General Public License v3.0",
    "repository"   : {

This module.json file could easily be phased by emoncms to display version number on the admin page and the extra info in the file could be used in the future for auto module updating, naming etc.

What do you think @TrystanLea?

I have created a PR to the dashboard module with the proposed template for module.json:

Just tried removing the ‘v’ from git to match core & module.json and I think it’s worked… :confused:
We could always start afresh if it hasn’t. Delete the existing versions and start at 1.0.0 again. Might as well get it right from the beginning.

If you are intending to use the Github release page for the other modules, then it makes sense to do the same in the dashboard module too for consistency.


Not quite, all the tags are now on the same commit location 9bba6bf which is not correct.

Yes, I think the easiest way would be just to delete all the tags and start again from 1.0.0. This is what I’ve just done. Now only a single tag 1.0.0 exists at the current commit 9bba6bf: Tags · emoncms/dashboard · GitHub

I’m just waiting to hear back from @TrystanLea regarding his thoughts on the module.json PR, please don’t merge until we get the go ahead from him. I’ll discuss with @TrystanLea the best way for Emoncms to look at module.json and display the version number in the Emoncms admin page.

Yes, I think following the same procedure that we use for Emoncms core for all Emoncms Modules is good for consistency. It seems to be working well for Emoncms core. In the case, would you mind if I removed and just used the github releases to store the changelog like on Emoncms core?

No, please do.
It was worth exploring what options were available, but, yes the changelog would create duplicity.

Can I suggest we set up a “version” feature branch on each repo (emoncms, modules and emonpi) to develop the versioning and possibly automated/scripted updating before committing to any particular format or methods?. Any commits to the “master” branch will get pulled through with any fixes/mods committed in the immediate future and any commits to the stable branch are pretty much set in stone unless backwards compatibility is also addressed.

I understand JSON is probably the easiest thing for emoncms to cope with, but when working from the Linux command line as we do much of the time, JSON is not so easy to handle. There are Bash based JSON parsers such as “jq” that could be installed if it must be JSON.

What are the advantages of the other items in module.json? Is there a planned need for the data? Would a plain text file with just the version in cause problems for emoncms?

Ok, done:

Sure, however lets use the dashboard module as a starting point to develop this.

Sure, I’m open to ideas. If JSON is not easy to parse, then maybe just a simple version.txt file could be the simplest solution. However, I can see that using JSON would let us easily add meta info about the module which could be very useful in the future to keep track of Modules. In the future, it would be great to be able to add / remove / update modules via the admin page. Such automation would require meta info to describe the module and any dependencies etc.

I need to discuss these idea with @TrystanLea. I’m currently abroad until the 19th July. I will discuss with Trystan when I’m back in the office unless he replies to this thread before then.

Sure, what works for the dashboard module should work with any module, we can bring the others on board closer to finalizing and merging to the master branches.

Great! I’m not against using JSON, I’m just for making the right choice and testing before committing to any untested path.

1 Like