Re: Versioning scheme

[Volkan Yazıcı]

Interesting. Could you share a concrete example, please?

On Tue, Dec 12, 2023 at 8:16 PM Ralph Goers 
wrote:

> Maybe you could add comments to the schema to define what the enumerations
> are intended for and what effect they have on the release?
>
> Ralph
>
> > On Dec 12, 2023, at 10:13 AM, Volkan Yazıcı  wrote:
> >
> > Got it. I will land a log4j-changelog change accordingly, implement the
> CI
> > magic, and update the release instructions.
> >
> > On Tue, 12 Dec 2023 at 17:41, Piotr P. Karwasz 
> > wrote:
> >
> >> Hi Volkan,
> >>
> >> On Tue, 12 Dec 2023 at 17:00, Volkan Yazıcı  wrote:
> >>> Piotr, could you give me a well-defined formula of your desired
> >> versioning
> >>> scheme concerning minor/patch bumps?
> >>
> >> I agree with what Ralph proposed.
> >>
> >> What I don't agree with is the current practice to set up the **next**
> >> release version always to the next minor release (with an empty set of
> >> changes).
> >> I would set it to the next patch release and only transform it into a
> >> minor release if we add an `added` or `changed` changelog entry.
> >> As Ralph said, the CI could do it.
> >>
> >> Piotr
> >>
>
>

Re: Versioning scheme

[Ralph Goers]

Maybe you could add comments to the schema to define what the enumerations are 
intended for and what effect they have on the release?

Ralph

> On Dec 12, 2023, at 10:13 AM, Volkan Yazıcı  wrote:
> 
> Got it. I will land a log4j-changelog change accordingly, implement the CI
> magic, and update the release instructions.
> 
> On Tue, 12 Dec 2023 at 17:41, Piotr P. Karwasz 
> wrote:
> 
>> Hi Volkan,
>> 
>> On Tue, 12 Dec 2023 at 17:00, Volkan Yazıcı  wrote:
>>> Piotr, could you give me a well-defined formula of your desired
>> versioning
>>> scheme concerning minor/patch bumps?
>> 
>> I agree with what Ralph proposed.
>> 
>> What I don't agree with is the current practice to set up the **next**
>> release version always to the next minor release (with an empty set of
>> changes).
>> I would set it to the next patch release and only transform it into a
>> minor release if we add an `added` or `changed` changelog entry.
>> As Ralph said, the CI could do it.
>> 
>> Piotr
>> 

Re: Versioning scheme

[Volkan Yazıcı]

Got it. I will land a log4j-changelog change accordingly, implement the CI
magic, and update the release instructions.

On Tue, 12 Dec 2023 at 17:41, Piotr P. Karwasz 
wrote:

> Hi Volkan,
>
> On Tue, 12 Dec 2023 at 17:00, Volkan Yazıcı  wrote:
> > Piotr, could you give me a well-defined formula of your desired
> versioning
> > scheme concerning minor/patch bumps?
>
> I agree with what Ralph proposed.
>
> What I don't agree with is the current practice to set up the **next**
> release version always to the next minor release (with an empty set of
> changes).
> I would set it to the next patch release and only transform it into a
> minor release if we add an `added` or `changed` changelog entry.
> As Ralph said, the CI could do it.
>
> Piotr
>

Re: Versioning scheme

[Piotr P. Karwasz]

Hi Volkan,

On Tue, 12 Dec 2023 at 17:00, Volkan Yazıcı  wrote:
> Piotr, could you give me a well-defined formula of your desired versioning
> scheme concerning minor/patch bumps?

I agree with what Ralph proposed.

What I don't agree with is the current practice to set up the **next**
release version always to the next minor release (with an empty set of
changes).
I would set it to the next patch release and only transform it into a
minor release if we add an `added` or `changed` changelog entry.
As Ralph said, the CI could do it.

Piotr

Re: Versioning scheme

[Ralph Goers]

Yes.

Ralph

> On Dec 12, 2023, at 9:03 AM, Volkan Yazıcı  wrote:
> 
> Ralph, do you mean if all changes are a subset of bug fixes, deprecations,
> or updates, then it is a patch release?
> 
> On Tue, 12 Dec 2023 at 16:23, Ralph Goers 
> wrote:
> 
>> I have to agree with Piotr’s example. Simply upgrading a dependency
>> doesn’t, on its own, change any code in Log4j.
>> 
>> I see three possible solutions for this:
>> 
>> 1. Do not allow any dependency updates until a “scheduled” mentor release
>> (once every 2 or 3 months). Frankly I’d be fine with this except when a
>> dependency has a major security vulnerability.
>> 2. Change all dependency versions to be ranges such that they don’t
>> require a release for users to include new dependency releases.  (I cannot
>> really recommend doing this).
>> 3. Add a new type to represent dependency updates. This would also not
>> require a minor release. This is really the most appropriate fix as
>> updating a dependency is not a change to anything in Log4j.
>> 
>> I would suggest adding another enumeration named “update”.
>> 
>> Ralph
>> 
>>> On Dec 12, 2023, at 7:19 AM, Piotr P. Karwasz 
>> wrote:
>>> 
>>> Hi Volkan,
>>> 
>>> On Tue, 12 Dec 2023 at 13:02, Volkan Yazıcı > vol...@yazi.ci>> wrote:
 
 On Tue, Dec 12, 2023 at 11:47 AM Piotr P. Karwasz <
>> piotr.karw...@gmail.com>
 wrote:
 
> * we lack a way to classify dependency updates. A concrete example:
> did the Commons DBCP2 bump to 2.11.0 change anything in
> `log4j-jdbc-dbcp2`? I don't think so, the artifact compiles with
> version 2.2.0 of the artifact. We are only stating that
> `log4j-jdbc-dbcp2` will **also** work with version 2.11.0.
> 
 
 Exactly! Hence, it is clear that this is neither a bug fix, nor a
 deprecation. That is, there is no ambiguity that this goes into a minor
 release.
