Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[argoclima] Initial contribution #15481

Merged

Conversation

mbronk
Copy link
Contributor

@mbronk mbronk commented Aug 22, 2023

This PR adds a new binding for ArgoClima HVAC devices.

Please refer to the included README.md for details of this binding's objectives.

  • Notably, the Connection modes section illustrates various modes this binding operates in.

Exemplary supported device:

Highlights (for reviewers)

  1. The most notable items I suggest to focus on during the review are the binding modes which spawn a separate HTTP server thread(s), and a custom HTTP client
  2. Since it started as a DYI project (with no initial plans to upstream), I did not start any separate thread in the OpenHab community.
    • If this is required for a new binding to get landed and the review process kicked off, I'd appreciate guidance.

Testing / development status

For what it's worth, I've been using this binding myself for a while now, and haven't noticed any anomalies, so as far as I subjectively perceive it, I consider it quite stable and fairly complete. No extensive multi-user large-scale testing has been performed though!
Outside of addressing any feedback stemming from review, I'm not currently planning any major functionality extensions. A.k.a. a 1.0 RC1 :)

Thank you in advance for all your feedback and guidance!

@mbronk mbronk requested a review from a team as a code owner August 22, 2023 23:53
@mbronk mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from a7a9dc8 to ed0a70f Compare August 22, 2023 23:58
@jlaur jlaur added the new binding If someone has started to work on a binding. For a new binding PR. label Aug 23, 2023
@mbronk mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch 3 times, most recently from b6f8a15 to e22b162 Compare August 24, 2023 18:54
Copy link
Contributor

@lsiepel lsiepel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First pass, only looked at the readme and metadata, will try to look at the other files when i have some more time.

Most looks good, mainly some textual comments and some questions.

bundles/org.openhab.binding.argoclima/README.md Outdated Show resolved Hide resolved
bundles/org.openhab.binding.argoclima/README.md Outdated Show resolved Hide resolved
bundles/org.openhab.binding.argoclima/README.md Outdated Show resolved Hide resolved
bundles/org.openhab.binding.argoclima/README.md Outdated Show resolved Hide resolved
bundles/org.openhab.binding.argoclima/README.md Outdated Show resolved Hide resolved
bundles/org.openhab.binding.argoclima/README.md Outdated Show resolved Hide resolved
bundles/org.openhab.binding.argoclima/README.md Outdated Show resolved Hide resolved
bundles/org.openhab.binding.argoclima/.gitignore Outdated Show resolved Hide resolved
@mbronk mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from e22b162 to 7cc19e8 Compare August 25, 2023 20:05
@mbronk

This comment was marked as resolved.

@lsiepel

This comment was marked as resolved.

Copy link
Contributor

@lsiepel lsiepel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Allmost half way, my time is up for now, didn't want to hold it back.

Impressed about the extensive documentation. It is a bit overwhelming, but it helps.

@mbronk

This comment was marked as resolved.

Copy link
Contributor

@lsiepel lsiepel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Finished the last part. Did leave some comments, but overall this seems a very solid (but complex) contribution.

Consider my review as an extra set of eyes to speed up the merge proces. I'm no maintainer, so there might be more feedback, or corrections to mine (don;t hope so).

@mbronk

This comment was marked as outdated.

@mbronk mbronk requested a review from lsiepel August 31, 2023 16:13
@mbronk

This comment was marked as outdated.

@lsiepel
Copy link
Contributor

lsiepel commented Sep 4, 2023

Hey @lsiepel, I know you're likely very busy with other things, but could you do me a favor and indicate (tentatively) when 🕐 would you be able to find a few minutes to take a final sweep through the latest comments and update their status? 🙏

Reason I'm asking is - while I tried to apply all the comments - I'm not 100% sure if I addressed everything, and would like to complete this phase, before I'm out for a short vacation next week (so that I leave it in a mergeable state). Let me know if it is realistic for you to take a look this week. Thank you in advance!

Give me a week max

Copy link
Contributor

@lsiepel lsiepel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM Thank you for this binding.

It might take some time, but a maintainer will pick this up and review / merge this eventually.

@mbronk mbronk requested a review from jlaur November 10, 2023 08:28
@mbronk
Copy link
Contributor Author

mbronk commented Nov 10, 2023

Hey @jlaur - sorry for bothering you... Since you're had some fly-by interactions with this PR (and are a maintainer), would you happen to know what might be the typical ETA for a new binding review novadays?
I do absolutely realize it's a community effort, and happy to wait as long as required - just making sure this PR didn't fall through the cracks and is on someone's radar still.

[joke] On that occasion, to lighten the mood... any chance to get it merged before christmas 😀 ? [ref: Duke Nukem] :) [/joke]

