Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakartaee-platform-dev] [External] : Re: [] Semantic Versioning Jakarta APIs

On 8/31/21 4:50 PM, Emily Jiang via jakartaee-platform-dev wrote:
Thanks Jean-Louis for your thoughts on this! My comments are inline.

On Thu, Aug 26, 2021 at 6:50 PM Jean-Louis Monteiro <jlmonteiro@xxxxxxxxxxxxx <mailto:jlmonteiro@xxxxxxxxxxxxx>> wrote:

    I'm not ok with adding an OSGi dependency and I'm not ok with the
    impact on the community.

    Class retention: even if it's class retention it's still in the
    Deployment does not always happen at runtime (Quarkus for example).
    And it's not uncommon to use tools like ASM, javasist, or other to
    read the bytecode where this annotation could be used for something
    specific, seriously impacting portability.

Since package-info is not a proper class, I don't think it will be processed. I think what you mentioned is for cdi osgi annotation not for semantic versioning, which was added to get MP Config to be used by other OSGi specs.

while package-info is not a proper class, some jakarta specs do rely and/or allow certain things to be there and are reading annotation(s) from there

    Do we want to open that door?
    If we add OSGi Version annotation, why don't we add others?

    That being said, let's step back a bit.
    Let's say we want a semantic versioning in Jakarta for our APIs.
    First we would need to discuss and decide on the mailing list.
    I would recommend not mixing with the "how to do it?"

    On the "how", it looks like all the @Version with OSGi discussion
    comes from the tool we want to use (BND).
    If the tool does not fit with our requirements, let's use/write
    another one.
    A tool should help and not be a restriction.

 I think we mentioned on the call, we can move these annotations to Jakarta and go from there.

Do we need them at all? I mean pom knows the version already, why the version cannot be read from there and reused?


    Throwing a crazy idea to illustrate. Not saying it's good and we
    should follow this path.
    We have had signature tests with signature definitions for ages.
    Why don't we write a tool that does a comparison with a previous
    version of the signature definition?

    Brainstorming but hope it helps

So far, I have not heard the objections to adopting semantic versioning. If no one has objections, we can then look into how to get this implemented and move from there.

    Jean-Louis Monteiro

    On Wed, Aug 25, 2021 at 12:15 PM Steve Millidge (Payara)
    <steve.millidge@xxxxxxxxxxx> wrote:

        My personal view is semantic versioning only focuses on one
        aspect of change i.e. breaking changes. It does not provide any
        information on whether a new api is significantly enhanced but
        without breaking changes and therefore worth a closer look by a
        developer. It can also force a "major" release for a minor
        incompatibility which may not be relevant to the majority. While
        this is intellectually pure it is also anaemic.

        Saying that, if we don't fall into the trap of using semantic
        versioning for the overall platform then we may get away with it.


        *From:* jakartaee-platform-dev
        <mailto:jakartaee-platform-dev-bounces@xxxxxxxxxxx>> on behalf
        of Emily Jiang via jakartaee-platform-dev
        *Sent:* 24 August 2021 10:14 PM
        *To:* jakartaee-platform developer discussions
        <mailto:jakartaee-platform-dev@xxxxxxxxxxx>>; Jakarta
        specification discussions <
        *Cc:* Emily Jiang <emijiang6@xxxxxxxxxxxxxx
        *Subject:* [jakartaee-platform-dev] Semantic Versioning Jakarta
        We discussed in today's Jakarta platform call regarding semantic
        versioning Jakarta APIs(see minutes here
        The discussion was positive. Since this impacts all
        specifications, we would like to see what others think.
        *Some context on Semantic versioning*
        Semantic versioning is to version each individual API package.
        Refer this
        white paper to understand semantic versioning. MicroProfile has
        been using semantic versioning to version the APIs from the
        beginning and it helped the specifications a great deal when
        deciding whether to perform a major or minor release. In Jakarta
        EE, specs are cautious with backward incompatible changes.
        However, no building tool is used to validate whether a
        particular spec has introduced such changes.

        With semantic versioning, both implementers and end users have a
        clear view on what APIs changes are introduced between releases.
        If the version for a particular package stays the same between
        the releases, it means no changes are introduced for that
        package. If major version changes (e.g. the version changes from
        1.0 to 2.0), it means backward incompatible changes are
        introduced between the releases.

        *How to do semantic versioning*
        In each API package, you just need to create a
        with the version number (see an example here
        You can also use this package-info to log the javadoc for that
        particular package. There are a couple of maven plugins to
        process the package version and then do the version comparison.
        Again, MicroProfile has the full set up to get it working. It is
        just a copy and paste job in the pom.xml when getting semantic
        versioning implemented in Jakarta EE specs.

        If you have any questions, please feel free to comment here.

-- Thanks

        _______________________________________________ mailing list <>
        To unsubscribe from this list, visit

    jakartaee-platform-dev mailing list
    To unsubscribe from this list, visit


jakartaee-platform-dev mailing list
To unsubscribe from this list, visit;!!ACWV5N9M2RV99hQ!acLVUt2ewJuxHAwWuvV2d38P-f83eeFxpifRNFwVtTR0b7Mv_XNaN7_HEQ6mW6466eY$

Back to the top