The process of logging breaking changes

[Emily Jiang]

MicroProfile 3.0 release date is fast approaching and this release will likely include the following 3 specs (all of them containing breaking changes). As MP 3.0 will be the first release containing backward incompatibility changes. We need to standardise the way how to communicate breaking changes.

1. Metrics 2.0

2. Health Check 2.0

3. Open API 2.0

Although MicroProfile allows breaking changes, I think we must ensure MP end users' life as easier as possible by documenting the breaking changes clearly and provide a way to achieve the old behavior if possible.

See the issue I raised for MP Architecture and Ken suggested bringing this topic for a wider discussion (see https://github.com/eclipse/microprofile/issues/99).

I suggest:

1. Each spec have a dedicated section labeling backward incompatibility changes

2. Provide a solution how to achieve the old behaviour if possible

3. How to fix the compilation issues if exists

4. In the umbrella release, there should be a section to call out all the break changes.

These just food for thoughts. Please share your opinion.

Thoughts?

Emily

[Ken Finnigan]

On Tue, Apr 23, 2019 at 9:20 AM 'Emily Jiang' via Eclipse MicroProfile <microp...@googlegroups.com> wrote:

MicroProfile 3.0 release date is fast approaching and this release will likely include the following 3 specs (all of them containing breaking changes). As MP 3.0 will be the first release containing backward incompatibility changes. We need to standardise the way how to communicate breaking changes.

1. Metrics 2.0

2. Health Check 2.0

3. Open API 2.0

Although MicroProfile allows breaking changes, I think we must ensure MP end users' life as easier as possible by documenting the breaking changes clearly and provide a way to achieve the old behavior if possible.

See the issue I raised for MP Architecture and Ken suggested bringing this topic for a wider discussion (see https://github.com/eclipse/microprofile/issues/99).

I suggest:

1. Each spec have a dedicated section labeling backward incompatibility changes

Should mandate that release notes included a "Breaking Changes" section for every release, even if most of the time it has "None".

 

2. Provide a solution how to achieve the old behaviour if possible

A migration description is a far cleaner alternative. If we require, or even just recommend, specifications provide a way to retain "old" behavior, we add complexity for implementations to try and support both.

 

3. How to fix the compilation issues if exists

An alternative, as mentioned in previous comment, is to require a specification provide a "migration path" type section to release notes when there are breaking changes, which outlines how to move from the old to the new. It would also be good if that content was posted as a blog as well as not everyone reads release notes.

 

4. In the umbrella release, there should be a section to call out all the break changes.

These just food for thoughts. Please share your opinion.

Thoughts?

Emily

--
You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/28d5a819-3d74-4372-9d2f-308976a0c37e%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Emily Jiang]

Ken,

Thanks for your comments!

A migration description is a far cleaner alternative. If we require, or even just recommend, specifications provide a way to retain "old" behavior, we add complexity for implementations to try and support both.

 Just want to follow up with this. We discussed on MP Architecture call. This will be left for each spec to make decision. I know Metrics introduced a breaking changes

e.g. In order to reserve the old behaviour of @Counted, the solution is to use @ConcurrenctGuage, which clearly tells the customer how to reserve the old behaviour. What I meant is the berhaviour, not the API.

If no one has any objections or any new comments by the end of this week, I will write this part of Spec release requirement and get it clearly documented in our wiki.

Emily

On Tuesday, April 23, 2019 at 3:17:17 PM UTC+1, Ken Finnigan wrote:

On Tue, Apr 23, 2019 at 9:20 AM 'Emily Jiang' via Eclipse MicroProfile <microp...@googlegroups.com> wrote:

MicroProfile 3.0 release date is fast approaching and this release will likely include the following 3 specs (all of them containing breaking changes). As MP 3.0 will be the first release containing backward incompatibility changes. We need to standardise the way how to communicate breaking changes.

1. Metrics 2.0

2. Health Check 2.0

3. Open API 2.0

Although MicroProfile allows breaking changes, I think we must ensure MP end users' life as easier as possible by documenting the breaking changes clearly and provide a way to achieve the old behavior if possible.

See the issue I raised for MP Architecture and Ken suggested bringing this topic for a wider discussion (see https://github.com/eclipse/microprofile/issues/99).

I suggest:

1. Each spec have a dedicated section labeling backward incompatibility changes

Should mandate that release notes included a "Breaking Changes" section for every release, even if most of the time it has "None".

 

2. Provide a solution how to achieve the old behaviour if possible

A migration description is a far cleaner alternative. If we require, or even just recommend, specifications provide a way to retain "old" behavior, we add complexity for implementations to try and support both.

 

3. How to fix the compilation issues if exists

An alternative, as mentioned in previous comment, is to require a specification provide a "migration path" type section to release notes when there are breaking changes, which outlines how to move from the old to the new. It would also be good if that content was posted as a blog as well as not everyone reads release notes.

 

4. In the umbrella release, there should be a section to call out all the break changes.

These just food for thoughts. Please share your opinion.

Thoughts?

Emily

--
You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microp...@googlegroups.com.