@jlaur
Copy link
Contributor

jlaur commented Nov 11, 2023

would you happen to know what might be the typical ETA for a new binding review novadays?

My algorithm for calculating that is broken. 😄 You can have a look at recent merged PR's with label "new binding" to get an impression. Unfortunately our capacity is a bit low, but eventually someone will pick up your PR and start a review. A few things in general that can have an impact on the time for completing a review of a new binding:

  • Size: I created a PR of similar size on February 9th: [energidataservice] Initial contribution #14376. It was merged on July 3rd, so ~5 months. 10k lines is a rather large PR in comparison with other PR's.
  • Quality: Will not do any comparisons or references here, but obviously a PR requiring many (perhaps major) comments to be resolved will take longer than a very clean and high quality PR.
  • Speed of addressing comments: Once a review gets started, the momentum can be kept by addressing comments quickly. It will be easier for a reviewer to check resolutions and provide new feedback when still fresh in mind compared to picking up a PR with months old comments. This is not to be underestimated.
  • Compliance: If there are many disagreements between the contributor and maintainer, this can prolong the process. What can help here is being reasonable and keeping a good tone, since reviewers are also human. 😉 This makes it easier to reach good compromises. Not everything can be discussed though since there are some guidelines and openHAB architecture/ways of doing things that must be followed. It only happens very rarely that a PR is rejected because of disagreements, usually we reach an agreement and the PR is merged.

Personally I probably won't be able to pick it up for the time being since I'm involved in some other ongoing rather large PR's, and I prefer to not have too many open at the same time because I then risk becoming the bottleneck and momentum is lost.

@mbronk
Copy link
Contributor Author

mbronk commented Nov 11, 2023

Thanks for such a thorough reply! Much more info than I had hoped for, appreciate it!
I was actually looking at some typical PR processing times myself, but failed to filter by new binding, so drew wrong conclusions... My bad!

Since 5+ months is not unprecedented, I'll stop getting worried for a while (till err... christmas? 😁 ).


And as for:

10k lines is a rather large PR

Yeah, I know. But also... java 😉

Copy link
Member

@holgerfriedrich holgerfriedrich left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution!
This is not a full review, just a few comments.

In addition to my comments, the following things need improvement:

  • javadoc is currently broken, at least the errors need to be fixed (mvn javadoc:javadoc|grep error:) - mainly & and < to be escaped.....

SAT is fine, warnings are fine, i18n seems ok

@mbronk
Copy link
Contributor Author

mbronk commented Dec 22, 2023

@holgerfriedrich Thanks fot the review. Fixed the javadocs errors (sorry for the miss!). Do you need me to address all javadoc warnings as well?

