You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@sling.apache.org by Konrad Windszus <kw...@apache.org> on 2025/07/21 07:17:28 UTC
Semantic Versioning: Promote unstable to stable API
Hi,
In the context of SLING-12861[1] the question arose how to promote an unstable (0.x versioned) package version to a stable one without breaking all consumers.
IIUC all bundle and package versions having major version 0 are considered preliminary [2] by baselining and therefore will never emit any errors even when modifying the API in a non backwards compatible way without modifying the version.
I raised a ticket with Bnd[3] but while waiting for an answer there I would like to know how the process used to be for other Sling modules in the past.
Thanks in advance for any input.
Konrad
1 - https://issues.apache.org/jira/browse/SLING-12861
2 - https://semver.org/#spec-item-4
3 - https://github.com/bndtools/bnd/issues/6691
Re: Semantic Versioning: Promote unstable to stable API
Posted by Carsten Ziegeler <cz...@apache.org>.
Yes, I would go with b) as well. Consumers can easily be fixed by rebuilding
Carsten
On 7/24/2025 1:19 PM, Konrad Windszus wrote:
> Hi,
> Thanks for the input. I agree with all you said.
> The question still remains what to do with packages with major version being 0 for several releases now.
> I see two options:
>
> a) leave with major version 0 (which will basically disable baselining and each modification might easily break consumers without any tooling support to check for that)
> b) Increase the major version to 1 and by that break all existing consumers
>
> In the long run I proposed a change in bnd, to not generate import-package version ranges for 0.x versions but that won’t help already existing consumers.
> I think we have to do b)!
>
> WDYT?
> Konrad
>
>
>> On 24. Jul 2025, at 12:57, Carsten Ziegeler <cz...@apache.org> wrote:
>>
>> Not sure if there is an answer that works for all. I would put a version on the exports - not putting one usually looks like a mistake :)
>>
>> An API should not be in an unstable state for a long time - hopefully you can validate your API before you do the first release. If you really need a release to validate, I would go with major version being 0 - clearly stating that things can break.
>>
>> But again, I think the mistake is to have it for too long in unstable.
>> Usually, if you have a stable API and things need to be fixed, you can do that and deprecate/phase out parts of the old API.
>> Waiting indefinitely to mark an API stable will not help with that.
>>
>> Regards
>> Carsten
>>
>> On 7/23/2025 6:01 PM, Robert Munteanu wrote:
>>> Hi,
>>> On Mon, 2025-07-21 at 09:17 +0200, Konrad Windszus wrote:
>>>> Hi,
>>>> In the context of SLING-12861[1] the question arose how to promote an
>>>> unstable (0.x versioned) package version to a stable one without
>>>> breaking all consumers.
>>>> IIUC all bundle and package versions having major version 0 are
>>>> considered preliminary [2] by baselining and therefore will never
>>>> emit any errors even when modifying the API in a non backwards
>>>> compatible way without modifying the version.
>>>> I raised a ticket with Bnd[3] but while waiting for an answer there I
>>>> would like to know how the process used to be for other Sling modules
>>>> in the past.
>>>> Thanks in advance for any input.
>>> I am not aware of history but I am in the same situation with the OAuth
>>> Client bundle which exports packages as 0.1 and marks them all as
>>> @ProviderType to generate narrow import ranges [4].
>>> Now I wonder if exporting packages without a version would be better
>>> rather than setting 0.x versions.
>>> Thanks,
>>> Robert
>>> [4]:
>>> https://github.com/apache/sling-org-apache-sling-auth-oauth-client?tab=readme-ov-file#apache-sling-oauth-20-client-with-oidc-support
>>
>> --
>> Carsten Ziegeler
>> Adobe
>> cziegeler@apache.org
>>
>>
>
--
Carsten Ziegeler
Adobe
cziegeler@apache.org
Re: Semantic Versioning: Promote unstable to stable API
Posted by Konrad Windszus <kw...@apache.org>.
Hi,
Thanks for the input. I agree with all you said.
The question still remains what to do with packages with major version being 0 for several releases now.
I see two options:
a) leave with major version 0 (which will basically disable baselining and each modification might easily break consumers without any tooling support to check for that)
b) Increase the major version to 1 and by that break all existing consumers
In the long run I proposed a change in bnd, to not generate import-package version ranges for 0.x versions but that won’t help already existing consumers.
I think we have to do b)!
WDYT?
Konrad
> On 24. Jul 2025, at 12:57, Carsten Ziegeler <cz...@apache.org> wrote:
>
> Not sure if there is an answer that works for all. I would put a version on the exports - not putting one usually looks like a mistake :)
>
> An API should not be in an unstable state for a long time - hopefully you can validate your API before you do the first release. If you really need a release to validate, I would go with major version being 0 - clearly stating that things can break.
>
> But again, I think the mistake is to have it for too long in unstable.
> Usually, if you have a stable API and things need to be fixed, you can do that and deprecate/phase out parts of the old API.
> Waiting indefinitely to mark an API stable will not help with that.
>
> Regards
> Carsten
>
> On 7/23/2025 6:01 PM, Robert Munteanu wrote:
>> Hi,
>> On Mon, 2025-07-21 at 09:17 +0200, Konrad Windszus wrote:
>>> Hi,
>>> In the context of SLING-12861[1] the question arose how to promote an
>>> unstable (0.x versioned) package version to a stable one without
>>> breaking all consumers.
>>> IIUC all bundle and package versions having major version 0 are
>>> considered preliminary [2] by baselining and therefore will never
>>> emit any errors even when modifying the API in a non backwards
>>> compatible way without modifying the version.
>>> I raised a ticket with Bnd[3] but while waiting for an answer there I
>>> would like to know how the process used to be for other Sling modules
>>> in the past.
>>> Thanks in advance for any input.
>> I am not aware of history but I am in the same situation with the OAuth
>> Client bundle which exports packages as 0.1 and marks them all as
>> @ProviderType to generate narrow import ranges [4].
>> Now I wonder if exporting packages without a version would be better
>> rather than setting 0.x versions.
>> Thanks,
>> Robert
>> [4]:
>> https://github.com/apache/sling-org-apache-sling-auth-oauth-client?tab=readme-ov-file#apache-sling-oauth-20-client-with-oidc-support
>
> --
> Carsten Ziegeler
> Adobe
> cziegeler@apache.org
>
>
Re: Semantic Versioning: Promote unstable to stable API
Posted by Carsten Ziegeler <cz...@apache.org>.
Not sure if there is an answer that works for all. I would put a version
on the exports - not putting one usually looks like a mistake :)
An API should not be in an unstable state for a long time - hopefully
you can validate your API before you do the first release. If you really
need a release to validate, I would go with major version being 0 -
clearly stating that things can break.
But again, I think the mistake is to have it for too long in unstable.
Usually, if you have a stable API and things need to be fixed, you can
do that and deprecate/phase out parts of the old API.
Waiting indefinitely to mark an API stable will not help with that.
Regards
Carsten
On 7/23/2025 6:01 PM, Robert Munteanu wrote:
> Hi,
>
> On Mon, 2025-07-21 at 09:17 +0200, Konrad Windszus wrote:
>> Hi,
>> In the context of SLING-12861[1] the question arose how to promote an
>> unstable (0.x versioned) package version to a stable one without
>> breaking all consumers.
>> IIUC all bundle and package versions having major version 0 are
>> considered preliminary [2] by baselining and therefore will never
>> emit any errors even when modifying the API in a non backwards
>> compatible way without modifying the version.
>> I raised a ticket with Bnd[3] but while waiting for an answer there I
>> would like to know how the process used to be for other Sling modules
>> in the past.
>> Thanks in advance for any input.
>
> I am not aware of history but I am in the same situation with the OAuth
> Client bundle which exports packages as 0.1 and marks them all as
> @ProviderType to generate narrow import ranges [4].
>
> Now I wonder if exporting packages without a version would be better
> rather than setting 0.x versions.
>
> Thanks,
> Robert
>
>
> [4]:
> https://github.com/apache/sling-org-apache-sling-auth-oauth-client?tab=readme-ov-file#apache-sling-oauth-20-client-with-oidc-support
--
Carsten Ziegeler
Adobe
cziegeler@apache.org
Re: Semantic Versioning: Promote unstable to stable API
Posted by Robert Munteanu <ro...@apache.org>.
Hi,
On Mon, 2025-07-21 at 09:17 +0200, Konrad Windszus wrote:
> Hi,
> In the context of SLING-12861[1] the question arose how to promote an
> unstable (0.x versioned) package version to a stable one without
> breaking all consumers.
> IIUC all bundle and package versions having major version 0 are
> considered preliminary [2] by baselining and therefore will never
> emit any errors even when modifying the API in a non backwards
> compatible way without modifying the version.
> I raised a ticket with Bnd[3] but while waiting for an answer there I
> would like to know how the process used to be for other Sling modules
> in the past.
> Thanks in advance for any input.
I am not aware of history but I am in the same situation with the OAuth
Client bundle which exports packages as 0.1 and marks them all as
@ProviderType to generate narrow import ranges [4].
Now I wonder if exporting packages without a version would be better
rather than setting 0.x versions.
Thanks,
Robert
[4]:
https://github.com/apache/sling-org-apache-sling-auth-oauth-client?tab=readme-ov-file#apache-sling-oauth-20-client-with-oidc-support