>>> 
>>> And here I don't agree. Dependabot upgrades provide **no** benefit to
>>> the generated JAR files. Even the bytecode is exactly the same as
>>> before the upgrade.
>>> 
>>> What these changes provide is part of our "Secure by default" or
>>> "Up-to-date by default" feature: Log4j artifacts will never freeze our
>>> clients dependencies and will work with the newest versions of the
>>> libraries we depend upon.
>>> 
>>> If you need to **manually** fix code for the upgrade to work (as you
>>> did for Jackson 2.16.0), then you can change the automatically
>>> generated entry from "fixed/upgraded" to "changed".
>>> 
> I don't think this warrants a minor version bump.
> 
 
 This is what I am trying to eliminate Piotr: opinions. When a person
>> starts
 thinking *"Shall this be a patch or minor release?"*, the outcome is
 inherently subjective. We cannot completely get rid of subjective
 assessment, but assist it with guardrails.
>>> 
>>> These guardrails seem to follow the easy path: let's just do minor
>>> releases, so nobody will tell us we are wrong. If you add ".0.0" to
>>> all Google Chrome versions, Chrome will also follow semver to the
>>> letter. It just loses the spirit.
>>> 
> The bump to JDK 17 was necessary, very useful for us, but users don't
> really care what JDK was used for compilation.
 
 
 What? Users, that is, developers using `logging-parent` as their parent
 project, do certainly care about this change. Why wouldn't they? This is
 *not* a simple change. It took us months to bump the compiler in Log4j.
>> I
 think your statement has an incorrect assumption on who the users of
 `logging-parent` are.
>>> 
>>> Sorry, I was still talking about Log4j. For `logging-parent` users the
>>> requirement to use JDK 17 is a minor change, but `log4j-core` users do
>>> not care what JDK we are using for compilation. Therefore the switch
>>> to JDK 17 for compilation is not reason enough to bump Log4j to
>>> 2.23.0.
>>> 
 I have the impression that you want to classify library updates that
>> don't
 disrupt the user experience as a patch release. If there is nothing
>> urgent
 about them, why do a patch release at all? Isn't the point of a patch
 release is to fix something, urgently? Piggybacking library updates into
 patch releases defeats the purpose of patch releases and makes the line
 between minor and patch releases blur, and that is the crux of our
 disagreement.
>>> 
>>> I would do a release at all if it only contains changes in the
>>> dependency versions. The only exception I would make is vulnerable
>>> dependencies, **if** we are affected by the vulnerability. If this is
>>> the case feel free to replace "fixed/upgraded" with "changed" in the
>>> changelog.
>>> 
>>> In case a dependency upgrade does not influence the bytecode (i.e. our
>>> artifacts still work with the old version), I would simply disregard
>>> the upgrade when computing the required version dump.
>>> 
>>> Piotr
>> 
>> 

Re: Versioning scheme

[Volkan Yazıcı]

Ralph, do you mean if all changes are a subset of bug fixes, deprecations,
or updates, then it is a patch release?

On Tue, 12 Dec 2023 at 16:23, Ralph Goers 
wrote:

> I have to agree with Piotr’s example. Simply upgrading a dependency
> doesn’t, on its own, change any code in Log4j.
>
> I see three possible solutions for this:
>
> 1. Do not allow any dependency updates until a “scheduled” mentor release
> (once every 2 or 3 months). Frankly I’d be fine with this except when a
> dependency has a major security vulnerability.
> 2. Change all dependency versions to be ranges such that they don’t
> require a release for users to include new dependency releases.  (I cannot
> really recommend doing this).
> 3. Add a new type to represent dependency updates. This would also not
> require a minor release. This is really the most appropriate fix as
> updating a dependency is not a change to anything in Log4j.
>
> I would suggest adding another enumeration named “update”.
>
> Ralph
>
> > On Dec 12, 2023, at 7:19 AM, Piotr P. Karwasz 
> wrote:
> >
> > Hi Volkan,
> >
> > On Tue, 12 Dec 2023 at 13:02, Volkan Yazıcı  vol...@yazi.ci>> wrote:
> >>
> >> On Tue, Dec 12, 2023 at 11:47 AM Piotr P. Karwasz <
> piotr.karw...@gmail.com>
> >> wrote:
> >>
> >>> * we lack a way to classify dependency updates. A concrete example:
> >>> did the Commons DBCP2 bump to 2.11.0 change anything in
> >>> `log4j-jdbc-dbcp2`? I don't think so, the artifact compiles with
> >>> version 2.2.0 of the artifact. We are only stating that
> >>> `log4j-jdbc-dbcp2` will **also** work with version 2.11.0.
> >>>
> >>
> >> Exactly! Hence, it is clear that this is neither a bug fix, nor a
> >> deprecation. That is, there is no ambiguity that this goes into a minor
> >> release.
> >
> > And here I don't agree. Dependabot upgrades provide **no** benefit to
> > the generated JAR files. Even the bytecode is exactly the same as
> > before the upgrade.
> >
> > What these changes provide is part of our "Secure by default" or
> > "Up-to-date by default" feature: Log4j artifacts will never freeze our
> > clients dependencies and will work with the newest versions of the
> > libraries we depend upon.
> >
> > If you need to **manually** fix code for the upgrade to work (as you
> > did for Jackson 2.16.0), then you can change the automatically
> > generated entry from "fixed/upgraded" to "changed".
> >
> >>> I don't think this warrants a minor version bump.
> >>>
> >>
> >> This is what I am trying to eliminate Piotr: opinions. When a person
> starts
> >> thinking *"Shall this be a patch or minor release?"*, the outcome is
> >> inherently subjective. We cannot completely get rid of subjective
> >> assessment, but assist it with guardrails.
> >
> > These guardrails seem to follow the easy path: let's just do minor
> > releases, so nobody will tell us we are wrong. If you add ".0.0" to
> > all Google Chrome versions, Chrome will also follow semver to the
> > letter. It just loses the spirit.
> >
> >>> The bump to JDK 17 was necessary, very useful for us, but users don't
> >>> really care what JDK was used for compilation.
> >>
> >>
> >> What? Users, that is, developers using `logging-parent` as their parent
> >> project, do certainly care about this change. Why wouldn't they? This is
> >> *not* a simple change. It took us months to bump the compiler in Log4j.
> I
> >> think your statement has an incorrect assumption on who the users of
> >> `logging-parent` are.
> >
> > Sorry, I was still talking about Log4j. For `logging-parent` users the
> > requirement to use JDK 17 is a minor change, but `log4j-core` users do
> > not care what JDK we are using for compilation. Therefore the switch
> > to JDK 17 for compilation is not reason enough to bump Log4j to
> > 2.23.0.
> >
> >> I have the impression that you want to classify library updates that
> don't
> >> disrupt the user experience as a patch release. If there is nothing
> urgent
> >> about them, why do a patch release at all? Isn't the point of a patch
> >> release is to fix something, urgently? Piggybacking library updates into
> >> patch releases defeats the purpose of patch releases and makes the line
> >> between minor and patch releases blur, and that is the crux of our
> >> disagreement.
> >
> > I would do a release at all if it only contains changes in the
> > dependency versions. The only exception I would make is vulnerable
> > dependencies, **if** we are affected by the vulnerability. If this is
> > the case feel free to replace "fixed/upgraded" with "changed" in the
> > changelog.
> >
> > In case a dependency upgrade does not influence the bytecode (i.e. our
> > artifacts still work with the old version), I would simply disregard
> > the upgrade when computing the required version dump.
> >
> > Piotr
>
>

Re: Versioning scheme

[Volkan Yazıcı]

Piotr, could you give me a well-defined formula of your desired versioning
scheme concerning minor/patch bumps?

On Tue, 12 Dec 2023 at 15:19, Piotr P. Karwasz 
wrote:

> Hi Volkan,
>
> On Tue, 12 Dec 2023 at 13:02, Volkan Yazıcı  wrote:
> >
> > On Tue, Dec 12, 2023 at 11:47 AM Piotr P. Karwasz <
> piotr.karw...@gmail.com>
> > wrote:
> >
> > >  * we lack a way to classify dependency updates. A concrete example:
> > > did the Commons DBCP2 bump to 2.11.0 change anything in
> > > `log4j-jdbc-dbcp2`? I don't think so, the artifact compiles with
> > > version 2.2.0 of the artifact. We are only stating that
> > > `log4j-jdbc-dbcp2` will **also** work with version 2.11.0.
> > >
> >
> > Exactly! Hence, it is clear that this is neither a bug fix, nor a
> > deprecation. That is, there is no ambiguity that this goes into a minor
> > release.
>
> And here I don't agree. Dependabot upgrades provide **no** benefit to
> the generated JAR files. Even the bytecode is exactly the same as
> before the upgrade.
>
> What these changes provide is part of our "Secure by default" or
> "Up-to-date by default" feature: Log4j artifacts will never freeze our
> clients dependencies and will work with the newest versions of the
> libraries we depend upon.
>
> If you need to **manually** fix code for the upgrade to work (as you
> did for Jackson 2.16.0), then you can change the automatically
> generated entry from "fixed/upgraded" to "changed".
>
> > > I don't think this warrants a minor version bump.
> > >
> >
> > This is what I am trying to eliminate Piotr: opinions. When a person
> starts
> > thinking *"Shall this be a patch or minor release?"*, the outcome is
> > inherently subjective. We cannot completely get rid of subjective
> > assessment, but assist it with guardrails.
>
> These guardrails seem to follow the easy path: let's just do minor
> releases, so nobody will tell us we are wrong. If you add ".0.0" to
> all Google Chrome versions, Chrome will also follow semver to the
> letter. It just loses the spirit.
>
> > > The bump to JDK 17 was necessary, very useful for us, but users don't
> > > really care what JDK was used for compilation.
> >
> >
> > What? Users, that is, developers using `logging-parent` as their parent
> > project, do certainly care about this change. Why wouldn't they? This is
> > *not* a simple change. It took us months to bump the compiler in Log4j. I
> > think your statement has an incorrect assumption on who the users of
> > `logging-parent` are.
>
> Sorry, I was still talking about Log4j. For `logging-parent` users the
> requirement to use JDK 17 is a minor change, but `log4j-core` users do
> not care what JDK we are using for compilation. Therefore the switch
> to JDK 17 for compilation is not reason enough to bump Log4j to
> 2.23.0.
>
> > I have the impression that you want to classify library updates that
> don't
> > disrupt the user experience as a patch release. If there is nothing
> urgent
> > about them, why do a patch release at all? Isn't the point of a patch
> > release is to fix something, urgently? Piggybacking library updates into
> > patch releases defeats the purpose of patch releases and makes the line
> > between minor and patch releases blur, and that is the crux of our
> > disagreement.
>
> I would do a release at all if it only contains changes in the
> dependency versions. The only exception I would make is vulnerable
> dependencies, **if** we are affected by the vulnerability. If this is
> the case feel free to replace "fixed/upgraded" with "changed" in the
> changelog.
>
> In case a dependency upgrade does not influence the bytecode (i.e. our
> artifacts still work with the old version), I would simply disregard
> the upgrade when computing the required version dump.
>
> Piotr
>

Re: Versioning scheme

[Ralph Goers]

> On Dec 11, 2023, at 2:32 PM, Piotr P. Karwasz  wrote:
> 
> I propose to keep the old strategy: after a release we set the version
> number to the next patch release.
> Only if we merge a change that requires a minor bump (we can tag
> those), we bump the release to the next minor version.

Actually, the strategy was to always make the version number a patch release. 
It really didn’t matter what the version number was though. When I ran the 
release plugin I always specified the release version so all the pom versions 
got updated regardless of what they were.

I would prefer that the CI system determine the release number based on what is 
in the changelog. That simply means we need to have enough enumerations to 
handle all the cases and be able to classify each enumeration as either patch 
or minor.

Ralph

Re: Versioning scheme

[Ralph Goers]

I have to agree with Piotr’s example. Simply upgrading a dependency doesn’t, on 
its own, change any code in Log4j.

I see three possible solutions for this:

1. Do not allow any dependency updates until a “scheduled” mentor release (once 
every 2 or 3 months). Frankly I’d be fine with this except when a dependency 
has a major security vulnerability.
2. Change all dependency versions to be ranges such that they don’t require a 
release for users to include new dependency releases.  (I cannot really 
recommend doing this).
3. Add a new type to represent dependency updates. This would also not require 
a minor release. This is really the most appropriate fix as updating a 
dependency is not a change to anything in Log4j. 

I would suggest adding another enumeration named “update”.

Ralph

> On Dec 12, 2023, at 7:19 AM, Piotr P. Karwasz  wrote:
> 
> Hi Volkan,
> 
> On Tue, 12 Dec 2023 at 13:02, Volkan Yazıcı  > wrote:
>> 
>> On Tue, Dec 12, 2023 at 11:47 AM Piotr P. Karwasz 
>> wrote:
>> 
>>> * we lack a way to classify dependency updates. A concrete example:
>>> did the Commons DBCP2 bump to 2.11.0 change anything in
>>> `log4j-jdbc-dbcp2`? I don't think so, the artifact compiles with
>>> version 2.2.0 of the artifact. We are only stating that
>>> `log4j-jdbc-dbcp2` will **also** work with version 2.11.0.
>>> 
>> 
>> Exactly! Hence, it is clear that this is neither a bug fix, nor a
>> deprecation. That is, there is no ambiguity that this goes into a minor
>> release.
> 
> And here I don't agree. Dependabot upgrades provide **no** benefit to
> the generated JAR files. Even the bytecode is exactly the same as
> before the upgrade.
> 
> What these changes provide is part of our "Secure by default" or
> "Up-to-date by default" feature: Log4j artifacts will never freeze our
> clients dependencies and will work with the newest versions of the
> libraries we depend upon.
> 
> If you need to **manually** fix code for the upgrade to work (as you
> did for Jackson 2.16.0), then you can change the automatically
> generated entry from "fixed/upgraded" to "changed".
> 
>>> I don't think this warrants a minor version bump.
>>> 
>> 
>> This is what I am trying to eliminate Piotr: opinions. When a person starts
>> thinking *"Shall this be a patch or minor release?"*, the outcome is
>> inherently subjective. We cannot completely get rid of subjective
>> assessment, but assist it with guardrails.
> 
> These guardrails seem to follow the easy path: let's just do minor
> releases, so nobody will tell us we are wrong. If you add ".0.0" to
> all Google Chrome versions, Chrome will also follow semver to the
> letter. It just loses the spirit.
> 
>>> The bump to JDK 17 was necessary, very useful for us, but users don't
>>> really care what JDK was used for compilation.
>> 
>> 
>> What? Users, that is, developers using `logging-parent` as their parent
>> project, do certainly care about this change. Why wouldn't they? This is
>> *not* a simple change. It took us months to bump the compiler in Log4j. I
>> think your statement has an incorrect assumption on who the users of
>> `logging-parent` are.
> 
> Sorry, I was still talking about Log4j. For `logging-parent` users the
> requirement to use JDK 17 is a minor change, but `log4j-core` users do
> not care what JDK we are using for compilation. Therefore the switch
> to JDK 17 for compilation is not reason enough to bump Log4j to
> 2.23.0.
> 
>> I have the impression that you want to classify library updates that don't
>> disrupt the user experience as a patch release. If there is nothing urgent
>> about them, why do a patch release at all? Isn't the point of a patch
>> release is to fix something, urgently? Piggybacking library updates into
>> patch releases defeats the purpose of patch releases and makes the line
>> between minor and patch releases blur, and that is the crux of our
>> disagreement.
> 
> I would do a release at all if it only contains changes in the
> dependency versions. The only exception I would make is vulnerable
> dependencies, **if** we are affected by the vulnerability. If this is
> the case feel free to replace "fixed/upgraded" with "changed" in the
> changelog.
> 
> In case a dependency upgrade does not influence the bytecode (i.e. our
> artifacts still work with the old version), I would simply disregard
> the upgrade when computing the required version dump.
> 
> Piotr

Re: Versioning scheme

[Christian Grobmeier]

On Tue, Dec 12, 2023, at 09:43, Volkan Yazıcı wrote:
> I agree with Ralph's view. It is not just the *view* in itself that I find
> appealing, but the (practically) deterministic nature of it. If one would
> closely look at Robert's and/or Piotr's explanation of patch-vs-minor
> strategy, it is pretty subjective, 

I don't think Roberts's view was subjective; he gave some clear rules to follow.

> aiming to eliminate. OTOH, Ralph's (or mine) is pretty straight forward:
>
> Will the next release *only* contain deprecations and/or bug fixes? Then it
> is a patch release. For all other cases, it is a minor release. [Assuming
> we all know and agree on what necessitates a major release.]

Well, this is what is said here, right?

- *MINOR version when you add functionality in a backward compatible manner*
- *PATCH version when you make backward compatible bug fixes*

Deprecations are no change in functionality but only a @deprecated tag. I 
assume this is why
they are not listed specifically, and also don't see the need for it.

> I propose sticking to this versioning scheme for all Logging Services
> releases and documenting it. Objections? 

I am okay with following semver, as we already did. 

I am against re-documenting what is already documented in semver. We can 
mention that we use semver, but please don't write documents that interpret 
semver further.

Are we trying to solve an actual problem? I have not seen a disagreement on a 
previous version number yet, or did I miss it in the flood of emails?

Christian

Re: Versioning scheme

[Piotr P. Karwasz]

Hi Volkan,

On Tue, 12 Dec 2023 at 13:02, Volkan Yazıcı  wrote:
>
> On Tue, Dec 12, 2023 at 11:47 AM Piotr P. Karwasz 
> wrote:
>
> >  * we lack a way to classify dependency updates. A concrete example:
> > did the Commons DBCP2 bump to 2.11.0 change anything in
> > `log4j-jdbc-dbcp2`? I don't think so, the artifact compiles with
> > version 2.2.0 of the artifact. We are only stating that
> > `log4j-jdbc-dbcp2` will **also** work with version 2.11.0.
> >
>
> Exactly! Hence, it is clear that this is neither a bug fix, nor a
> deprecation. That is, there is no ambiguity that this goes into a minor
> release.

And here I don't agree. Dependabot upgrades provide **no** benefit to
the generated JAR files. Even the bytecode is exactly the same as
before the upgrade.

What these changes provide is part of our "Secure by default" or
"Up-to-date by default" feature: Log4j artifacts will never freeze our
clients dependencies and will work with the newest versions of the
libraries we depend upon.

If you need to **manually** fix code for the upgrade to work (as you
did for Jackson 2.16.0), then you can change the automatically
generated entry from "fixed/upgraded" to "changed".

> > I don't think this warrants a minor version bump.
> >
>
> This is what I am trying to eliminate Piotr: opinions. When a person starts
> thinking *"Shall this be a patch or minor release?"*, the outcome is
> inherently subjective. We cannot completely get rid of subjective
> assessment, but assist it with guardrails.

These guardrails seem to follow the easy path: let's just do minor
releases, so nobody will tell us we are wrong. If you add ".0.0" to
all Google Chrome versions, Chrome will also follow semver to the
letter. It just loses the spirit.

> > The bump to JDK 17 was necessary, very useful for us, but users don't
> > really care what JDK was used for compilation.
>
>
> What? Users, that is, developers using `logging-parent` as their parent
> project, do certainly care about this change. Why wouldn't they? This is
> *not* a simple change. It took us months to bump the compiler in Log4j. I
> think your statement has an incorrect assumption on who the users of
> `logging-parent` are.

Sorry, I was still talking about Log4j. For `logging-parent` users the
requirement to use JDK 17 is a minor change, but `log4j-core` users do
not care what JDK we are using for compilation. Therefore the switch
to JDK 17 for compilation is not reason enough to bump Log4j to
2.23.0.

> I have the impression that you want to classify library updates that don't
> disrupt the user experience as a patch release. If there is nothing urgent
> about them, why do a patch release at all? Isn't the point of a patch
> release is to fix something, urgently? Piggybacking library updates into
> patch releases defeats the purpose of patch releases and makes the line
> between minor and patch releases blur, and that is the crux of our
> disagreement.

I would do a release at all if it only contains changes in the
dependency versions. The only exception I would make is vulnerable
dependencies, **if** we are affected by the vulnerability. If this is
the case feel free to replace "fixed/upgraded" with "changed" in the
changelog.

In case a dependency upgrade does not influence the bytecode (i.e. our
artifacts still work with the old version), I would simply disregard
the upgrade when computing the required version dump.

Piotr

Re: Versioning scheme

[Volkan Yazıcı]

On Tue, Dec 12, 2023 at 11:47 AM Piotr P. Karwasz 
wrote:

>  * we lack a way to classify dependency updates. A concrete example:
> did the Commons DBCP2 bump to 2.11.0 change anything in
> `log4j-jdbc-dbcp2`? I don't think so, the artifact compiles with
> version 2.2.0 of the artifact. We are only stating that
> `log4j-jdbc-dbcp2` will **also** work with version 2.11.0.
>

Exactly! Hence, it is clear that this is neither a bug fix, nor a
deprecation. That is, there is no ambiguity that this goes into a minor
release.


> I don't think this warrants a minor version bump.
>

This is what I am trying to eliminate Piotr: opinions. When a person starts
thinking *"Shall this be a patch or minor release?"*, the outcome is
inherently subjective. We cannot completely get rid of subjective
assessment, but assist it with guardrails.


>  * we lack a type to classify internal changes to the build system.
> The bump to JDK 17 was necessary, very useful for us, but users don't
> really care what JDK was used for compilation.


What? Users, that is, developers using `logging-parent` as their parent
project, do certainly care about this change. Why wouldn't they? This is
*not* a simple change. It took us months to bump the compiler in Log4j. I
think your statement has an incorrect assumption on who the users of
`logging-parent` are.


> Lacking a special "upgraded" type I would classify those changes as
> "fixed", hence a patch level change.
>

I have the impression that you want to classify library updates that don't
disrupt the user experience as a patch release. If there is nothing urgent
about them, why do a patch release at all? Isn't the point of a patch
release is to fix something, urgently? Piggybacking library updates into
patch releases defeats the purpose of patch releases and makes the line
between minor and patch releases blur, and that is the crux of our
disagreement.

Re: Versioning scheme

[Piotr P. Karwasz]

Hi Ralph,

On Mon, 11 Dec 2023 at 22:43, Ralph Goers  wrote:
>
> The rule for this seems extremely simple to me.  The changelog uses
>
> 
> 
> 
> 

Re: Versioning scheme

[Volkan Yazıcı]

I agree with Ralph's view. It is not just the *view* in itself that I find
appealing, but the (practically) deterministic nature of it. If one would
closely look at Robert's and/or Piotr's explanation of patch-vs-minor
strategy, it is pretty subjective, which is exactly the variable I am
aiming to eliminate. OTOH, Ralph's (or mine) is pretty straight forward:

Will the next release *only* contain deprecations and/or bug fixes? Then it
is a patch release. For all other cases, it is a minor release. [Assuming
we all know and agree on what necessitates a major release.]


I propose sticking to this versioning scheme for all Logging Services
releases and documenting it. Objections? [Or, if I may say,] strong
objections? 

On Mon, Dec 11, 2023 at 10:44 PM Ralph Goers 
wrote:

> The rule for this seems extremely simple to me.  The changelog uses
>
> 
> 
> 
> 

Re: Versioning scheme

[Robert Middleton]

This is going to be somewhat subjective and may be on a case-by-case
basis, but here are my thoughts:

On Mon, Dec 11, 2023 at 2:17 PM Volkan Yazıcı  wrote:
>
> I think this is where we have different ideas.
> Robert, could you elaborate on *"change/fix behavior without adding new
> method"*, please? For instance, does this cover the following changes?
>
>- Upgrading a dependency whose patch version is bumped (no behavior
>change on the parts we use the dependency)
>- Upgrading a dependency whose minor version is bumped (no behavior
>change on the parts we use the dependency)
>- Upgrading a dependency whose major version is bumped (no behavior
>change on the parts we use the dependency)
>- Upgrading a dependency whose major version is bumped (no behavior
>change on the parts we use the dependency, though the runtime requirements
>of the dependency has changed, e.g., started requiring Java 17 instead of
>Java 8, etc.)
>- `sum(a,b)` has changed from `a+b` to `a-b` (behaviour change, no new
>method)
>- `sum(a,b)` has started using GPUs (no change visible to the user,
>though substantial implementation change)
>

I think all of these would be either a patch/minor version change -
semver is showing users of your library(in this case log4j) what YOU
provide, not what you depend on.  The more difficult/large the change
is(using GPU, bumping a dependent library) I would argue is grounds
for a minor version bump.  Since the API that log4j provides does not
change in any of these circumstances, there is no need to bump the
major version(although you could if you want, I suppose).

The examples I gave before are when you must increment the version
number(according to my understanding) - I don't see any issue in
increasing the version number when you are not in one of those
scenarios.  For example, the Linux kernel has a somewhat arbitrary
major number, since it doesn't really tell you what API the kernel
has(there is no stable interface inside of the kernel).

-Robert Middleton

Re: Versioning scheme

[Ralph Goers]

The rule for this seems extremely simple to me.  The changelog uses

Re: Versioning scheme

[Piotr P. Karwasz]

On Mon, 11 Dec 2023 at 20:33, Volkan Yazıcı  wrote:
> > In the end the result (release version number) might be the same, but
> > the burden of proof falls on those advocating for a patch release.
> >
>
> I don't understand what you mean by "the burden of proof falls on those
> advocating for a patch release". Could you elaborate on it, please?

If you were to release Log4j right now from `2.x` what version would
you use? Almost certainly 2.23.0, since:

 * the current snapshot version is 2.23.0-SNAPSHOT,
 * there is a 2.23.0 milestone:
https://github.com/apache/logging-log4j2/milestone/9

The fact that the milestone contains only two patch-level changes is
completely hidden. Either the Release Manager or the PMC members
checking the release would have to go through those issues and prove
that it is a 2.22.1 release.

> As this conversation shows one more time, my main argument is against a
> rule that is too open to interpretation. I prefer to have a rule that has
> practically no room for ambiguity and at the same time makes sense in the
> semver framework.

Ambiguity is natural in the context of semver. We are supposed to
convey a meaning, so we should try to categorize each change properly
and discuss the changes hard to classify.

There is a simple case: if BND says MINOR change, it is usually a
minor change. However a change can always be upgraded due to reasons
besides the public API changes.

Regarding the classification of changes I also tend to look at our doc:

 * if the previous behavior disagreed with the doc, correcting it is a
bug fix (we probably all agree),
 * if we change a previously documented behavior, it is a minor bump
(here we also probably agree),
 * if we change a behavior that was **not** documented (e.g. the
evaluation of lookups in user data ;-), we should discuss about it.

> For the record, do you have a clear definition of your proposal? *"Every
> release should be a patch release"* doesn't really help.

I propose to keep the old strategy: after a release we set the version
number to the next patch release.
Only if we merge a change that requires a minor bump (we can tag
those), we bump the release to the next minor version.

Piotr

PS: Of course the examples for Log4j are a little bit artificial,
since Ralph's PR bumped the release number:
https://github.com/apache/logging-log4j2/pull/2062

Re: Versioning scheme

[Gary Gregory]

IMO:

A new protected or public anything needs a minor version bump. I think that
follows sem ver.

Gary

On Mon, Dec 11, 2023, 1:56 PM Piotr P. Karwasz 
wrote:

> Hi Volkan,
>
> On Mon, 11 Dec 2023 at 10:26, Volkan Yazıcı  wrote:
> > *Given a version number `MAJOR.MINOR.PATCH`, increment the:*
> >
> >
> >- *MAJOR version when you make incompatible API changes*
> >   - *MINOR version when you add functionality in a backward
> compatible
> >   manner*
> >   - *PATCH version when you make backward compatible bug fixes*
> >
> > I think we all agree on what warrants a major version bump. The
> definition
> > of what constitutes an API, etc. are all open to interpretation, but we
> > have a common sense of it in the PMC.
>
> I think we can split this into a:
>
>  * minimal version dump, dictated by technical reasons (changes in the
> methods exposed to the public),
>  * and a component that can not be automatically detected, which is
> due to change of behavior. E.g. I can modify the behavior of the `%i`
> converter without touching the public API.
>
> > We mostly have a problem whether the next release needs a minor or patch
> > version bump. I propose to refine the official semantics as follows:
> >
> > Are we making a release to *only* address a set of particular issues?
> That
> > is, does the following hold?
> >
> > [next release] = [last release] + [fix1] + [fix2] + ... + [fixN]
> >
> > If so, this needs a patch version bump. Otherwise, this is a minor
> version
> > bump.
>
> What I am having a problem with is the default type of change:
>
>  * for me every release should be a **patch** release, unless there
> are reasons to publish a minor release. For example the next Log4j
> release should be 2.22.1. This is the old strategy used by Log4j;
>  * recently this strategy shifted to: every release is a **minor**
> release, unless someone justifies that it can be a patch release. All
> our repos are currently using a snapshot version that is a minor
> version bump from the previous release.
>
> In the end the result (release version number) might be the same, but
> the burden of proof falls on those advocating for a patch release.
>
> The concrete example of `logging-parent` is hard to discuss, since it
> is not written in Java, but a mix of Maven plugins, bash scripts and
> Github action workflows. Your fix of the problem we were having with
> `META-INF/services/` is pretty nice, but for me it constitutes a bug
> fix, not a new feature children project can rely upon. The value of
> the contribution does not depend on the version bump it generates,
> patch contributions require usually more effort.
>
> On the other hand if we consider that the `bnd:jar` execution
> disappeared from `logging-parent`, this might be considered a major
> version change.
>
> Piotr
>

Re: Versioning scheme

[Volkan Yazıcı]

On Mon, Dec 11, 2023 at 7:56 PM Piotr P. Karwasz 
wrote:

>  * for me every release should be a **patch** release, unless there
> are reasons to publish a minor release. For example the next Log4j

release should be 2.22.1. This is the old strategy used by Log4j;
>  * recently this strategy shifted to: every release is a **minor**
> release, unless someone justifies that it can be a patch release. All
> our repos are currently using a snapshot version that is a minor
> version bump from the previous release.
>
> In the end the result (release version number) might be the same, but
> the burden of proof falls on those advocating for a patch release.
>

I don't understand what you mean by "the burden of proof falls on those
advocating for a patch release". Could you elaborate on it, please?


> The concrete example of `logging-parent` is hard to discuss, since it
> is not written in Java, but a mix of Maven plugins, bash scripts and
> Github action workflows. Your fix of the problem we were having with
> `META-INF/services/` is pretty nice, but for me it constitutes a bug
> fix, not a new feature children project can rely upon. The value of
> the contribution does not depend on the version bump it generates,
> patch contributions require usually more effort.
>

The recent `logging-parent` release increases the compiler baseline from
Java 8 to Java 17 due to the upgrade of BND from version `6.x` to `7.0.0`,
which requires Java 17.

Plus, `bnd:jar` is switched to `bnd:bnd-process` – a backward compatible
behaviour change. Though nothing urgent, a good-to-have.

Plus, several dependencies are upgraded – again, nothing urgent, a
good-to-have.

In conclusion, we have a JDK baseline bump along with
not-urgent-but-good-to-have backward compatible changes. I think these are
too big and too optional to be shipped in a patch release.

As this conversation shows one more time, my main argument is against a
rule that is too open to interpretation. I prefer to have a rule that has
practically no room for ambiguity and at the same time makes sense in the
semver framework.

For the record, do you have a clear definition of your proposal? *"Every
release should be a patch release"* doesn't really help.

Re: Versioning scheme

[Volkan Yazıcı]

On Mon, Dec 11, 2023 at 6:20 PM Robert Middleton 
wrote:

> add new method/class = minor version bump
> change/fix behavior without adding new method = patch
>

I think this is where we have different ideas.
Robert, could you elaborate on *"change/fix behavior without adding new
method"*, please? For instance, does this cover the following changes?

   - Upgrading a dependency whose patch version is bumped (no behavior
   change on the parts we use the dependency)
   - Upgrading a dependency whose minor version is bumped (no behavior
   change on the parts we use the dependency)
   - Upgrading a dependency whose major version is bumped (no behavior
   change on the parts we use the dependency)
   - Upgrading a dependency whose major version is bumped (no behavior
   change on the parts we use the dependency, though the runtime requirements
   of the dependency has changed, e.g., started requiring Java 17 instead of
   Java 8, etc.)
   - `sum(a,b)` has changed from `a+b` to `a-b` (behaviour change, no new
   method)
   - `sum(a,b)` has started using GPUs (no change visible to the user,
   though substantial implementation change)

My point is, it is difficult to draw a line and the gray area is pretty
large. Hence, I propose a very simple resolution rule for minor-vs-patch
that doesn't have room for ambiguity: Is it only a selected set of fixes
and nothing else? Then it is a `patch` bump, otherwise everything else is a
`minor` bump.

Re: Versioning scheme

[Volkan Yazıcı]

Yes, we do semver.

No, I am not against alpha, vs.
Though I think we can limit the regex of the `patch` part a bit.

The main problem is that there is no clear line between patch and minor
releases.
[See my response below.]

On Mon, Dec 11, 2023 at 5:15 PM Christian Grobmeier 
wrote:

> I don't understand what is the difference to what semver says.
> When you add functionality, it's a minor. If you just add fixes, it's a
> patch.
> Did I miss something that we are doing differently?
>