BTW. I had to extend pom.xml to add @implNote and @apiNote support. Is this typical/expected?
(I was thinking the plugin should inherit configuration from top-level, but it didn't work for me... not sure if it is my setup-specific or if I made an error somewhere...)

@holgerfriedrich
Copy link
Member

@holgerfriedrich Thanks fot the review. Fixed the javadocs errors (sorry for the miss!). Do you need me to address all javadoc warnings as well?

No, warnings are ok. I have not checked, but most of the warnings should be undocumented elements. This is expected.
I just wanted to make sure that the javadoc build does not fail.

BTW. I had to extend pom.xml to add @implNote and @apiNote support. Is this typical/expected? (I was thinking the plugin should inherit configuration from top-level, but it didn't work for me... not sure if it is my setup-specific or if I made an error somewhere...)

If I got it correctly, you branched quite a wile ago. Those tags are now defined in pom.xml on top level (since ~2 months). Before, we had it on binding level.
Just fetch upstream/main and rebase.

@mbronk mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from 8541027 to d56a032 Compare December 22, 2023 13:48
@mbronk
Copy link
Contributor Author

mbronk commented Dec 22, 2023

BTW. I had to extend pom.xml to add @implNote and @apiNote support. Is this typical/expected?

If I got it correctly, you branched quite a wile ago. Those tags are now defined in pom.xml on top level (since ~2 months). Before, we had it on binding level. Just fetch upstream/main and rebase.

Yup, that did it. I did a quick check and saw it on GH main, but it didn't occur to me it might not bee there for ages, so didn't check on my local copy... Thx for the pointer!

@mbronk mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from 23700ae to 5f02573 Compare December 23, 2023 10:27
Copy link
Contributor

@lsiepel lsiepel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, LGTM.

I prefer another @openhab/add-ons-maintainers to have a second look. Not necessarily all files, the readme and the ThingHandlers will probably be enough to get a good understanding and provide some feedback.

@lsiepel
Copy link
Contributor

lsiepel commented Jun 28, 2024

@jlaur if you have some spare time, would be nice if you can look at this pr for a moment

@jlaur
Copy link
Contributor

jlaur commented Jun 28, 2024

if you have some spare time, would be nice if you can look at this pr for a moment

I took at very quick look at the README which lead me straight to the thing type definition. I have posted a few comments there, as some of these things will be hard to change later without introducing breaking changes.

However, if the intention with your request is to have review comments added and fixed by tomorrow, I'm afraid this is too late and too out of context. I also doubt @mbronk would have time to even react on the comments I already posted, so please feel free to ignore.

Unit hint for Number:Dimensionless should be added (see #16614), so you could either commit those changes if @mbronk will not be able to respond, or it can be added in a follow-up PR.

@lsiepel
Copy link
Contributor

lsiepel commented Jun 28, 2024

if you have some spare time, would be nice if you can look at this pr for a moment

I took at very quick look at the README which lead me straight to the thing type definition. I have posted a few comments there, as some of these things will be hard to change later without introducing breaking changes.

However, if the intention with your request is to have review comments added and fixed by tomorrow, I'm afraid this is too late and too out of context. I also doubt @mbronk would have time to even react on the comments I already posted, so please feel free to ignore.

Unit hint for Number:Dimensionless should be added (see #16614), so you could either commit those changes if @mbronk will not be able to respond, or it can be added in a follow-up PR.

Thanks! My request was more about the overall complexity by looking at the readme and the handler. I would have merged it if you didnt have significant feedback at those areas.
Your current feedback about channel id's is minor, but altogether enough to postpone a merge. So this will propably not make it into 4.2. Maybe you can revisit the handler on a later time after 4.2 is done.

@jlaur
Copy link
Contributor

jlaur commented Jun 28, 2024

Your current feedback about channel id's is minor, but altogether enough to postpone a merge. So this will propably not make it into 4.2. Maybe you can revisit the handler on a later time after 4.2 is done.

The channel type id's can be changed later on using update instructions, but it's really minor anyway, and doesn't violate naming convention. However, the thing type id, although also minor, cannot be changed later.

I would focus first on getting the modelling right (from the start), the implementation can always be refactored if it turns out to be too complex (for example). So I trust your review, and you can still consider merging this for 4.2. I believe strictly it doesn't have to be tomorrow even though we have feature freeze. The feature freeze s is mostly to avoid introducing regressions in existing bindings with last-minute changes. So if you and @mbronk would agree on the thing type id proposal, this is a small change, and there could still be a few days to do that (XML, constants, README).

mbronk added 3 commits June 29, 2024 08:20
Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
Contents:
[argoclima] 1st round of review remarks (editorials)
[argoclima] 2nd round of review remarks (config)
            showCleartextPasswords --> includeDeviceSidePasswordsInProperties
            (default: NEVER)
[argoclima] i18n: Missing localization added
            Adds i18n for dynamic Channels and Thing statuses (incl. exceptions)
[argoclima] 3rd round of review remarks
[argoclima] 4th round of review remarks
            Renamed localDevicePort --> hvacListenPort
            Used instanceof pattern matching (where applicable)
            Demoted device communication logs to TRACE
            (non-review feedback) Added missing indirect command intercept in STUB
            mode
[argoclima] Fixed typos in docs (README, diagrams)
[argoclima] Post-review corrections: javadoc, etc.
[argoclima] Bump version to 4.2.0-SNAPSHOT
[argoclima] README.md minutiae
[argoclima] Channels rename to lower-case-hyphen
[argoclima] CP header update to 2024
[argoclima] Review remarks (password hashing extracted + minutiae)

Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
@mbronk
Copy link
Contributor Author

mbronk commented Jun 29, 2024

The channel type id's can be changed later on using update instructions, but it's really minor anyway, and doesn't violate naming convention. (...) So if you and @mbronk would agree on the thing type id proposal, this is a small change, and there could still be a few days to do that (XML, constants, README).

@jlaur - I do agree with the proposed renames (less boilerplate, less typing). I had them globally-unique 'just in case', to avoid weird x-tenancy issues at development time... but as there are none... yeah, it can/should be shortened.

Given short timelines... behold...

The plan ™️ 😉

You guessed right I won't have time to properly apply (and test) this change in full just today (only have about 1 hour free before I head off for a short weekend getaway).
But - it's a straightforward one I can try to apply (=change, make things compile again) very quickly.

This would be a not-yet-tested code, but in a "frozen" state already with all the CI complete and such.
When I'm back from a short family trip, I'd be able to test and around Monday, give you a works 👍 / doesn't work 👎 .
Worst-case, the last commit can be reverted, or the changeset skips 4.2. Best case... what I'll commit today passes the "quality" checks and would become mergable on Monday.
@lsiepel , @jlaur - What do you think? OFC not a good engineering practice, but... sounds like a plan? 😁

@lsiepel
Copy link
Contributor

lsiepel commented Jun 29, 2024

The channel type id's can be changed later on using update instructions, but it's really minor anyway, and doesn't violate naming convention. (...) So if you and @mbronk would agree on the thing type id proposal, this is a small change, and there could still be a few days to do that (XML, constants, README).

@jlaur - I do agree with the proposed renames (less boilerplate, less typing). I had them globally-unique 'just in case', to avoid weird x-tenancy issues at development time... but as there are none... yeah, it can/should be shortened.

Given short timelines... behold...

The plan ™️ 😉

You guessed right I won't have time to properly apply (and test) this change in full just today (only have about 1 hour free before I head off for a short weekend getaway). But - it's a straightforward one I can try to apply (=change, make things compile again) very quickly.

This would be a not-yet-tested code, but in a "frozen" state already with all the CI complete and such. When I'm back from a short family trip, I'd be able to test and around Monday, give you a works 👍 / doesn't work 👎 . Worst-case, the last commit can be reverted, or the changeset skips 4.2. Best case... what I'll commit today passes the "quality" checks and would become mergable on Monday. @lsiepel , @jlaur - What do you think? OFC not a good engineering practice, but... sounds like a plan? 😁

Take your time, as it is a new binding I think we can merge it after the milestone. It should just be well tested.

@mbronk
Copy link
Contributor Author

mbronk commented Jun 29, 2024

Take your time, as it is a new binding I think we can merge it after the milestone. It should just be well tested.

Oh, I'm not at all proposing skipping a testing phase. Given the nature of the changes (renames-only) though, early next week is an actual possibility (not cutting corners) - just can't make any guarantees today.

For me it is still far better to try (best-effort) to intercept 4.2 (b/c it's incremental for me) than to do the whole nine yards on 4.3 or later...

* Thing type ID renames: argoclima-local -> local,
  argoclima-remote->remote
* Dropped '-channel' suffix from channel type IDs
* Added % unit hint to eco-power-limit

Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
@mbronk mbronk force-pushed the mbronk/argoclima_binding_wip_OH4.1-SNAPSHOT-clean branch from f7b70d6 to 30dabd2 Compare June 29, 2024 07:41
@mbronk
Copy link
Contributor Author

mbronk commented Jun 29, 2024

As mentioned - changes suggested by @jlaur are in. I'll separately confirm the testing status early next week.

Seems I can't vote (👎 ) for my own changes (or wasn't able to find an option), but please consider it a -1 from me for the interim (this applies to last commit's status only).

Comment on lines +426 to +429
## Disclaimer

This project is not affiliated with, funded, or in any way associated with Argoclima S.p.A.
All third-party product, company names, logos and trademarks™ or registered® trademarks remain the property of their respective holders.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kaikreuzer - sorry for tagging you directly (well, half-sorry, since I'm still doing it 😄) - do we have some project-wise disclaimer like this? It feels a bit inconsistent to have this at binding level, since I guess most bindings do not have this. On the other hand, it must be on binding-level to mention specific companies we are not affiliated with. From a legal perspective, is this needed at all?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lsiepel, @mbronk - FTR, my comment here is generic and doesn't have to be considered for the PR at hand. Depending on response from @kaikreuzer we can adjust (if needed) even after this PR is merged.

Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
@mbronk
Copy link
Contributor Author

mbronk commented Jul 1, 2024

As mentioned - changes suggested by @jlaur are in. I'll separately confirm the testing status early next week.

Update

All tests have passed on my end.

Copy link
Contributor

@lsiepel lsiepel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks LGTM. This will (as exception due to feuture freeze) be included in 4.2.

@lsiepel lsiepel merged commit 7bcce77 into openhab:main Jul 1, 2024
5 checks passed
@lsiepel lsiepel added this to the 4.2 milestone Jul 1, 2024
psmedley pushed a commit to psmedley/openhab-addons that referenced this pull request Jul 12, 2024
* Initial contribution of the ArgoClima binding

Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
pgfeller pushed a commit to pgfeller/openhab-addons that referenced this pull request Sep 29, 2024
* Initial contribution of the ArgoClima binding

Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
Signed-off-by: Patrik Gfeller <patrik.gfeller@proton.me>
joni1993 pushed a commit to joni1993/openhab-addons that referenced this pull request Oct 15, 2024
* Initial contribution of the ArgoClima binding

Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
matchews pushed a commit to matchews/openhab-addons that referenced this pull request Oct 18, 2024
* Initial contribution of the ArgoClima binding

Signed-off-by: Mateusz Bronk <bronk.m+gh@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
new binding If someone has started to work on a binding. For a new binding PR.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants