Test emulated changes against the API

[jonaslagoni]

After https://github.com/asyncapi/shape-up-process/issues/93 we should test the emulated changes against the API to ensure that it do not break it.

[jonaslagoni]

Copy pasted from https://github.com/asyncapi/parser-js/pull/263#issuecomment-806996059

Emulated breaking changes

We needed to test the intents based on different changes from https://github.com/asyncapi/shape-up-process/issues/93

3.0.0-fake

Assumptions:

• Only one operation type (publish/subscribe) per channel

Intents:

• (GOOD) Channel.messagesSubscribes('<role>') : Message[]
• (GOOD) Channel.messagesPublishes('<role>') : Message[]
• (GOOD) Channel.summaryForPublishing('<role>') : string
• (GOOD) Channel.summaryForSubscribing('<role>') : string

3.0.0-fake2

Because this makes it possible to define multiple schema formats per message, it is no longer a 1:1 (message:schemaFormat) but a 1:* and breaks the return values

• (QUESTIONABLE) Message.schemaFormat() : string (this intent is not part of the initial suggestion, but added to support the breaking change example)
  • This could return multiple schema formats

3.0.0-fake3

Because this makes it possible to define multiple operations per channel, it is no longer 1:1 (channel:operation) but a 1:* and breaks the return values

• (GOOD) Channel.messagesSubscribes('<role>') : Message[]
• (GOOD) Channel.messagesPublishes('<role>') : Message[]
• (QUESTIONABLE) Channel.summaryForPublishing('<role>') : string
  • This could return multiple summaries.
• (QUESTIONABLE) Channel.summaryForSubscribing('<role>') : string
  • This could return multiple summaries.
• (QUESTIONABLE) Channel.operationIdForPublishing('<role>') : string
  • This could return multiple ids.
• (QUESTIONABLE) Channel.operationIdForSubscribing('<role>') : string
  • This could return multiple ids.

3.0.0-fake4

Because this makes it possible to define multiple messages under a channel, and those messages can contain operations we no longer have a 1:1 (channel:operation) but a 1:* and breaks the return values

• (GOOD) Channel.messagesSubscribes('<role>') : Message[]
• (GOOD) Channel.messagesPublishes('<role>') : Message[]
• (QUESTIONABLE) Channel.summaryForPublishing('<role>') : string
  • This could return multiple summaries.
• (QUESTIONABLE) Channel.summaryForSubscribing('<role>') : string
  • This could return multiple summaries.
• (QUESTIONABLE) Channel.operationIdForPublishing('<role>') : string
  • This could return multiple ids.
• (QUESTIONABLE) Channel.operationIdForSubscribing('<role>') : string
  • This could return multiple ids.

    Conclusion

    As you can see we have a problem with the cardinality of return values in general..

The only apparent solution is to return an array of values, always, to be safe. But this is affecting the toolings using the parser making it more difficult...

[jonaslagoni]

We need to take a design decision in regard to the breaking changes and how we want to guard the API.

1. Always return arrays This makes it somewhat harder for developers to use. We would have to change Message.schemaFormat() : string to return string[] instead.

2. Accept it will be breaking changes when the cardinality of return values changes We simply accept that any cardinality changes to the return values will create a breaking change.

[derberg]

cardinality changes

sorry but I have no idea what cardinality means in this context, you mean function return type?

[jonaslagoni]

cardinality changes

sorry but I have no idea what cardinality means in this context, you mean function return type?

Yes, updated the comment :)

[fmvilas]

Accept it will be breaking changes when the cardinality of return values changes We simply accept that any cardinality changes to the return values will create a breaking change.

I'd go for this solution. In case it happens, we can always default to returning the first value of the array and add another method that will return the array for those who want to upgrade to the new functionality. For instance:

Message.schemaFormat() : string would remain the same but we add Message.schemaFormats() : string[]. At some point, we remove the first method.

Might not be perfect but it's an easy-to-handle situation.

[jonaslagoni]

Copy pasted from https://github.com/asyncapi/parser-js/pull/263#issuecomment-816652619

With a new iteration for the intent API another round of checking breaking changes.

Emulated breaking changes

It seems like we solved the problems of the breaking changes we had in the last suggestion 👏

3.0.0-fake

Since we already return an array of operations, this will not break the parser API.

3.0.0-fake2

Does not break the parser API since we can add support function such as getAllSchemaFormats to the standard getSchemaFormat so we deprecate the old function as time goes on.

3.0.0-fake3

Still works since we have a bidirectional flow of channels, messages, and operations already.

3.0.0-fake4

Still works since we have a bidirectional flow of channels, messages, and operations already.

[jonaslagoni]

I think we have a pretty good understanding of what will force breaking changes moving forward. Think we can close this issue, what do you think @smoya ?

[smoya]

+1 @jonaslagoni