[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [hono-dev] Definition of Hono's public API
|
+ 1
>
> 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
Best regards
Carsten Lohmann
Bosch IoT Hub - Product Area IoT Platform (IOC/PAP-HU)
Bosch.IO GmbH | Ullsteinstr. 128 | 12109 Berlin | GERMANY | www.bosch.io
Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling
