How to notify user about deprecations properly?

[damihe (Michael Wodniok)]

Is there a standard way to notify an openHAB admin about using a deprecated feature or configuration?

Use case: I am preparing a new thing type which is more powerful and takes over the logic of a bridge it’ll be attached to. But the new features are not applicable to other things attached to the bridge. Also i want to make it more meaningful to the user. This will be a breaking change. Now i think breaking changes should be possible. But a user/admin (assuming updating openHAB regularly) should have the chance to migrate in a way not experiencing to much trouble. As automatic migrations should not happen - what is the proper way to notify the admin or user?

[matt1 (Skinah)]

You can add an Alert line to this file and it gets shown as a warning when a admin does an apt upgrade.

openhab-distro/update.lst at main · openhab/openhab-distro (github.com)

Also you can mark the PR with the breaking change label so that it gets listed in the release notes.

[J-N-K (Jan N. Klug)]

It depends. If there are only minor changes (like added or removed channels), then there is a way to automatically migrate things. Core also supports changing the thing-type of a thing.

If it is just deprecated, but will continue to work, then it should be stated in the documentation and thing-types should have the attribute listed=false so they don’t show up for newly created things.

When something is really removed or requires manual actions, then it should be added to the update.lst in openhab-distro which is displayed to the user on upgrade.

Maybe you can describe a bit more detailed what you want to do.

[damihe (Michael Wodniok)]

AFAIK, channels can be added and removed by using BaseThingHandler.updateThing. This is also the solution i would keep the bridge up to date.

More detail about my plan for icalendar binding: I’d like to split up the bridge (currently doing the download, showing current events, showing some metadata and executing commands) into multiple things with orthogonal functionality, only keeping the shared functionality (only the download and metadata) in the bridge.

Is there a policy about removal of configuration options and channels (should they be deprecated a time before removal)?

[J-N-K (Jan N. Klug)]

Since https://github.com/openhab/openhab-core/pull/3330 we can also update things from the framework by adding update instructions like

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 <update:update-descriptions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xmlns:update="https://openhab.org/schemas/update-description/v1.0.0"
 	xsi:schemaLocation="https://openhab.org/schemas/update-description/v1.0.0 https://openhab.org/schemas/update-description-1.0.0.xsd">

 	<thing-type uid="testBinding:testThingTypeMultiple">
 		<instruction-set targetVersion="1">
 			<update-channel id="testChannel1">
 				<type>testBinding:testChannelNewTypeId</type>
 				<label>Test Label</label>
 			</update-channel>
 		</instruction-set>
 		<instruction-set targetVersion="2">
 			<add-channel id="testChannel2">
 				<type>testBinding:testChannelOldTypeId</type>
 				<label>TestLabel</label>
 			</add-channel>
 		</instruction-set>
 		<instruction-set targetVersion="3">
 			<remove-channel id="testChannel0"/>
 		</instruction-set>
 	</thing-type>

 </update:update-descriptions>

If channels cannot be used anymore (e.g. because a remote service simply does not provide the value anymore) then they should be removed immediately, there is no need to keep them.

[damihe (Michael Wodniok)]

In my case, keeping the old channels would just lead to partly duplicated code, but not for dead channels. So it’s pure convenience to keep the old channels up.
As there is a proper mechanism to change channels (new to me, thanks!) and showing a message to the admin about a breaking change i tend to remove the convenience and duplicated code to keep it clean.

Thank you for your input.