| Re: [hono-dev] Definition of Hono's public API |
Hi Committers,
in our Hono community call today we discussed this topic as well.
Carsten and I argued that we do not (yet) have broad adoption of any of
the Java artifacts that we publish. In particular, there is only the Red
Hat folks working on a device registry utilizing the base classes that
are contained in the service-base module and they seem to be happy to
adapt their implementation to (modest) breaking changes that we might
introduce in new minor releases.
In addition to that we quickly agreed that the client module currently
contains classes relevant for the implementation of protocol adapters as
well as for applications that want to interact with Hono's north bound
API. This is less than ideal because it creates strong coupling between
mostly unrelated classes. We agreed that we should split up the client
module into modules that each target a more specific type of client.
All this leads me to think that declaring any of these classes to be
stable, public API and subjecting them to semantic versioning would not
be very helpful to anybody in our community (yet) but would make it
considerably harder for us to quickly evolve and improve Hono.
I therefore propose to only declare Hono's remote APIs defined under [1]
and the standard protocol adapters' device-facing resources/behavior [2]
as public API and thus subject to semantic versioning.
Committers, in order to come to a conclusion on this topic, I kindly ask
you to cast your vote.
[1] https://www.eclipse.org/hono/docs/api/
[2] https://www.eclipse.org/hono/docs/user-guide/
Kai
On 22.01.20 09:40, Hudalla Kai (IOC/PAP-HU) wrote:
> Sorry, forgot to add the links ...
>
> Based on the discussions I had with Carsten regarding the changes
> necessary for [1] I can now also imagine to only define the classes of
> the core and client modules as part of Hono's Public API.
>
> Dejan had already raised some concerns regarding the impact it would
> have on our ability to quickly evolve, if we declared too much of our
> code as part of the public API. I now see his point more clearly as it
> would basically prevent us from making any reasonably complex changes to
> any of our adapters without creating a new major release, which is
> probably not what we want. Most of our adapters heavily depend on
> classes in the service-base module so in order to make any substantial
> progress we will need to change many of the classes in there.
>
> In the past we had encouraged people to create custom protocol adapters
> by means of extending some of the base classes in service-base. However,
> in reality it seems more practical to use the approach outlined in [2]
> in order to connect devices using a proprietary protocol to a Hono
> system. Note that this approach does not require implementing a full
> fledged custom protocol adapter.
>
> I would therefore propose to also exclude the service-base module from
> Hono's public API. People can still use it if they want to implement a
> custom adapter but they should be aware that we might change the code at
> any time.
>
> WDYT?
>
> [1] https://github.com/eclipse/hono/issues/1328
> [2] https://github.com/eclipse/hono/issues/1478
>
> Kai
>
> On 15.01.20 14:22, Hudalla Kai (INST/ECS4) wrote:
>> On 15.01.20 12:56, Dejan Bosanac wrote:
>>> Hi Kai,
>>>
>>> this seems reasonable to me. Just one thing, when you say "all classes",
>>> do you mean public methods signatures by that or something else?
>>>
>>
>> Good point. I would say that this affects all public classes in the
>> "public" packages which are currently
>>
>> core: all packages
>>
>> client: all packages
>>
>> service-base: all packages
>>
>> Does that make sense?
>>
>>> On Tue, Jan 14, 2020 at 8:52 AM Hudalla Kai (INST/ECS4)
>>> <Kai.Hudalla@xxxxxxxx <mailto:Kai.Hudalla@xxxxxxxx>> wrote:
>>>
>>> Hi list,
>>>
>>> with Hono 1.0.0 having been released last year, we now need to follow
>>> semantic versioning for its public API. So far so good. During the past
>>> weeks while implementing new features, we already ran in to situations
>>> where some refactoring would have been beneficial but where we had to
>>> think twice about whether we can simply change a method's signature or
>>> remove some obsolete class(es). I think we can all agree that this
>>> depends on whether the affected artifacts are to be considered part of
>>> Hono's public API or not.
>>>
>>> However, we haven't yet defined which parts of Hono actually constitute
>>> its public API. Thus, I would like to propose a draft of what I would
>>> consider (or like to see as) part of Hono's public API:
>>>
>>> 1) All remote APIs documented under [1]
>>> 2) All classes in the core module
>>> 3) All classes in the client module
>>> 4) All classes in the service-base module
>>>
>>> IMHO the rest would then automatically not be public API and would thus
>>> not be subject to semantic versioning.
>>>
>>> WDYT?
>>>
>>> [1] https://www.eclipse.org/hono/docs/api/
>>>
>>> --
>>> Mit freundlichen Grüßen / Best regards
>>>
>>> Kai Hudalla
>>>
>>> Software Developer - Bosch IoT Hub
>>>
>>> Bosch.IO GmbH
>>> Ullsteinstr. 128
>>> 12109 Berlin
>>> GERMANY
>>> www.bosch.io <http://www.bosch.io>
>>>
>>> Registered Office: Berlin, Registration Court: Amtsgericht
>>> Charlottenburg; HRB 148411 B
>>> Chairman of the Supervisory Board: Dr.-Ing. Thorsten Lücke;
>>> Managing Directors: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne
>>> Reckling
>>> _______________________________________________
>>> hono-dev mailing list
>>> hono-dev@xxxxxxxxxxx <mailto:hono-dev@xxxxxxxxxxx>
>>> To change your delivery options, retrieve your password, or
>>> unsubscribe from this list, visit
>>> https://www.eclipse.org/mailman/listinfo/hono-dev
>>>
>>>
>>>
>>> --
>>> Regards
>>> --
>>> Dejan Bosanac
>>> http://sensatic.net/about
>>>
>>> _______________________________________________
>>> hono-dev mailing list
>>> hono-dev@xxxxxxxxxxx
>>> To change your delivery options, retrieve your password, or unsubscribe from this list, visit
>>> https://www.eclipse.org/mailman/listinfo/hono-dev
>>>
>>
>
--
Mit freundlichen Grüßen / Best regards
Kai Hudalla
Software Developer - Bosch IoT Hub
Bosch.IO GmbH
Ullsteinstr. 128
12109 Berlin
GERMANY
www.bosch.io
Registered Office: Berlin, Registration Court: Amtsgericht
Charlottenburg; HRB 148411 B
Chairman of the Supervisory Board: Dr.-Ing. Thorsten Lücke;
Managing Directors: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne
Reckling
_______________________________________________
hono-dev mailing list
hono-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/hono-dev