You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by Dirk Rudolph <di...@apache.org> on 2021/06/28 11:20:42 UTC
[VOTE] Release Apache Sling Sitemap version 1.0.0
Hi,
We solved 1 issues in this release:
https://issues.apache.org/jira/projects/SLING/versions/12350352
Staging repository:
https://repository.apache.org/content/repositories/orgapachesling-2484
You can use this UNIX script to download the release and verify the signatures:
https://gitbox.apache.org/repos/asf?p=sling-tooling-release.git;a=blob;f=check_staged_release.sh;hb=HEAD
Usage:
sh check_staged_release.sh 2484 /tmp/sling-staging
Please vote to approve this release:
[ ] +1 Approve the release
[ ] 0 Don't care
[ ] -1 Don't release, because ...
This majority vote is open for at least 72 hours.
- Dirk
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Konrad Windszus <ko...@gmx.de>.
Semantic Versioning IMHO mostly cares about Consumers (which are many bundles) as Providers usually need to be changed for any kind of API change and are only a few bundles compared to the many consumer bundles.
So yes, although changing a consumer interface requires recompilation of the provider bundle that is usually desired (especially if the class is closely related to a provider type class in the same package).
So I guess the best practice is rather:
- Put closely related classes in the same package
- Don't let the package contain too many classes (because obviously the fewer classes share one package version the less of a risk for unnecessary recompilation of consumers)
Konrad
> On 30. Jun 2021, at 06:54, Carsten Ziegeler <cz...@apache.org> wrote:
>
> You can regard provider type as the implementor of the api of a package whereas everything marked as consumer type is implemented by users of that api.
>
> So yes, if you make any changes to that package, add a new interface, add a new method etc., you need to adjust the implementor.
>
> For example, if you add a new consumer interface, it will break the implementor - but it is highly likely that the implementor needs to do something with that new interface, like picking up all services implementing that new interface and eventually invoking those. So it is natural that the implementation needs to be updated.
>
> Of course, if the change is about static utility code, then yes this is not breaking the implementor. But I consider this an edge case.
>
> You can't make changes to a consumer type (unless you add a default method to an interface) as this will break all clients.
>
> So again, many use cases for putting consumer and provider type interfaces into a single package are totally valid and good api style.
>
> Moving api artifically into separate packages just because of the fear that changes require to update the implementation, can create a bad api experience.
>
> Side note, if you have api and the implementor in the same module, the whole discussion goes away. Which is another fun discussion :)
>
> Regards
> Carsten
>
>
> Am 29.06.2021 um 22:48 schrieb Eric Norman:
>> Hi Konrad,
>> Can you confirm that mixing your 3rd scenario (as below) with any of the
>> other 3 within the same bundle also results in the narrow version range for
>> that imported package?
>> @ProviderType 1.1.0 yes
>> [1.1, 1.2) Provider
>> The point being that as soon as you implement any ProviderType interface in
>> your bundle then you can't add new (unrelated?) classes to that exported
>> package or change any ConsumerType classes in that exported package because
>> those changes would result in a bump of the exported minor version number.
>> The imported package range for any bundles that were built against the
>> previous release would no longer match the narrow version range exported by
>> the new release.
>> This is the scenario that was discussed with SLING-10031
>> On Tue, Jun 29, 2021 at 12:28 PM Konrad Windszus <ko...@gmx.de> wrote:
>>> Hi, sorry for the confusion here, I think I may be just wrong.
>>>
>>> From the standard policies from Bnd I do no longer think mixing Consumer
>>> and Provider in one package can lead to breaking users of the API more
>>> easily.
>>>
>>> Let's quickly recall what the rules are:
>>>
>>> Rules for Exported Versions
>>> ====
>>>
>>> ConsumerType
>>> Every binary incompatible change requires an increment on the major
>>> version.
>>>
>>> ProviderType
>>> Every binary incompatible change requires (at least) an increment on the
>>> minor version.
>>>
>>> Rules for Imported Versions
>>> =====
>>>
>>> For each interface/ non final class it is stated, whether it is supported
>>> to be implemented/extended by Consumers (and providers, the default) or by
>>> Providers only. That information together with the information whether the
>>> interface is just used or really implemented determines the version-range
>>> of the import-package statement:
>>>
>>> Annotation on class/interface | Version Implemented | Import-Package
>>> Version Range | Versioning Policy
>>> @ConsumerType 1.1.0 yes
>>> [1.1, 2.0) Consumer
>>> @ConsumerType 1.1.0 no
>>> [1.1, 2.0) Consumer
>>> @ProviderType 1.1.0 yes
>>> [1.1, 1.2) Provider
>>> @ProviderType 1.1.0 no
>>> [1.1, 2.0) Consumer
>>>
>>> Those policies can be overwritten via the instruction
>>> http://bnd.bndtools.org/instructions/consumer_policy.html and
>>> http://bnd.bndtools.org/instructions/provider_policy.html.
>>> From those rules I cannot construct a usage which would point at splitting
>>> Consumer and Provider types.
>>>
>>> I think my confusion initially came from
>>> https://github.com/apache/felix-dev/blob/057bb85d7d496671755cd53cffc9e91a17c1d17c/tools/osgicheck-maven-plugin/src/main/java/org/apache/felix/maven/osgicheck/impl/checks/ConsumerProviderTypeCheck.java#L115
>>> @Carsten: Do you remember why that usage leads to an error in
>>> osgicheck-maven-plugin?
>>>
>>> Konrad
>>>
>>>
>>>
>>>> On 29. Jun 2021, at 20:23, Eric Norman <en...@apache.org> wrote:
>>>>
>>>> I haven't looked at this too closely, but do you think that there could
>>> be
>>>> some benefit to keeping them in separate packages if you expect the
>>>> consumer and provider apis to evolve at a different pace?
>>>>
>>>> If I recall correctly, the bundles that import and use stuff from a
>>> package
>>>> that contains both consumer and provider classes may get a too specific
>>>> range for the import package range.
>>>> This has to do with bndlib choosing the "provider-policy" instead of the
>>>> "consumer-policy" when calculating the version ranges.
>>>>
>>>> From what I read, the default definitions for bnd are:
>>>>
>>>> -consumer-policy ${range;[==,+)}
>>>> -provider-policy ${range;[==,=+)}
>>>>
>>>>
>>>>
>>>> Specifically, the import-package item can end up with a narrow range as
>>>> something like org.apache.sling.whatever; version="[2.4, 2.5)" for the
>>>> importing bundles which can leads to troubles when the next minor change
>>>> requires the exported package to get bumped to "2.5.0" since that
>>> exported
>>>> package number no longer satisfies the import package range. This would
>>>> mean that all the "importing" bundles would have to change as well and
>>> you
>>>> end up with a cascade of new releases just for some minor change in the
>>>> "consumer" part of the exported package even if the changes were trivial
>>>> and backward compatible.
>>>>
>>>> Regards,
>>>> -Eric
>>>>
>>>>
>>>>
>>>> On Tue, Jun 29, 2021 at 8:54 AM Carsten Ziegeler <cz...@apache.org>
>>>> wrote:
>>>>
>>>>> I don't think that not mixing consumer and provider interfaces is a best
>>>>> practice.
>>>>>
>>>>> The OSGi specs - which I think are usually following best practices -
>>>>> are mixing them. For example event admin where the event admin interface
>>>>> is in the same package as the event handler.
>>>>>
>>>>> The markers actually help putting those interfaces into the same
>>>>> package. In above example you can change the event admin interface
>>>>> without breaking the event handler.
>>>>>
>>>>> The framework api does the same, confgig admin etc.
>>>>>
>>>>> It's good to split packages based on purpose and usage. For example to
>>>>> move SPI interfaces into a separate package.
>>>>>
>>>>> Regards
>>>>> Carsten
>>>>>
>>>>> Am 29.06.2021 um 16:49 schrieb Bertrand Delacretaz:
>>>>>> Hi Konrad,
>>>>>>
>>>>>> On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de>
>>> wrote:
>>>>>>> - Please don't mix Consumer and Provider interfaces in the same
>>> package
>>>>>>> (
>>>>>
>>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
>>>>>>> and
>>>>>>>
>>>>>
>>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions
>>>>> )
>>>>>>> as that enforces updates to break more consumers than necessary....
>>>>>>
>>>>>> Could you elaborate on that? The issue is not obvious to me.
>>>>>>
>>>>>> More generally, I think it would be useful for us to document best
>>>>>> practices around Consumer and Provider interfaces.
>>>>>>
>>>>>> If someone has links to such best practices that would be great,
>>>>>> otherwise feel free to add some notes in response to this message and
>>>>>> I'll write something up for https://sling.apache.org/
>>>>>>
>>>>>> -Bertrand
>>>>>>
>>>>>
>>>>> --
>>>>> --
>>>>> Carsten Ziegeler
>>>>> Adobe Research Switzerland
>>>>> cziegeler@apache.org
>>>>>
>>>
>>>
>
> --
> --
> Carsten Ziegeler
> Adobe Research Switzerland
> cziegeler@apache.org
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Carsten Ziegeler <cz...@apache.org>.
You can regard provider type as the implementor of the api of a package
whereas everything marked as consumer type is implemented by users of
that api.
So yes, if you make any changes to that package, add a new interface,
add a new method etc., you need to adjust the implementor.
For example, if you add a new consumer interface, it will break the
implementor - but it is highly likely that the implementor needs to do
something with that new interface, like picking up all services
implementing that new interface and eventually invoking those. So it is
natural that the implementation needs to be updated.
Of course, if the change is about static utility code, then yes this is
not breaking the implementor. But I consider this an edge case.
You can't make changes to a consumer type (unless you add a default
method to an interface) as this will break all clients.
So again, many use cases for putting consumer and provider type
interfaces into a single package are totally valid and good api style.
Moving api artifically into separate packages just because of the fear
that changes require to update the implementation, can create a bad api
experience.
Side note, if you have api and the implementor in the same module, the
whole discussion goes away. Which is another fun discussion :)
Regards
Carsten
Am 29.06.2021 um 22:48 schrieb Eric Norman:
> Hi Konrad,
>
> Can you confirm that mixing your 3rd scenario (as below) with any of the
> other 3 within the same bundle also results in the narrow version range for
> that imported package?
>
> @ProviderType 1.1.0 yes
> [1.1, 1.2) Provider
>
> The point being that as soon as you implement any ProviderType interface in
> your bundle then you can't add new (unrelated?) classes to that exported
> package or change any ConsumerType classes in that exported package because
> those changes would result in a bump of the exported minor version number.
> The imported package range for any bundles that were built against the
> previous release would no longer match the narrow version range exported by
> the new release.
>
> This is the scenario that was discussed with SLING-10031
>
>
>
>
>
> On Tue, Jun 29, 2021 at 12:28 PM Konrad Windszus <ko...@gmx.de> wrote:
>
>> Hi, sorry for the confusion here, I think I may be just wrong.
>>
>> From the standard policies from Bnd I do no longer think mixing Consumer
>> and Provider in one package can lead to breaking users of the API more
>> easily.
>>
>> Let's quickly recall what the rules are:
>>
>> Rules for Exported Versions
>> ====
>>
>> ConsumerType
>> Every binary incompatible change requires an increment on the major
>> version.
>>
>> ProviderType
>> Every binary incompatible change requires (at least) an increment on the
>> minor version.
>>
>> Rules for Imported Versions
>> =====
>>
>> For each interface/ non final class it is stated, whether it is supported
>> to be implemented/extended by Consumers (and providers, the default) or by
>> Providers only. That information together with the information whether the
>> interface is just used or really implemented determines the version-range
>> of the import-package statement:
>>
>> Annotation on class/interface | Version Implemented | Import-Package
>> Version Range | Versioning Policy
>> @ConsumerType 1.1.0 yes
>> [1.1, 2.0) Consumer
>> @ConsumerType 1.1.0 no
>> [1.1, 2.0) Consumer
>> @ProviderType 1.1.0 yes
>> [1.1, 1.2) Provider
>> @ProviderType 1.1.0 no
>> [1.1, 2.0) Consumer
>>
>> Those policies can be overwritten via the instruction
>> http://bnd.bndtools.org/instructions/consumer_policy.html and
>> http://bnd.bndtools.org/instructions/provider_policy.html.
>> From those rules I cannot construct a usage which would point at splitting
>> Consumer and Provider types.
>>
>> I think my confusion initially came from
>> https://github.com/apache/felix-dev/blob/057bb85d7d496671755cd53cffc9e91a17c1d17c/tools/osgicheck-maven-plugin/src/main/java/org/apache/felix/maven/osgicheck/impl/checks/ConsumerProviderTypeCheck.java#L115
>> @Carsten: Do you remember why that usage leads to an error in
>> osgicheck-maven-plugin?
>>
>> Konrad
>>
>>
>>
>>> On 29. Jun 2021, at 20:23, Eric Norman <en...@apache.org> wrote:
>>>
>>> I haven't looked at this too closely, but do you think that there could
>> be
>>> some benefit to keeping them in separate packages if you expect the
>>> consumer and provider apis to evolve at a different pace?
>>>
>>> If I recall correctly, the bundles that import and use stuff from a
>> package
>>> that contains both consumer and provider classes may get a too specific
>>> range for the import package range.
>>> This has to do with bndlib choosing the "provider-policy" instead of the
>>> "consumer-policy" when calculating the version ranges.
>>>
>>> From what I read, the default definitions for bnd are:
>>>
>>> -consumer-policy ${range;[==,+)}
>>> -provider-policy ${range;[==,=+)}
>>>
>>>
>>>
>>> Specifically, the import-package item can end up with a narrow range as
>>> something like org.apache.sling.whatever; version="[2.4, 2.5)" for the
>>> importing bundles which can leads to troubles when the next minor change
>>> requires the exported package to get bumped to "2.5.0" since that
>> exported
>>> package number no longer satisfies the import package range. This would
>>> mean that all the "importing" bundles would have to change as well and
>> you
>>> end up with a cascade of new releases just for some minor change in the
>>> "consumer" part of the exported package even if the changes were trivial
>>> and backward compatible.
>>>
>>> Regards,
>>> -Eric
>>>
>>>
>>>
>>> On Tue, Jun 29, 2021 at 8:54 AM Carsten Ziegeler <cz...@apache.org>
>>> wrote:
>>>
>>>> I don't think that not mixing consumer and provider interfaces is a best
>>>> practice.
>>>>
>>>> The OSGi specs - which I think are usually following best practices -
>>>> are mixing them. For example event admin where the event admin interface
>>>> is in the same package as the event handler.
>>>>
>>>> The markers actually help putting those interfaces into the same
>>>> package. In above example you can change the event admin interface
>>>> without breaking the event handler.
>>>>
>>>> The framework api does the same, confgig admin etc.
>>>>
>>>> It's good to split packages based on purpose and usage. For example to
>>>> move SPI interfaces into a separate package.
>>>>
>>>> Regards
>>>> Carsten
>>>>
>>>> Am 29.06.2021 um 16:49 schrieb Bertrand Delacretaz:
>>>>> Hi Konrad,
>>>>>
>>>>> On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de>
>> wrote:
>>>>>> - Please don't mix Consumer and Provider interfaces in the same
>> package
>>>>>> (
>>>>
>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
>>>>>> and
>>>>>>
>>>>
>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions
>>>> )
>>>>>> as that enforces updates to break more consumers than necessary....
>>>>>
>>>>> Could you elaborate on that? The issue is not obvious to me.
>>>>>
>>>>> More generally, I think it would be useful for us to document best
>>>>> practices around Consumer and Provider interfaces.
>>>>>
>>>>> If someone has links to such best practices that would be great,
>>>>> otherwise feel free to add some notes in response to this message and
>>>>> I'll write something up for https://sling.apache.org/
>>>>>
>>>>> -Bertrand
>>>>>
>>>>
>>>> --
>>>> --
>>>> Carsten Ziegeler
>>>> Adobe Research Switzerland
>>>> cziegeler@apache.org
>>>>
>>
>>
>
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Eric Norman <en...@apache.org>.
Hi Konrad,
Can you confirm that mixing your 3rd scenario (as below) with any of the
other 3 within the same bundle also results in the narrow version range for
that imported package?
@ProviderType 1.1.0 yes
[1.1, 1.2) Provider
The point being that as soon as you implement any ProviderType interface in
your bundle then you can't add new (unrelated?) classes to that exported
package or change any ConsumerType classes in that exported package because
those changes would result in a bump of the exported minor version number.
The imported package range for any bundles that were built against the
previous release would no longer match the narrow version range exported by
the new release.
This is the scenario that was discussed with SLING-10031
On Tue, Jun 29, 2021 at 12:28 PM Konrad Windszus <ko...@gmx.de> wrote:
> Hi, sorry for the confusion here, I think I may be just wrong.
>
> From the standard policies from Bnd I do no longer think mixing Consumer
> and Provider in one package can lead to breaking users of the API more
> easily.
>
> Let's quickly recall what the rules are:
>
> Rules for Exported Versions
> ====
>
> ConsumerType
> Every binary incompatible change requires an increment on the major
> version.
>
> ProviderType
> Every binary incompatible change requires (at least) an increment on the
> minor version.
>
> Rules for Imported Versions
> =====
>
> For each interface/ non final class it is stated, whether it is supported
> to be implemented/extended by Consumers (and providers, the default) or by
> Providers only. That information together with the information whether the
> interface is just used or really implemented determines the version-range
> of the import-package statement:
>
> Annotation on class/interface | Version Implemented | Import-Package
> Version Range | Versioning Policy
> @ConsumerType 1.1.0 yes
> [1.1, 2.0) Consumer
> @ConsumerType 1.1.0 no
> [1.1, 2.0) Consumer
> @ProviderType 1.1.0 yes
> [1.1, 1.2) Provider
> @ProviderType 1.1.0 no
> [1.1, 2.0) Consumer
>
> Those policies can be overwritten via the instruction
> http://bnd.bndtools.org/instructions/consumer_policy.html and
> http://bnd.bndtools.org/instructions/provider_policy.html.
> From those rules I cannot construct a usage which would point at splitting
> Consumer and Provider types.
>
> I think my confusion initially came from
> https://github.com/apache/felix-dev/blob/057bb85d7d496671755cd53cffc9e91a17c1d17c/tools/osgicheck-maven-plugin/src/main/java/org/apache/felix/maven/osgicheck/impl/checks/ConsumerProviderTypeCheck.java#L115
> @Carsten: Do you remember why that usage leads to an error in
> osgicheck-maven-plugin?
>
> Konrad
>
>
>
> > On 29. Jun 2021, at 20:23, Eric Norman <en...@apache.org> wrote:
> >
> > I haven't looked at this too closely, but do you think that there could
> be
> > some benefit to keeping them in separate packages if you expect the
> > consumer and provider apis to evolve at a different pace?
> >
> > If I recall correctly, the bundles that import and use stuff from a
> package
> > that contains both consumer and provider classes may get a too specific
> > range for the import package range.
> > This has to do with bndlib choosing the "provider-policy" instead of the
> > "consumer-policy" when calculating the version ranges.
> >
> > From what I read, the default definitions for bnd are:
> >
> > -consumer-policy ${range;[==,+)}
> > -provider-policy ${range;[==,=+)}
> >
> >
> >
> > Specifically, the import-package item can end up with a narrow range as
> > something like org.apache.sling.whatever; version="[2.4, 2.5)" for the
> > importing bundles which can leads to troubles when the next minor change
> > requires the exported package to get bumped to "2.5.0" since that
> exported
> > package number no longer satisfies the import package range. This would
> > mean that all the "importing" bundles would have to change as well and
> you
> > end up with a cascade of new releases just for some minor change in the
> > "consumer" part of the exported package even if the changes were trivial
> > and backward compatible.
> >
> > Regards,
> > -Eric
> >
> >
> >
> > On Tue, Jun 29, 2021 at 8:54 AM Carsten Ziegeler <cz...@apache.org>
> > wrote:
> >
> >> I don't think that not mixing consumer and provider interfaces is a best
> >> practice.
> >>
> >> The OSGi specs - which I think are usually following best practices -
> >> are mixing them. For example event admin where the event admin interface
> >> is in the same package as the event handler.
> >>
> >> The markers actually help putting those interfaces into the same
> >> package. In above example you can change the event admin interface
> >> without breaking the event handler.
> >>
> >> The framework api does the same, confgig admin etc.
> >>
> >> It's good to split packages based on purpose and usage. For example to
> >> move SPI interfaces into a separate package.
> >>
> >> Regards
> >> Carsten
> >>
> >> Am 29.06.2021 um 16:49 schrieb Bertrand Delacretaz:
> >>> Hi Konrad,
> >>>
> >>> On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de>
> wrote:
> >>>> - Please don't mix Consumer and Provider interfaces in the same
> package
> >>>> (
> >>
> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
> >>>> and
> >>>>
> >>
> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions
> >> )
> >>>> as that enforces updates to break more consumers than necessary....
> >>>
> >>> Could you elaborate on that? The issue is not obvious to me.
> >>>
> >>> More generally, I think it would be useful for us to document best
> >>> practices around Consumer and Provider interfaces.
> >>>
> >>> If someone has links to such best practices that would be great,
> >>> otherwise feel free to add some notes in response to this message and
> >>> I'll write something up for https://sling.apache.org/
> >>>
> >>> -Bertrand
> >>>
> >>
> >> --
> >> --
> >> Carsten Ziegeler
> >> Adobe Research Switzerland
> >> cziegeler@apache.org
> >>
>
>
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Carsten Ziegeler <cz...@apache.org>.
Hi Konrad,
that check in the osgicheck maven plugin checks a single class whether
it contains both annotations - not a whole package
Regards
Carsten
Am 29.06.2021 um 21:27 schrieb Konrad Windszus:
> Hi, sorry for the confusion here, I think I may be just wrong.
>
> From the standard policies from Bnd I do no longer think mixing Consumer and Provider in one package can lead to breaking users of the API more easily.
>
> Let's quickly recall what the rules are:
>
> Rules for Exported Versions
> ====
>
> ConsumerType
> Every binary incompatible change requires an increment on the major version.
>
> ProviderType
> Every binary incompatible change requires (at least) an increment on the minor version.
>
> Rules for Imported Versions
> =====
>
> For each interface/ non final class it is stated, whether it is supported to be implemented/extended by Consumers (and providers, the default) or by Providers only. That information together with the information whether the interface is just used or really implemented determines the version-range of the import-package statement:
>
> Annotation on class/interface | Version Implemented | Import-Package Version Range | Versioning Policy
> @ConsumerType 1.1.0 yes [1.1, 2.0) Consumer
> @ConsumerType 1.1.0 no [1.1, 2.0) Consumer
> @ProviderType 1.1.0 yes [1.1, 1.2) Provider
> @ProviderType 1.1.0 no [1.1, 2.0) Consumer
>
> Those policies can be overwritten via the instruction http://bnd.bndtools.org/instructions/consumer_policy.html and http://bnd.bndtools.org/instructions/provider_policy.html.
> From those rules I cannot construct a usage which would point at splitting Consumer and Provider types.
>
> I think my confusion initially came from https://github.com/apache/felix-dev/blob/057bb85d7d496671755cd53cffc9e91a17c1d17c/tools/osgicheck-maven-plugin/src/main/java/org/apache/felix/maven/osgicheck/impl/checks/ConsumerProviderTypeCheck.java#L115
> @Carsten: Do you remember why that usage leads to an error in osgicheck-maven-plugin?
>
> Konrad
>
>
>
>> On 29. Jun 2021, at 20:23, Eric Norman <en...@apache.org> wrote:
>>
>> I haven't looked at this too closely, but do you think that there could be
>> some benefit to keeping them in separate packages if you expect the
>> consumer and provider apis to evolve at a different pace?
>>
>> If I recall correctly, the bundles that import and use stuff from a package
>> that contains both consumer and provider classes may get a too specific
>> range for the import package range.
>> This has to do with bndlib choosing the "provider-policy" instead of the
>> "consumer-policy" when calculating the version ranges.
>>
>> From what I read, the default definitions for bnd are:
>>
>> -consumer-policy ${range;[==,+)}
>> -provider-policy ${range;[==,=+)}
>>
>>
>>
>> Specifically, the import-package item can end up with a narrow range as
>> something like org.apache.sling.whatever; version="[2.4, 2.5)" for the
>> importing bundles which can leads to troubles when the next minor change
>> requires the exported package to get bumped to "2.5.0" since that exported
>> package number no longer satisfies the import package range. This would
>> mean that all the "importing" bundles would have to change as well and you
>> end up with a cascade of new releases just for some minor change in the
>> "consumer" part of the exported package even if the changes were trivial
>> and backward compatible.
>>
>> Regards,
>> -Eric
>>
>>
>>
>> On Tue, Jun 29, 2021 at 8:54 AM Carsten Ziegeler <cz...@apache.org>
>> wrote:
>>
>>> I don't think that not mixing consumer and provider interfaces is a best
>>> practice.
>>>
>>> The OSGi specs - which I think are usually following best practices -
>>> are mixing them. For example event admin where the event admin interface
>>> is in the same package as the event handler.
>>>
>>> The markers actually help putting those interfaces into the same
>>> package. In above example you can change the event admin interface
>>> without breaking the event handler.
>>>
>>> The framework api does the same, confgig admin etc.
>>>
>>> It's good to split packages based on purpose and usage. For example to
>>> move SPI interfaces into a separate package.
>>>
>>> Regards
>>> Carsten
>>>
>>> Am 29.06.2021 um 16:49 schrieb Bertrand Delacretaz:
>>>> Hi Konrad,
>>>>
>>>> On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de> wrote:
>>>>> - Please don't mix Consumer and Provider interfaces in the same package
>>>>> (
>>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
>>>>> and
>>>>>
>>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions
>>> )
>>>>> as that enforces updates to break more consumers than necessary....
>>>>
>>>> Could you elaborate on that? The issue is not obvious to me.
>>>>
>>>> More generally, I think it would be useful for us to document best
>>>> practices around Consumer and Provider interfaces.
>>>>
>>>> If someone has links to such best practices that would be great,
>>>> otherwise feel free to add some notes in response to this message and
>>>> I'll write something up for https://sling.apache.org/
>>>>
>>>> -Bertrand
>>>>
>>>
>>> --
>>> --
>>> Carsten Ziegeler
>>> Adobe Research Switzerland
>>> cziegeler@apache.org
>>>
>
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Konrad Windszus <ko...@gmx.de>.
Hi, sorry for the confusion here, I think I may be just wrong.
From the standard policies from Bnd I do no longer think mixing Consumer and Provider in one package can lead to breaking users of the API more easily.
Let's quickly recall what the rules are:
Rules for Exported Versions
====
ConsumerType
Every binary incompatible change requires an increment on the major version.
ProviderType
Every binary incompatible change requires (at least) an increment on the minor version.
Rules for Imported Versions
=====
For each interface/ non final class it is stated, whether it is supported to be implemented/extended by Consumers (and providers, the default) or by Providers only. That information together with the information whether the interface is just used or really implemented determines the version-range of the import-package statement:
Annotation on class/interface | Version Implemented | Import-Package Version Range | Versioning Policy
@ConsumerType 1.1.0 yes [1.1, 2.0) Consumer
@ConsumerType 1.1.0 no [1.1, 2.0) Consumer
@ProviderType 1.1.0 yes [1.1, 1.2) Provider
@ProviderType 1.1.0 no [1.1, 2.0) Consumer
Those policies can be overwritten via the instruction http://bnd.bndtools.org/instructions/consumer_policy.html and http://bnd.bndtools.org/instructions/provider_policy.html.
From those rules I cannot construct a usage which would point at splitting Consumer and Provider types.
I think my confusion initially came from https://github.com/apache/felix-dev/blob/057bb85d7d496671755cd53cffc9e91a17c1d17c/tools/osgicheck-maven-plugin/src/main/java/org/apache/felix/maven/osgicheck/impl/checks/ConsumerProviderTypeCheck.java#L115
@Carsten: Do you remember why that usage leads to an error in osgicheck-maven-plugin?
Konrad
> On 29. Jun 2021, at 20:23, Eric Norman <en...@apache.org> wrote:
>
> I haven't looked at this too closely, but do you think that there could be
> some benefit to keeping them in separate packages if you expect the
> consumer and provider apis to evolve at a different pace?
>
> If I recall correctly, the bundles that import and use stuff from a package
> that contains both consumer and provider classes may get a too specific
> range for the import package range.
> This has to do with bndlib choosing the "provider-policy" instead of the
> "consumer-policy" when calculating the version ranges.
>
> From what I read, the default definitions for bnd are:
>
> -consumer-policy ${range;[==,+)}
> -provider-policy ${range;[==,=+)}
>
>
>
> Specifically, the import-package item can end up with a narrow range as
> something like org.apache.sling.whatever; version="[2.4, 2.5)" for the
> importing bundles which can leads to troubles when the next minor change
> requires the exported package to get bumped to "2.5.0" since that exported
> package number no longer satisfies the import package range. This would
> mean that all the "importing" bundles would have to change as well and you
> end up with a cascade of new releases just for some minor change in the
> "consumer" part of the exported package even if the changes were trivial
> and backward compatible.
>
> Regards,
> -Eric
>
>
>
> On Tue, Jun 29, 2021 at 8:54 AM Carsten Ziegeler <cz...@apache.org>
> wrote:
>
>> I don't think that not mixing consumer and provider interfaces is a best
>> practice.
>>
>> The OSGi specs - which I think are usually following best practices -
>> are mixing them. For example event admin where the event admin interface
>> is in the same package as the event handler.
>>
>> The markers actually help putting those interfaces into the same
>> package. In above example you can change the event admin interface
>> without breaking the event handler.
>>
>> The framework api does the same, confgig admin etc.
>>
>> It's good to split packages based on purpose and usage. For example to
>> move SPI interfaces into a separate package.
>>
>> Regards
>> Carsten
>>
>> Am 29.06.2021 um 16:49 schrieb Bertrand Delacretaz:
>>> Hi Konrad,
>>>
>>> On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de> wrote:
>>>> - Please don't mix Consumer and Provider interfaces in the same package
>>>> (
>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
>>>> and
>>>>
>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions
>> )
>>>> as that enforces updates to break more consumers than necessary....
>>>
>>> Could you elaborate on that? The issue is not obvious to me.
>>>
>>> More generally, I think it would be useful for us to document best
>>> practices around Consumer and Provider interfaces.
>>>
>>> If someone has links to such best practices that would be great,
>>> otherwise feel free to add some notes in response to this message and
>>> I'll write something up for https://sling.apache.org/
>>>
>>> -Bertrand
>>>
>>
>> --
>> --
>> Carsten Ziegeler
>> Adobe Research Switzerland
>> cziegeler@apache.org
>>
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Eric Norman <en...@apache.org>.
I haven't looked at this too closely, but do you think that there could be
some benefit to keeping them in separate packages if you expect the
consumer and provider apis to evolve at a different pace?
If I recall correctly, the bundles that import and use stuff from a package
that contains both consumer and provider classes may get a too specific
range for the import package range.
This has to do with bndlib choosing the "provider-policy" instead of the
"consumer-policy" when calculating the version ranges.
From what I read, the default definitions for bnd are:
-consumer-policy ${range;[==,+)}
-provider-policy ${range;[==,=+)}
Specifically, the import-package item can end up with a narrow range as
something like org.apache.sling.whatever; version="[2.4, 2.5)" for the
importing bundles which can leads to troubles when the next minor change
requires the exported package to get bumped to "2.5.0" since that exported
package number no longer satisfies the import package range. This would
mean that all the "importing" bundles would have to change as well and you
end up with a cascade of new releases just for some minor change in the
"consumer" part of the exported package even if the changes were trivial
and backward compatible.
Regards,
-Eric
On Tue, Jun 29, 2021 at 8:54 AM Carsten Ziegeler <cz...@apache.org>
wrote:
> I don't think that not mixing consumer and provider interfaces is a best
> practice.
>
> The OSGi specs - which I think are usually following best practices -
> are mixing them. For example event admin where the event admin interface
> is in the same package as the event handler.
>
> The markers actually help putting those interfaces into the same
> package. In above example you can change the event admin interface
> without breaking the event handler.
>
> The framework api does the same, confgig admin etc.
>
> It's good to split packages based on purpose and usage. For example to
> move SPI interfaces into a separate package.
>
> Regards
> Carsten
>
> Am 29.06.2021 um 16:49 schrieb Bertrand Delacretaz:
> > Hi Konrad,
> >
> > On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de> wrote:
> >> - Please don't mix Consumer and Provider interfaces in the same package
> >> (
> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
> >> and
> >>
> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions
> )
> >> as that enforces updates to break more consumers than necessary....
> >
> > Could you elaborate on that? The issue is not obvious to me.
> >
> > More generally, I think it would be useful for us to document best
> > practices around Consumer and Provider interfaces.
> >
> > If someone has links to such best practices that would be great,
> > otherwise feel free to add some notes in response to this message and
> > I'll write something up for https://sling.apache.org/
> >
> > -Bertrand
> >
>
> --
> --
> Carsten Ziegeler
> Adobe Research Switzerland
> cziegeler@apache.org
>
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Carsten Ziegeler <cz...@apache.org>.
I don't think that not mixing consumer and provider interfaces is a best
practice.
The OSGi specs - which I think are usually following best practices -
are mixing them. For example event admin where the event admin interface
is in the same package as the event handler.
The markers actually help putting those interfaces into the same
package. In above example you can change the event admin interface
without breaking the event handler.
The framework api does the same, confgig admin etc.
It's good to split packages based on purpose and usage. For example to
move SPI interfaces into a separate package.
Regards
Carsten
Am 29.06.2021 um 16:49 schrieb Bertrand Delacretaz:
> Hi Konrad,
>
> On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de> wrote:
>> - Please don't mix Consumer and Provider interfaces in the same package
>> (https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
>> and
>> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions)
>> as that enforces updates to break more consumers than necessary....
>
> Could you elaborate on that? The issue is not obvious to me.
>
> More generally, I think it would be useful for us to document best
> practices around Consumer and Provider interfaces.
>
> If someone has links to such best practices that would be great,
> otherwise feel free to add some notes in response to this message and
> I'll write something up for https://sling.apache.org/
>
> -Bertrand
>
--
--
Carsten Ziegeler
Adobe Research Switzerland
cziegeler@apache.org
Re: [osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by David Bosschaert <da...@gmail.com>.
Hi Bertrand,
The OSGi semantic versioning whitepaper has a lot of info about this:
https://docs.osgi.org/whitepaper/semantic-versioning/
Best regards,
David
On Tue, 29 Jun 2021 at 15:49, Bertrand Delacretaz <bd...@apache.org>
wrote:
> Hi Konrad,
>
> On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de> wrote:
> > - Please don't mix Consumer and Provider interfaces in the same package
> > (
> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
> > and
> >
> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions
> )
> > as that enforces updates to break more consumers than necessary....
>
> Could you elaborate on that? The issue is not obvious to me.
>
> More generally, I think it would be useful for us to document best
> practices around Consumer and Provider interfaces.
>
> If someone has links to such best practices that would be great,
> otherwise feel free to add some notes in response to this message and
> I'll write something up for https://sling.apache.org/
>
> -Bertrand
>
[osgi] mixing Consumer and Provider interfaces + best practices
around Consumer/Provider
Posted by Bertrand Delacretaz <bd...@apache.org>.
Hi Konrad,
On Tue, Jun 29, 2021 at 3:04 PM Konrad Windszus <ko...@gmx.de> wrote:
> - Please don't mix Consumer and Provider interfaces in the same package
> (https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator
> and
> https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions)
> as that enforces updates to break more consumers than necessary....
Could you elaborate on that? The issue is not obvious to me.
More generally, I think it would be useful for us to document best
practices around Consumer and Provider interfaces.
If someone has links to such best practices that would be great,
otherwise feel free to add some notes in response to this message and
I'll write something up for https://sling.apache.org/
-Bertrand
Re: [CANCELLED] [VOTE] Release Apache Sling Sitemap version 1.0.0
Posted by Dirk Rudolph <di...@gmail.com>.
Thanks Robert, I will do that.
As suggested, I separated API and SPI from each other.
I also updated the badges of the module, however I will defer fully
updating the sling aggregator until javadoc and maven central links
are working as well.
Any other feedback, or issues I should address? If not, I will start a
new vote later today.
Thanks,
Dirk
On Wed, 30 Jun 2021 at 11:23, Robert Munteanu <ro...@apache.org> wrote:
>
> On Tue, 2021-06-29 at 15:27 +0200, Dirk Rudolph wrote:
> > One question though, according to
> > https://sling.apache.org/documentation/development/release-management.html#wait-for-the-results
> > I should not reuse the version number. Is that the case for the first
> > version/1.0.0 as well or would it be safe to assume no one copied the
> > binaries around yet?
>
> We should use a new version number for 1.0.0 releases as well. We did
> that several times in the past, especially when we forgot to set proper
> SCM entries in the POM :-)
>
> Thanks,
> Robert
>
Re: [CANCELLED] [VOTE] Release Apache Sling Sitemap version 1.0.0
Posted by Robert Munteanu <ro...@apache.org>.
On Tue, 2021-06-29 at 15:27 +0200, Dirk Rudolph wrote:
> One question though, according to
> https://sling.apache.org/documentation/development/release-management.html#wait-for-the-results
> I should not reuse the version number. Is that the case for the first
> version/1.0.0 as well or would it be safe to assume no one copied the
> binaries around yet?
We should use a new version number for 1.0.0 releases as well. We did
that several times in the past, especially when we forgot to set proper
SCM entries in the POM :-)
Thanks,
Robert
Re: [CANCELLED] [VOTE] Release Apache Sling Sitemap version 1.0.0
Posted by Dirk Rudolph <di...@apache.org>.
Thank you Konrad.
I agree with your points and due to the nature of the last 3 I hereby
cancel the release.
One question though, according to
https://sling.apache.org/documentation/development/release-management.html#wait-for-the-results
I should not reuse the version number. Is that the case for the first
version/1.0.0 as well or would it be safe to assume no one copied the
binaries around yet?
> When restarting a vote version numbers must not be reused, since binaries might have already been copied around.
Thanks,
Dirk
On Tue, 29 Jun 2021 at 15:04, Konrad Windszus <ko...@gmx.de> wrote:
>
> Hi Dirk,
> I have some general remarks (mostly minor ones but one should be IMHO fixed before release)
> - Can you update https://sling.apache.org/repolist.html as the new Github repo doesn't appear there yet.
> - Please also use the most recent parent version (43 at the time of writing). A lot of plugin configuration and the profile named "autoInstallBundle" doesn't need to be repeated per module as it is inherited from parent.
> - Please also make sure to include all badges used in other modules in the readme via https://github.com/apache/sling-aggregator/blob/master/generate-badges.groovy.
> - Please don't mix Consumer and Provider interfaces in the same package (https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator and https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions) as that enforces updates to break more consumers than necessary. This should be done prior to the 1.0 release.
> - SitemapGenerator.GenerationContext should rather be named SitemapGenerator.Context or SitemapGenerator.GeneratorContext.
> - Make SitemapUtil final to ease semantic versioning
>
>
> Apart from that looks really nice and looking forward to the release.
> Thanks,
> Konrad
>
>
>
> > On 28. Jun 2021, at 13:20, Dirk Rudolph <di...@apache.org> wrote:
> >
> > Hi,
> >
> > We solved 1 issues in this release:
> > https://issues.apache.org/jira/projects/SLING/versions/12350352
> >
> > Staging repository:
> > https://repository.apache.org/content/repositories/orgapachesling-2484
> >
> > You can use this UNIX script to download the release and verify the signatures:
> > https://gitbox.apache.org/repos/asf?p=sling-tooling-release.git;a=blob;f=check_staged_release.sh;hb=HEAD
> >
> > Usage:
> > sh check_staged_release.sh 2484 /tmp/sling-staging
> >
> > Please vote to approve this release:
> >
> > [ ] +1 Approve the release
> > [ ] 0 Don't care
> > [ ] -1 Don't release, because ...
> >
> > This majority vote is open for at least 72 hours.
> >
> > - Dirk
>
Re: [VOTE] Release Apache Sling Sitemap version 1.0.0
Posted by Konrad Windszus <ko...@gmx.de>.
Hi Dirk,
I have some general remarks (mostly minor ones but one should be IMHO fixed before release)
- Can you update https://sling.apache.org/repolist.html as the new Github repo doesn't appear there yet.
- Please also use the most recent parent version (43 at the time of writing). A lot of plugin configuration and the profile named "autoInstallBundle" doesn't need to be repeated per module as it is inherited from parent.
- Please also make sure to include all badges used in other modules in the readme via https://github.com/apache/sling-aggregator/blob/master/generate-badges.groovy.
- Please don't mix Consumer and Provider interfaces in the same package (https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/generator and https://github.com/apache/sling-org-apache-sling-sitemap/tree/master/src/main/java/org/apache/sling/sitemap/builder/extensions) as that enforces updates to break more consumers than necessary. This should be done prior to the 1.0 release.
- SitemapGenerator.GenerationContext should rather be named SitemapGenerator.Context or SitemapGenerator.GeneratorContext.
- Make SitemapUtil final to ease semantic versioning
Apart from that looks really nice and looking forward to the release.
Thanks,
Konrad
> On 28. Jun 2021, at 13:20, Dirk Rudolph <di...@apache.org> wrote:
>
> Hi,
>
> We solved 1 issues in this release:
> https://issues.apache.org/jira/projects/SLING/versions/12350352
>
> Staging repository:
> https://repository.apache.org/content/repositories/orgapachesling-2484
>
> You can use this UNIX script to download the release and verify the signatures:
> https://gitbox.apache.org/repos/asf?p=sling-tooling-release.git;a=blob;f=check_staged_release.sh;hb=HEAD
>
> Usage:
> sh check_staged_release.sh 2484 /tmp/sling-staging
>
> Please vote to approve this release:
>
> [ ] +1 Approve the release
> [ ] 0 Don't care
> [ ] -1 Don't release, because ...
>
> This majority vote is open for at least 72 hours.
>
> - Dirk