Release cycle

[florian-h05]

Hello @openhab/javascript-maintainers,

I would propose to release (at least) a new version of the openhab-js library about one week before any openHAB stable release as we also need some time to get the according PR for the JS Scripting add-on merged.

Additionally, any merged PR should be set the according milestone (currently https://github.com/openhab/openhab-js/milestone/1) to track bugfixes & enhancements (as described in https://github.com/orgs/openhab/teams/maintainers/discussions/1).

For the next openhab-js release, I would plan the 24th of June which is one week before the time limit of the 3.3.0 Milestone of openhab-core.

Please comment or leave a 👍 or 👎 .

Best greetings,
Florian

[digitaldan]

That sounds great. 👍

It would be good to decide on a general process/cadence for releasing openhab-js and updating the plugin.

Also i did not put a lot of thought into our versioning scheme for openhab-js, other then it had to start higher then the original project that donated that NPM project/name to us (npm.org rules) .

[florian-h05]

For the general process, I would propose that we release a new version a few days before each openHAB Milestone release and get this new version into that milestone. As far as I remember, new milestones are typically released on the first days of a new month.

So we should release about 5 days before the end of month to get our PR merged into the milestone.
Generally, I would target the 25th of the month for a new release.

I will have a look at the publish workflow and try to modify it to also release beta versions (with npm publish --tag beta).

Regarding the versioning scheme:
I would follow the About semantic versioning section of the npm docs, which says:

Code status	Stage	Rule	Example version
Backward compatible bug fixes	Patch release	Increment the third digit (1.0.x)	1.0.1
Backward compatible new features	Minor release	Increment the middle digit and reset last digit to zero (1.x.0)	1.1.0
Changes that break backward compatibility	Major release	Increment the first digit and reset middle and last digits to zero (x.0.0)	2.0.0

Given that, the last release should have been 2.0.0 due to some breaking changes, so I would make the next release 2.0.0.
I would continue to have tags to trigger the npm publish workflow and create a new release on GitHub where we will have a changelog.

I would tag stable versions with v* and milestones with v*-milestone* (e.g. v2.0.0-milestone1).

[florian-h05]

@digitaldan
WDYT?

[digitaldan]

For the general process, I would propose that we release a new version a few days before each openHAB Milestone release

I wondering if we want to release more often than this, at least for non-milestones? So if people want to try out new features by using npm install or we want the nightly build to have an updated version? I like having our library version moving on its own, and then like your idea about tagging milestone releases for inclusion into the addon. I think tagging 5 days before sounds reasonable.

The version scheme sounds fine to me as well.

[florian-h05]

I wondering if we want to release more often than this, at least for non-milestones? So if people want to try out new features by using npm install or we want the nightly build to have an updated version?

We could setup a daily/weekly CI job to publish a nightly (or better experimental to stay in npm scheme) tagged version to npm and manually publish milestone (or beta to stay in npm scheme) tagged versions as well as latest (npm default) (=stable).

Then our release schedule would look like (with example version number):

Version name	Description	Release schedule	npm tag
2.0.0	Stable version	Half a year (manually)	latest
2.0.0-milestone1	Milestone version	Every month (manually)	beta
2.0.0-snapshot-2022-06-05	Nightly snapshot	Every night (CI automation)	experimental

[digitaldan]

if would be awesome if we could just keep incrementing our build using standard semantic versioning on every push when things change using something like https://itnext.io/how-to-automate-versioning-and-publication-of-an-npm-package-233e8757a526 , and only have to do manual tags for inclusion into openHAB (aka milestone releases), or only have to manually bump the version when there is a breaking change. I'm thinking how we keep our versioning permutations as simple as possible since this library is pretty light weight and changes seem less risky compared to openHAB core or addon development. WDYT?

[florian-h05]

I have read the article a few days ago, and I am wondering if we should publish a new version on every push to main or only when the commit message includes a special keyword, what would allow us to have the version number automatically bumped when there is a breaking change. The second approach with keywords would also allow us to make changes that are not related to the package (like CI workflows) and not publish a new version then.

only have to do manual tags for inclusion into openHAB (aka milestone releases)

Yes, I would do manual tags for openHAB inclusion to clearly indicate which version of the package goes into the add-on, but we could also just use the current version of the library.

I'm thinking how we keep our versioning permutations as simple as possible since this library is pretty light weight and changes seem less risky compared to openHAB core or addon development. WDYT?

I totally agree with the point that changes seem less risky compared to core or addons, I can‘t remember any change of the library breaking something or introducing a bug that was not in a new added feature.

So it would be awesome to automatically publish on pushes to main, the only question for me is if we want to use keywords like described in the article or not. WDYT?

[florian-h05]

https://github.com/marketplace/actions/automated-version-bump Seems to do what we want.

This workflow would require commit messages to include sth like (patch), (minor), (major) to release an according release.

[florian-h05]

@digitaldan
I have implemented my proposed workflow for openhab-js in one of my personal repos, see https://github.com/florian-h05/openhab-js-tools/tree/main/.github/workflows.

This workflow does:
Run at midnight and get today's commits. Based on today's commit messages (if there are any) (based on keywords), the version scheme (patch, minor, major) is determined and the version is bumped, after this a new release is created. If there were no commits today, nothing happens.

I adjusted the action I mentioned in my previous post to meet my requirements, see https://github.com/florian-h05/gh-action-advanced-bump-version.

I will test that workflow for a few days on my personal repo and if everything works fine, I can come up with a PR.

WDYT?

[florian-h05]

@digitaldan
How do we proceed on this?
We can continue to publish manually, then we have more control over what is released when, but we could also use that automation.
I‘ve been using it for over a month now on one of my personal repos and it is great, when I just push a commit and at midnight a new version is on npm.

[digitaldan]

Sounds good, trying to remember our conversation. Did we say by default this would do minor version increments, then we would manually do major version bumps? Did we also say we would tag versions that were intended to be including in JSScripting builds?

[florian-h05]

Did we say by default this would do minor version increments, then we would manually do major version bumps?

This workflow would by default do patch version increments and do minor or major based on configurable keywords.

Did we also say we would tag versions that were intended to be including in JSScripting builds?

Yes, but I need to try that out first.

[digitaldan]

This sounds good to me! I think it's fine to manually tag a version for now when we want to include it in a addon release.

[florian-h05]

I will open a PR to create both Workflows, one for automated publishing and one for tagging the add-on versions.

[florian-h05]

@digitaldan
In the last few weeks I thought a little bit over the automatic publishing of new versions, and I am asking myself whether it is better to only publish when a maintainer decided to.
Often when I manually published a new version, I was waiting for a PR to get merged to get a bugfix or enhancement into the next version.

I would rather create a workflow that is triggered manually from the actions site (using the workflow_dispatch trigger), so that we can control when to release and when not. This could anyway use my GitHub action, just with a different trigger.

The next thing we have to look out with, is the CHANGELOG. This requires manual updating.

[digitaldan]

I'm fine with that, we can give it a try and see how it works.

[florian-h05]

I checked today, there is no easy way of publishing something like SNAPSHOTS to npm that is worth the work when it is also possible to install directly from GitHub. I added a note to the README that describes how to install the latest „development version“ from GitHub.

Regarding the releases, I tried some tools for auto-releasing and automated CHANGELOG generation, but to have this properly work, we would have to follow a specific commit message scheme.

I want the CHANGELOG, therefore I will stay on manual releases. To be honest, as that’s nothing to happen to often, it would cost more time to find an auto-release system I‘m happy with than jost publishing that release manually.

[digitaldan]

Hey @florian-h05 i have github notifications on my phone from this thread like there is new activity, but i don't see any here. Just checking if you were bumping this topic or replying and i am just not seeing it ?

[florian-h05]

I have read GitHub's deprecation statement on Team Discussions and followed GitHub's recommendation to move the team discussions to the repo discussions. Otherwise we would not be able to continue discussion on your topics.

What I have however noted, is that the repo discussions are public visible. I don't have enough rights on this repo to check whether we can make our maintainer discussions private. If there is no way, the openhab GitHub org needs some new way for private discussions after GitHub shut down team discussions.

[digitaldan]

Gotcha, i did not realize this was a migrated thread.

From Github:

GitHub Discussions is a collaborative communication forum for the community around an open source or internal project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project board and are not related to code, unlike GitHub Issues. Discussions enable fluid, open conversation in a public forum.

From that description I would say they are always visible

[florian-h05]

Okay thanks for looking into this. We should keep in mind that discussions are public.