MicroProfile/SpecVersioning

Spec Versioning Guidelines

This is a draft! These guidelines are drawn from a series of calls on how spec versioning should work. These are minuted in a google doc and the calls occurred on April 24th and April 26th.

Terms

• Umbrella Specification - MicroProfile 1.0 is an Umbrella specification pulling together a set of component specs
• Component Spec - A single specification of an API. MicroProfile Config is an example of a component spec. (Note: this was referred to as "sub-spec" in the meeting minutes. But, MicroProfile has always called these "component specs".)
• Breaking Change - A breaking change is a change that is known to cause users of the API to either recompile, or update their source.
• Version - A MicroProfile version is built up of a major and a minor component. e.g. 1.0, 1.2, 1.3, 2.0

Note - some may observe that the MicroProfile 2.0 release doesn't exactly fit these guidelines. The current discussion assumes that MicroProfile 2.0 will be proceed on the current proposed basis of just updating to Java EE 8 and these guidelines will take effect post MicroProfile 2.0

Version Guidelines for Component Specs

Major version change will be triggered when:

• A breaking change
• Dropping support for a Java SE version
• Requiring a Jakarta EE specification at a higher Jakarta EE release level than is currently specified
• Dropping support for a Jakarta EE / Java EE feature version
• A dependency on another component spec is updated to one that has a major version change.

Bug fix releases can be done at any time but these kind of releases will NOT be included by umbrella release according to Hangout minutes on 12th Dec 2017

Version Guidelines for Umbrella Specification

Major version change will be triggered when:

• A breaking change
• Removing a component spec from an umbrella spec
• Including a component spec that increases its major version triggers a major version change on the umbrella spec.
  • There is a general exception to this. If a component spec raised it's major version to 'catch up with' another component spec contained in the umbrella version then this will not trigger a major version change.
• Adding a spec? [ This is yet to be discussed and agreed as a rule ]

[Note:] There was a subsequent discussion at a MicroProfile Live Hangout on May 15 that questioned whether these Guidelines should apply to the Umbrella Specification, or just the Component Specifications. That is, to follow the convention followed by Java EE and Jakarta EE to version the umbrella (platform) specification independent of semantic versioning. It was determined to leave the Guidelines as-is for now. We will re-address when these guidelines cause an issue with the umbrella specification versioning.

Guidance for Ensuring a Consistent Platform

In general component specs should have freedom to change independently, however there is still a need for a consistent umbrella release which requires some coordination. To enable a consistent platform the following guidelines have been discussed for coordination:

• When an umbrella specification is released, all included component specs must be interoperable.
• The umbrella specification ultimately chooses which component spec versions to include. e.g. the umbrella specification may decide to remain at an older component spec version.
• The umbrella specification decides which component specs to include [ not discussed yet]
• Component specs may recommend which version of their spec should be included in a particular Umbrella release
• Component specs are free to determine how many parallel release streams they maintain at any given time based on their resources, community interest, etc.
  • This could become 0, resulting in the component spec ending.
• A component spec can release a major version that includes breaking changes at any time and does not need to be coordinated with an umbrella spec.
• The decision of which versions of Jakarta EE a component spec depends on is down to the component spec to determine. The intent is that the component specs drive the adoption of new Jakarta EE versions, not the umbrella specification. (Note, this is the exception discussed earlier relating to MicroProfile 2.0 content.)

Examples

Assumed base release

• MicroProfile 55.0
• Config 13.4
• Metrics 10.1

• Scenario - Metrics releases version 11. MicroProfile 55.1 cannot include it. MicroProfile 56 can.
• Scenario - Config 14 comes out and pre-reqs CDI 4. MicroProfile 56 is released including Config 14 and Metrics 10.1. Metrics now releases a version 11 which makes no breaking changes, but now exploits CDI 4. MicroProfile 56.1 can contain Metrics 11.

Note: