-
-
Notifications
You must be signed in to change notification settings - Fork 74
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Inspecting bindings for spec 3.0 #182
Comments
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
As the spec changes are nearly there, it's time to inspect the bindings. Tagging code owners. @rcoppen do you have the bandwidth to inspect |
Generally, for all bindings the following applies:
Further more, we do not add features here, it's only about adapting to the new 3.0 structure. Here is the inspection of the other bindings: amqp
amqp1
anypointmq
http
jms
mercure
mqtt
mqtt5
nats
redis
sns
sqs
stomp
websockets
|
I am gonna create individual PRs for each protocol above for it to make sense on a review point of view. |
I will gladly take care of the |
@whitlockjc just had a quick look:
But that's about it I think 🤔 |
Is there some existing documentation on an 'upgrade path' for V3? Not for bindings, but for the V3 spec. |
@VisualBean I am on it, finishing the release notes today that you can use as guidelines. |
I have updated the release notes: Read it here: https://deploy-preview-659--asyncapi-website.netlify.app/blog/release-notes-3.0.0 (asyncapi/website#659) The migration guide has not been finalized, but it does contain some information, might be useful as well: https://deploy-preview-660--asyncapi-website.netlify.app/docs/migration/migrating-to-v3 (asyncapi/website#660) You can also find the most recent spec document here: https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12 cc @VisualBean |
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
Kindly pinging @rcoppen please inspect ibmmq binding |
I think the pulsar bindings are fine as is. |
Hey there, I think that Kafka bindings are globally fine, but examples have to be adapted because we have bindings at the operation and the message levels. That said, I have a general concern regarding the versioning of bindings and the matching with the spec versions. Today, we have bindings with This is a bit confusing to me because of:
I would have thought of other options for versioning In the case of no binding schema update:
What do you think? Am I the only one to be a bit confused on this? |
No, you are not the only one for sure. I also think it might look very confusing, and forcing the users to carry on with that complexity is not desired IMHO.
I think this option helps reducing that complexity. However, I don't think we can force or ensure all bindings versions will follow such versioning strategy. For example, what if a binding needs to introduce a breaking change? Will it mean its version can't increase in one major because no new major spec version is out? I would keep the idea of releasing a major for each major spec version that is supported, but keeping a table in the markdown that shows a compatibility matrix, mapping binding version with supported AsyncAPI major versions. |
Thanks @dalelane and @smoya for the comments! I also think that transitioning from AsyncAPI 2.x to 3.x will take some time and I am afraid that linear versioning will introduce confusion... Imagine I'm still using AsyncAPI 2.x and I'd like to propose a change to a binding - starting with the following situation:
In case of a non-breaking change:
In case of a breaking change:
I'm scratching my head over this... and I am sorry if it has already been discussed elsewhere 😖 Shall we adopt another versioning scheme clearly stating the major spec number? Ex: |
Love this discussion, keep going you are definitely on the right track 👏
Just for the record, I have no preference for a solution, I just used the simplest approach for bumping the binding versions, because, for AsyncAPI v2, I would still like to be able to use the old bindings with the proper definitions and descriptions (i.e. not AsyncAPI v3). That's why it was bumped even though only the description/constraint changed 🙂 But yea, could also just as well have added v3-specific information along side v2, just didn't come up 😄 Somewhat related to asyncapi/spec#590 |
+1 on this |
@dalelane @lbroudoux any of you have the bandwidth to update the examples, or possibly create a good first issue for it? |
I should be able to do it at the end of the week. |
As I'll probably work on the PR tomorrow, do you think about the versioning convention above? @dalelane: What do you think of having this |
Technically it's all yours and @dalelane decision @lbroudoux 👍 But from my side, I do not see anything wrong with trying out different version strategies across different bindings, as long as it's well-documented (compatibility matrix would probably be a good idea) 👍 The strategy that works the best will win over time 😄 So I think at some point it will most likely be aligned 👍 |
@lbroudoux I notice something went wrong with the last merge https://github.com/asyncapi/bindings/blob/master/kafka/README.md?plain=1#L148 https://github.com/asyncapi/bindings/blob/master/kafka/README.md?plain=1#L155 Do you want to do this as part of the PR for this? Or shall we fix it separately? |
Will integrate it in the PR. I will then produce 2 versions of the binding integrating this fix:
I propose to split the README file into 2 different files (keeping the main one to introduce both versions and include a compatibility matrix) and add subfolders to I think I will not have the bandwidth to finalize today but probably during the weekend. |
@lbroudoux Remember to make the JSON Schema changes in the spec-json-schema repo 😄 They will be removed soon from this repository. |
Oops! Forgot about that. Thanks @jonaslagoni for the reminder! |
Following our previous discussions, I have created: Feel free to review and comment 😉 |
Hey, do not wanna be a party pooper but just had a look at and I'm very confused, especially
You won't be able to do it as nobody want to deal with old versions and remember both ways. I for example plan to forget v2 world as soon as possible 😄
I'm not sure what PR and changes you mean exactly, but So if in README nothing changes, maybe just examples, then version should not change examples:
does it somehow help? tl;dr |
of course happy to hop on a call if anybody needs |
Hey Lukasz, Thanks for the comments.
I asked this question in the past, and the answer wasn't that assertive.
I think that organizations that already invest in AsyncAPI and manage several specs may take some time to migrate to v3 and adapt their toolchain as well. I think it's usually great to have flexible migration paths and be able to dissociate migrating the abstract level (the The other concern I had with the single-digit bump (or no bump if not required) was about the compatibility matrix. As versioning among the bindings is not homogeneous (some are The above concerns found some echo, but if we're happy going the way of breaking changes, constrained upgrades and compatibility matrix, that's also fine for me. We'll just have to revert some stuff. The most important thing here is to be clear that - as you said: "When we release v3 and somebody using v2 wants a new feature, they need to migrate to v3 and add a feature to v3" Cheers, |
It is a complicated topic, as on one hand bindings are there, maintained by different people to assure flexibility, but on the other hand when I look at it as the good thing is that in JSON Schemas that describe the spec, for 2.6 and prior, we have zero constraints -> https://github.com/asyncapi/spec-json-schemas/blob/next-major-spec/definitions/2.6.0/bindingsObject.json. So people can put whatever they want (and they actually do it already, and for example in docs generation we take whatever is there and do not fail AsyncAPI document validation). This means that if they really want to add something to v2 instead of migrating to v3 - they can add it, but not through official bindings-contribution process. And it is up to the tooling, if something is supported or not. if we wanna change the approach, we need a dedicated discussion where we make sure all owners are notified and follow.
I completely agree but this can be consistently solved with GitHub tags. So whenever we release main specification, we tag
The new constraint would be that if you add something new to Kafka binding, it needs to wait for main spec release to be supported. This is not a problem though as we anyway release spec regularly 4 times a year. Scenario:
it is just a rough idea 🤔 basically wanna visualize what options we have other than doing custom-per-binding approach. Thoughts? so my suggestion:
@smoya @char0n @fmvilas @dalelane your view so we can somehow move forward? |
I'm interested in how common this use case or need @lbroudoux mentioned:
It is just a feeling or it is really a need users are asking for? I don't know about numbers, metrics or provided company use cases that speak about this, but that doesn't mean this is not common. The answer to this question is, IMHO, the critical decision maker here. Any thoughts? |
Hey friends! Thanks for your detailed thoughts on this. I think the most important part of it that I agree with is:
So as a conclusion, I propose to edit a new PR for Kafka bindings just adapting the Also, before issuing this new PR, I'll merge #220 so that it will be quickly available. Finally, I propose to be collectively vigilant on this point I mentioned above:
I agree that this is currently a feeling on a requirement and not a user's feedback. But I have experience with large organizations where those 2 concerns (channel & message definitions vs bindings choices) would be handled by different personas, at different times within an API lifecycle. Don't know if AsyncAPI has adopters yet in that kind of organizations but better watch out. |
Hey folks, as this issue was solely focused on getting the bindings up to date with v3, I am gonna close down the issue. Thanks for all the help with updating and inspecting bindings @lbroudoux @whitlockjc @VisualBean @smoya @derberg @mboss37 🙏 I suspect it's not the final discussion we are gonna have on versioning bindings either, if we need further discussion please create an issue 💪 |
yes, I encourage anyone to open up a followup issue with details on use case whenever if your communities you hear people complaining about how bindings work with asyncapi spec, and stuff like that, migrations and other topics |
Reason/Context
We have no overview of how the spec 3.0 changes affect the bindings. Or if they even affect them at all. We also need to figure out if we need to make spec 3.0 specific bindings, how to visualize them.
Preliminary possible binding changes:
This issue are meant as a placeholder until the changes in the spec are finalized where code owners will be pinged for feedback.
The text was updated successfully, but these errors were encountered: