Difference between revisions of "MicroProfile/SpecVersioning"

Revision as of 17:14, 30 April 2018

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:

• Requiring a Jakarta EE specification at a higher Jakarta EE release level than is currently specified
• A breaking change
• Dropping support for a Java SE version
• 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.

Version Guidelines for Umbrella Specification

Major version change will be triggered when:

• A breaking change
• Removing a sub-spec from an umbrella spec
• Including a sub-spec that increases its major version triggers a major version change.
  • There is a general exception to this. If a sub-spec raised it's major version to 'catch up with' another sub-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 ]

Guidance for Ensuring a Consistent Platform

In general sub-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 sub-specs must be interoperable.
• The umbrella specification ultimately chooses which sub-spec versions to include. e.g. the umbrella specification may decide to remain at an older sub-spec version.
• The umbrella specification decides which sub-specs to include [ not discussed yet]
• Sub-specs may recommend which version of their spec should be included in a particular Umbrella release
• Sub-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 spec ending

• A sub-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 sub-spec depends on is down to the sub-spec to determine. The intent is that the sub-specs drive the adoption of new Jakarta EE versions, not the umbrella specification

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. The next release of MicroProfile is 56.1.