I totally agree. Though Piotr doesn't – he better speaks for himself. In a
nutshell, Piotr suggests doing `patch` releases also for *"add
functionality"*, granted it is backward compatible.

Re: Versioning scheme

[Piotr P. Karwasz]

Hi Volkan,

On Mon, 11 Dec 2023 at 10:26, Volkan Yazıcı  wrote:
> *Given a version number `MAJOR.MINOR.PATCH`, increment the:*
>
>
>- *MAJOR version when you make incompatible API changes*
>   - *MINOR version when you add functionality in a backward compatible
>   manner*
>   - *PATCH version when you make backward compatible bug fixes*
>
> I think we all agree on what warrants a major version bump. The definition
> of what constitutes an API, etc. are all open to interpretation, but we
> have a common sense of it in the PMC.

I think we can split this into a:

 * minimal version dump, dictated by technical reasons (changes in the
methods exposed to the public),
 * and a component that can not be automatically detected, which is
due to change of behavior. E.g. I can modify the behavior of the `%i`
converter without touching the public API.

> We mostly have a problem whether the next release needs a minor or patch
> version bump. I propose to refine the official semantics as follows:
>
> Are we making a release to *only* address a set of particular issues? That
> is, does the following hold?
>
> [next release] = [last release] + [fix1] + [fix2] + ... + [fixN]
>
> If so, this needs a patch version bump. Otherwise, this is a minor version
> bump.

What I am having a problem with is the default type of change:

 * for me every release should be a **patch** release, unless there
are reasons to publish a minor release. For example the next Log4j
release should be 2.22.1. This is the old strategy used by Log4j;
 * recently this strategy shifted to: every release is a **minor**
release, unless someone justifies that it can be a patch release. All
our repos are currently using a snapshot version that is a minor
version bump from the previous release.

In the end the result (release version number) might be the same, but
the burden of proof falls on those advocating for a patch release.

The concrete example of `logging-parent` is hard to discuss, since it
is not written in Java, but a mix of Maven plugins, bash scripts and
Github action workflows. Your fix of the problem we were having with
`META-INF/services/` is pretty nice, but for me it constitutes a bug
fix, not a new feature children project can rely upon. The value of
the contribution does not depend on the version bump it generates,
patch contributions require usually more effort.

On the other hand if we consider that the `bnd:jar` execution
disappeared from `logging-parent`, this might be considered a major
version change.

Piotr

Re: Versioning scheme

[Robert Middleton]

remove method/class OR change method arguments OR class size
changes(C++) = major version bump
add new method/class = minor version bump
change/fix behavior without adding new method = patch

That should be the criteria for when to bump, at least according to
semver as far as I understand.

-Robert Middleton

On Mon, Dec 11, 2023 at 11:15 AM Christian Grobmeier
 wrote:
>
> Hi Volkan,
>
> I am not sure what you are proposing.
>
> On Mon, Dec 11, 2023, at 10:26, Volkan Yazıcı wrote:
> > I propose embracing a common versioning scheme across all Logging Services
> > projects; log4j, log4cxx, etc.
>
> As you already mentioned, except for some parts of Log4j 1, we are following 
> server already, and it looks like everybody knows about it.
>
> > match the `[0-9]+(-(alpha|beta)[1-9]+)?` That is, only the following will
> > be valid: `1.2.3`, `1.2.3-alpha4`, `1.2.3-beta4`, etc.
>
> We have only 3.0.0 with the alpha label. You are not against it, I guess?
>
> >- *MAJOR version when you make incompatible API changes*
> >   - *MINOR version when you add functionality in a backward compatible
> >   manner*
> >   - *PATCH version when you make backward compatible bug fixes*
> >
> > We mostly have a problem whether the next release needs a minor or patch
> > version bump. I propose to refine the official semantics as follows:
> >
> > Are we making a release to *only* address a set of particular issues? That
> > is, does the following hold?
> >
> > [next release] = [last release] + [fix1] + [fix2] + ... + [fixN]
> >
> > If so, this needs a patch version bump. Otherwise, this is a minor version
> > bump.
>
> I assume with "issue" and "fix" you mean "bug fix".
>
> I don't understand what is the difference to what semver says.
> When you add functionality, it's a minor. If you just add fixes, it's a patch.
> Did I miss something that we are doing differently?

Re: Versioning scheme

[Christian Grobmeier]

Hi Volkan,

I am not sure what you are proposing.

On Mon, Dec 11, 2023, at 10:26, Volkan Yazıcı wrote:
> I propose embracing a common versioning scheme across all Logging Services
> projects; log4j, log4cxx, etc. 

As you already mentioned, except for some parts of Log4j 1, we are following 
server already, and it looks like everybody knows about it.

> match the `[0-9]+(-(alpha|beta)[1-9]+)?` That is, only the following will
> be valid: `1.2.3`, `1.2.3-alpha4`, `1.2.3-beta4`, etc.

We have only 3.0.0 with the alpha label. You are not against it, I guess?

>- *MAJOR version when you make incompatible API changes*
>   - *MINOR version when you add functionality in a backward compatible
>   manner*
>   - *PATCH version when you make backward compatible bug fixes*
>
> We mostly have a problem whether the next release needs a minor or patch
> version bump. I propose to refine the official semantics as follows:
>
> Are we making a release to *only* address a set of particular issues? That
> is, does the following hold?
>
> [next release] = [last release] + [fix1] + [fix2] + ... + [fixN]
>
> If so, this needs a patch version bump. Otherwise, this is a minor version
> bump.

I assume with "issue" and "fix" you mean "bug fix".

I don't understand what is the difference to what semver says. 
When you add functionality, it's a minor. If you just add fixes, it's a patch.
Did I miss something that we are doing differently?