[QUESTION] Releases

[ofirsnb]

Question

Hi again :)
Hope ya'll doing well..

First lemme say thanks for the efforts by recent contributors (and Lubeda of course), EspHoMatrix has been evolved greatly!

Perhaps I misunderstood something along the way,
but the latest release is 2023.7.1.
Since then, there are 2023.8.0 and 2023.9.0/1 branches.

Are these branches expected to be merge into main and have their own releases?
Or are we (as users) should install EHMTX per branch-basis?

Hope to have some clarifications, to know how it's best to proceed.

Thanks again:)

[lubeda]

Hello,
thanks.

I really don't know what's the best way to deal with this problem. Between main and 2023.9.1 are many breaking changes, It's hard for me to make a proper documentation and some users don't even read the available documentation...

I like the features/possibilities of 2023.9.1, but I don't like the internal code structure, My plan is to clean up the internal structure and some function calls and release the result as an EspHoMaTriXv3. So everybody who is happy with the features of EspHoMaTriX or EspHoMaTriXv2 or... can stick with that version without dealing with the breaking change and without reading the messy documentation....

But I am open for suggestions, but the code clean up is mandatory before a new release.

For now, you can select the branch you like with:

external_components:
  - source:
      type: git
      url: https://github.com/lubeda/EspHoMaTriXv2
      ref: 2023.8.0

The 2023.9.1 is a work in progress, there are some details not fixed, but the 2023.9.0 will stay as it is.

[ofirsnb]

Thanks for the reply Lubeda.

I fully understand the difficulties. I'm personally good on 2023.7.1, since I didn't have time to deal with the breaking changes yet (I've been watching and very exited about the new features though!).
Just wanted to know what's planned ahead.

I'd be glad to share from share my experience as a dev, if I may..
TLDR: You should treat your project like any other package - it should be maintained by versions (even with breaking changes). As long as you don't rewrite your package from (almost) scratch or you don't massively change the API, I don't see a reason to open a new project.

In details:
As said, your project is actually a package.
The custom_components in ESPHome, is like a sort-of package-manager (in each yaml independently).
Same way you (as a consumer) "lock" the packages' versions when you install them (in general, not necessarily here) - the same you need to expect from your users. For example, If I install pillow in my project, and write the code for its current API, I should lock its current working version - so the next install won't install the latest version which may habe breaking changes. So, same:
When users install you package, once they finished configuring it, they should "lock" the current version that works for them (using the ref tag which can also point to a Release version).

Each release (for example 2023.7.1) should have its correlated branch - don't delete the "old" branches.
So, if I'm locked on version 2023.7.1 in this example, I can switch to this branch and take a look at its relevant documentation.
The main (or latest) branch, which is the project's Default-Branch, should be always synced to the latest (Stable) release, so when a new user installs the package, it will be exactly as the latest release - so they can lock it.

I expect users, especially ESPHome users (which are likely a bit more savvy than the average user), to follow to "version locking" method. When a new version is available, they should read the Breaking-Changes before upgrading. Otherwise they can keep their version freely. This is relevant for all custom_components in this case, not specifically for EHMTX.

In your case, What I personally would do, is
Whenever the "next" release is ready (after clean-ups as you said, etc.), I would just release a new release. I wouldn't open a new Project (I.e. "V3"). I would emphasize the breaking-changes (obviously), and maybe in your case I would even add the "version locking" suggestion in the readme. Whoever wants to upgrade - is very welcome to. Whoever doesn't - should stay in their current version (and they'll have the branch available for reference if needed).

DON'T BE AFRAID OF RELEASING BREAKING-CHANGES, they are inevitable, especially if new features are expected and wanted, while you still maintain an option for the users to move/stay freely between the releases.

BTW, if you'll release a breaking changes in the next version, sync to main, and a user who doesn't have a ref installs the "new" package during an ESPHome upgrade for example, it won't let them install obviously (or things won't work). Which will make them go here, and either upgrade correctly using breaking-changes, or adding ref to use their latest version that worked - if you'll add it to the docs as a reminder ;) . Users will always be ok, in my opinion :)

This is pretty much how every public package maintainers handle their packages, I don't see any reason why it shouldn't be like this here as well :)
But of course it's not mandatory, you should proceed however you see fit!

Hope I was able to share my way around this subject,
I'm here for any follow-ups:)

Thanks!

[ofirsnb]

One last thing, I personally have no issue with your documentation.
Yes, it's heavy, but what can you do this is a well-packed package with lots of features and options.
Again, users should find their way around, we as devs need to do our best to help them - and our only option is with a detailed doc:)

Thanks Lubeda

[anthonylavado]

I just wanted to also say thank you @lubeda , and that I agree with @ofirsnb's comments. Breaking changes are a part of progress, and having releases/versions that people can pin should be more than enough.

I'm actually looking forward to the customizable queue that I saw in the 2023.9.0 branch, so if that one is "done", I'll switch over to it.

[trip5]

2023.9.0 has stopped. 2023.9.1 branch has received even more work... I'm using it on 4 clocks. 👍

[lubeda]

I also think the 2023.9.1 is the version to go for production. I don't like the internal structure of the code but the features are very useful.

[andrewjswan]

Maybe it makes sense to release 2023.9.1?