as requested I updated the recently
added proposal 5 (SemVer), which was derived from the original
more strict proposal 3 and adds some of the flexibility and ideas
of proposal 1.
@Emily: What we do in MicroProfile
(and unfortunately not in Jakarta EE yet) with the semver
analysis via Maven plugin is great - but this does not cover all
the semver aspects.
We check on the MP Spec API level
only, but we are still deviating. Examples:
In some cases we are ignoring the
Patch Release version, like in spec documents or omitting it
completely in recent MP Parent versioning (only MAJOR.MINOR
version schema), but with Semantic Versioning the following
parts are mandatory: MAJOR.MINOR.PATCH (https://semver.org/)
Not (fully) covered are dependency
related version updates. And in the case these dependencies are
not using semver, doing this automatically is nearly impossible,
like Java SE version definition (as minimum).
The MPSP defines service releases,
not Patch Releases - another "alike", but not exactly matching
semver.
You called patch related versioning
"micro version" recently... ;-)
Of course, MicroProfile is ahead of
Jakarta EE in supporting semver, but we are not fully compliant.
Regrading proposal 1:
To pass the TCK and as CI to allow
the release of a new spec version, only the defined set of
(minimum) versions need to be passed. When the MicroProfile
umbrella spec defines higher versions as a minimum, then this
umbrella spec CI need to pass the TCKs of the component specs
and this could fail, because both requirements do not match. And
this will be a very late fail...
Especially when the CIs of the
component specs deviate from the umbrella specs CI, we have a
higher chance for this pitfall - but our release process should
allow deviation and still need to be save.
Proposal 1 is, what was done in the
MP 6.0 release and defined in it's Release Plan, where some
component specs where still based on Jakarta EE 9.1 component
specs (defined in MP Parent 2.6) and only two component specs
where defining Jakarta EE 10 Core Profile itself (defined in MP
Parent 3.0). So we have two different, deviating versions of MP
Parent in one umbrella spec release. This is dangerous,
especially when there are different Major Releases (as some
minor ones) for these dependencies defined.
Now we have some security issues,
that need to be fixed - to do this completely, we have to fix it
in all referenced Jakarta EE 9.1 component specs, Jakarta EE 10
component specs, Jakarta EE 10 Core Profile, MP Parent 2.6 and
MP Parent 3.0 etc. to fix it for MP 6.0(.1) - this is much more
because of having ranges for dependencies being used as a
shortcut.
That's technical debt, where we now
have to pay the additional interest rate!
Really sad is, that this approach
complicates automatic testing, as you need to test with manually
edited configurations to cover all necessary system
environments, as opposed to define one environment that does not
deviate from the umbrella spec's ones, which also defines the
one, the user can expect (and not get confused when looking at a
single component spec).
A different system environment
justifies another spec release, like first do a Minor Release
and then a Major Release of the specs where possible or create a
backport later.
We should head for clarity and define
a single MP Parent version for a MP umbrella spec release - as
the MP Parent defines the system environment for the MP release.
Then we need to manage the directed graph of the MP component
specs and it's dependencies to each other for the hole MP
release to be clean.
Am 09.03.23 um 23:03 schrieb Emily
Jiang via microprofile-wg:
Thank you Jan for sharing your thoughts! By the way,
MicroProfile has been using semantic versioning from the
first release and each spec uses the plugin to work out
whether there are breaking changes introduced or not.
As for Proposal 1, the implementation indeed needs to
test the variation they support. The umbrella spec just
specifies the minimum, as long as the impl can demonstrate
they can support the combination, they can claim the
certification.
@Reza: I would like to disagree you here - we need to
discuss these proposals in detail, because it's not only
affecting the next release, it's about all future
releases until we change the strategy again.
And as the Google Doc and it's version history might
get lost, this mailing list will be archived for future
review.
I added some comments in the Google Doc, but I have
major to minor concerns for all of these proposal
variants.
First of all, from my point of view, the discussion
is mainly focused on the vendors and not the users view,
while the last one is important for a successful
specification in the long run.
Then second, we are focussing on releasing according
to the past (retrograde) and not keep in mind potential
future releases too (anterograde), when cutting
releases.
Why we not officially decide to use Semantic
Versioning (semver) first (and not something "alike" or
following it partly only)?
Users like this de facto industry standard, as this
manifests the design-by-contract pattern with
well-defined rules in a short version number, which
makes things simple!
When maintaining software according to semver, a
consumer of a software artefact (like a dependency in an
application or specification), knows by looking on the
version number (string), what can be updated or combined
in a safe way: A higher Patch Release is safe, as this
should fix issues only and also a Minor Release is safe,
while this might contain new features to, but in a
non-breaking way. When updating to a Major Release, then
extra caution is necessary, as this means at least
something breaks! To know, if this affects you, this
means RTFM (read the f...... manual) like release notes,
spec documents etc.
Because Major Release updates create extra work
(sometimes with no direct benefit for the consumer in
the short), we should do them carefully and not more
than necessary.
Therefore it's a good idea to combine multiple
breaking changes in one single Major Release on
component and umbrella spec level, so there is room for
doing feature enhancements in future releases only with
a Minor Release and also even allow to backport (some)
of these new features aligned to older Major Releases
later, without violating the versioning schema.
This simplifies maintenance too, as Patch Releases
are possible for every existing version.
There are corner cases, where you can argument that
the artefact in scope is not affected directly from a
breaking change in a lower dependency level and you do
not need to do a Major Release - but this can create a
hidden link for the user of that artefact, as he might
be affected - and looking at the version contract is not
enough, because this is transitive...
The other way around is another possibility: Do the
same breaking change in the upper artefact with a Major
release with a non-Major Release in the dependency and
then later, do a Major Release with this breaking change
(and only that one, that was already done in the upper
artefact) in it, combined with a non-Major Release in
the upper artefact, so skipping the Major Release there.
But this is not that obvious to the user and might
confuse him. At least it requires some sort of RTFM
again...
Example: The umbrella spec can decide to do a release
that requires Java SE 21, but a component spec (as a
part of it) could still allow Java SE 17 - even it can
be used with the umbrella spec with Java SE 21 (or
above) only. Then in the next release, the umbrella spec
can do a non-Major Release that contains that component
spec's Major Release, when the only breaking change in
it is raising the requirement to Java SE 21 for it, as
it was done for the umbrella spec already.
BTW, Java SE version schema deviates from semver
severely, but there are breaking changes that are done
with extra care, especially between LTS releases
(including between 11, 17 and 21) - but this requires
some RTFM again. ;-)
Helpful to identify them could be this Java Version
Almanac (https://javaalmanac.io).
With the last Jakarta EE Releases, we have breaking
changes too, and Jakarta EE 21 will be no exception,
like Jakarta REST 4.0, Java SE 21 (LTS). Getting to
non-experimental JPMS support might result in some
breaking changes too, as JPMS disallows circular
dependencies on modules and does not support (multiple)
versions of a module.
This is another requirement we need to be aware of in
MicroProfile too, especially when we let Jakarta EE
depend on MP specs!
Regarding the proposals here my summary:
Proposal 1:
With semver it would be allowed to support newer
versions in the future, but supporting multiple Major
Releases as intended here is leaving the safe path and
extremely dangerous!
Managing Ranges of versions for specs also lead to
the problem, that they create multiple potential system
environments and the need to test all of the ones we
want to allow.
To remember, we are testing manually yet! Continuous
Integration might help to ensure the component specs are
tested in the umbrella specs scopes, so we do not end in
surprises there. But even then we have the challenge to
deliver a clean directed graph of dependencies for every
variant and have a much higher chance to be affected by
security issues through vulnerabilities - and this
affects us now already...
Notably there are only two useful aspects, we should
think of in general:
Let component specs depend on component specs only,
not on umbrella specs directly, because then they would
require unused dependencies. However, we definitively
should manage the versions in the MP Parent with a BOM
import, where possible.
The other aspect we might consider is defining the
Jakarta EE Core Profile dependency as type provided -
this could help with some issues.
Proposal 2:
This Lite Profile variant complicates things even
more, while does not solve the system environment and
testing issue.
Proposal 3:
When there is a breaking change for the user of a
underlying dependency, like a higher minimum Java SE LTS
version requirement of a Jakarta EE Core Profile Major
Release (containing breaking changes), then we should
plan a fitting MicroProfile Major Release to support
this.
And I think with component specs depending on
component specs only as mentioned above, a umbrella spec
release can be done very soon after the Core Profile
release - so implementations can support them together.
Continuous Integration will help here a lot too.
Dependencies in both directions would be possible
with this approach, as moving a spec in one or the other
direction, as a hole or in part.
I have some small concerns regarding the described
versioning in corner cases (see introduction here), but
I think it's the most viable solution for the next
release.
For allowing accelerated patching we can think about
adding even the Jakarta EE dependencies as of type
provided, so i.e. vendors do not have to wait for a spec
release to fix a vulnerability.
Proposal 4:
This might be a solution in the long run, if we can
not justify the existence of two separate WGs (as
discussed in John's other thread).
I would not expect we can manage this for the release
fitting to Jakarta EE 11 currently.
So, in conclusion I would vote for Proposal 3
definitively, may be by picking the useful two aspects
from Proposal 1 additionally.
Otherwise the maintenance and user confusion will
increase even more than yet, and I think we have to do a
lot already...
For (some) of the details of ongoing issues, have a
look at my CN4J call preparation slides:
Solving some of them (especially the security related
ones) may require doing Patch Releases for Jakarta EE
and MicroProfile (multiple versions) soon...
Agreeing on semver will make things clearer and may
make some parts of the discussions obsolete in the
future - and some parts can be automated with already
existing tooling for semver easily!
Best,
Jan
Am 02.03.23 um 01:15 schrieb Reza Rahman:
Added some very minor comments. I think it's thorough
enough already for people to make a decision.
On 3/1/2023 6:23 PM, Emily Jiang via
microprofile-wg wrote:
After some lengthy discussion regarding the
issue David raised in this thread that
MicroProfile 7.0 is trying to solve, we revealed this googledoc
containing some proposals in yesterday's
MicroProfile technical call. There are 4
proposals listed with cons/pros included.
For Proposal 4: Making the MicroProfile a profile of Jakarta EE,
the group felt that there was a prerequisite to
dissolve MicroProfile working group. This might
not be feasible to release MicroProfile 7.0 in
June 2023. With this in mind, the group felt it
might be better for us to focus on Option 1, 2 and
3 and discuss further in the next few days till
Tuesday next week. At the MicroProfile Live
Hangout, we can decide whether we need further
discussion or put up for a vote on Option 1, 2 or
3 among MicroProfile Working Members.
Proposal 1: MicroProfile releases support a minimum Jakarta EE versions
Proposal 2: Create MicroProfile Lite and rename the current umbrella to MicroProfile Full
Proposal 3: Release new MicroProfile versions when new Jakarta EE/Java SE versions are released
I understand not everyone was in yesterday's
call. Please use this thread to share your
thoughts.
Alternatively, please comment on the cons/pros
of each individual proposal.
Thank you Arjan! Your proposal was added to
the doc.
We will continue the discussion of
MicroProfile 7.0 next Tuesday.
On
Wednesday, February 8, 2023 at 3:47:44 PM
UTC Arjan Tijms wrote:
Hi,
On Tuesday, January 31,
2023 at 6:09:14 PM UTC+1 Emily Jiang
wrote:
As promised, I have created this
googledoc to capture and log
some comments for this conversation.
Thanks for creating the document
Emily.
Could you also add my proposal of
making the Micro Profile a profile of
Jakarta EE to the document as proposal
4?
I know some of you may think it's a
peculiar proposal, but I would like to
ask those people to do the following
thought experiment:
"If the micro profile didn't exist
yet, and today, given the situation of
how Jakarta EE is at Eclipse and
everything, we would talk about adding
a micro profile and associated new
APIs. Would you then wanted to create
a new working group for this new micro
profile, or would you add it as a
profile to Jakarta EE?"
My guess is you already know the
answer to this, but truthfully for
yourself, go through this mental
exercise. It may also help to think
about why we didn't create new or
separate working groups for the core
profile last year and for the web
profile after it was transferred.