Re: [jakarta.ee-spec] Major vs minor version update for the Plan Reviews

[Emily Jiang <emijiang6@xxxxxxxxxxxxxx>]

I remember Ivar and I discussed this 2 years ago at EclipseCon in the past. I highly recommend to adopt semantic versioning for versioning APIs. MicroProfile specifications adopt the semantic versioning policies and it worked well. The semantic versioning maven plugin biz.aQute.bnd:bnd-baseline-maven-plugin was so easy to use, so it would be quite straightforward to get started. We used this plugin to help us spot any backward incompatible changes and properly version our packages and releases. Without this plugin automating the build, some backward incompatible change might sometimes sneak into a PR without being noticed.

Thanks

Emily

On Wed, Apr 28, 2021 at 9:31 PM Kevin Sutter <sutter@xxxxxxxxxx> wrote:

Hi,
As I either mentor or review the Plan Reviews for the upcoming Jakarta Specifications, I am questioning some of the major version updates.  Per semantic versioning, we should be limiting the major version update for breaking API changes -- not just because we have "too many changes for a minor release".

I will be challenging all of these that I see, but I also ask the rest of the Spec Committee to also help monitor this situation.  In the EFSPwe determined that we would encourage the use semantic versioning for the individual Specifications, but we couldn't require it.  (The Platform and Profile versions could be an exception to the rule.)

One example that I came across is the JSONB 3.0 Plan Review:
https://github.com/jakartaee/specifications/pull/348

Although the author did an excellent job of highlighting the changes proposed for this release, I didn't see anything that caused an incompatible change.  Thus, I am challenging the use of a major version update to 3.0 instead of just increasing the minor version to 2.x.  At the end of the day, each Spec Project can decide for themselves, but we should encourage semantic behavior for APIs.

I'm going to post this to the public Spec mailing list since it was a wider audience and this discussion/observation shouldn't be limited to just the Spec Committee (imho).  Thanks!

---------------------------------------------------
Kevin Sutter
STSM, Jakarta EE and MicroProfile architect @ IBM
e-mail:  sutter@xxxxxxxxxx     Twitter:  @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)    
LinkedIn: https://www.linkedin.com/in/kevinwsutter

Part-time schedule: Tue, Wed, Thu (off on Mon and Fri)
_______________________________________________
jakarta.ee-spec mailing list
jakarta.ee-spec@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec

--

Thanks
Emily