or should we assume people use CLI properly, they use always a fixed version, and the same with templates - always specific version. So they will not notice issues, and basically upgrade only when they feel a need and other projects are ready?

When you say they use always a fixed version you mean templates version right? this is something we could get from insights we are collecting (cc @peter-rr )

I mean, that in theory people in production should never install CLI as npm install @asyncapi/cli but npm install @asyncapi/[email protected] for example.

Same with templates, in production, in pipelines they should run generation with templates not pointing like here, to latest: asyncapi generate fromTemplate asyncapi.yaml @asyncapi/nodejs-template but for example asyncapi generate fromTemplate asyncapi.yaml @asyncapi/[email protected].

The problem is - can we assume people do it properly, can we "expect" them do it like this - and have it as defined assumption - so they always manually decide to use new version? the problem with this assumption is that it is not the best DX 🤔 So probably philosophy here should be to always assume people not always read docs, and we should somehow proactively protect them.

From my perspective, always better to enable support for new generator version (or optimizer or anything else) and set the older one to deprecate with some period to have it enabled, and then removed 🤔 really hard to decide

From my perspective, always better to enable support for new generator version (or optimizer or anything else) and set the older one to deprecate with some period to have it enabled, and then removed 🤔 really hard to decide

no other option really. We can educate through docs: https://www.asyncapi.com/docs/tools/generator/versioning but this is in my opinion just to make our lives easier, not users

When you say they use always a fixed version you mean templates version right? this is something we could get from insights we are collecting (cc @peter-rr )

Sure! Currently we are collecting the template used, and also the CLI version if specified by the user, according to the documentation. I guess we could collect the template version as well if needed 🤔

So the different use cases are:

• asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template will produce:

asyncapi_adoption.action.finished       COUNTER {
  user: '5db8f33f-320c-4d50-85a5-7e8135c33380',
  action: 'generate:fromTemplate',
  template: '@asyncapi/html-template',
  success: true,
  asyncapi_version: '3.0.0',
  asyncapi_servers: 1,
  asyncapi_channels: 1,
  asyncapi_messages: 1,
  asyncapi_operations_send: 0,
  asyncapi_operations_receive: 1,
  asyncapi_schemas: 4
}       1

• asyncapi generate fromTemplate asyncapi.yaml @asyncapi/[email protected] will produce:

asyncapi_adoption.action.finished       COUNTER {
  user: '5db8f33f-320c-4d50-85a5-7e8135c33380',
  action: 'generate:fromTemplate',
  template: '@asyncapi/[email protected]',
  success: true,
  asyncapi_version: '3.0.0',
  asyncapi_servers: 1,
  asyncapi_channels: 1,
  asyncapi_messages: 1,
  asyncapi_operations_send: 0,
  asyncapi_operations_receive: 1,
  asyncapi_schemas: 4
}       1

We can leverage also the efforts @Shurtu-gal is making to improve DX CLI, for instance if we want to force users to explicitly mention versions we can show a documentation link that shows the versions map between generator and templates.

ok, so we look at a solution to support different version of generator in the CLI, right?

Yes @derberg I think it's the most DX friendly option.

are you, maintainers, will work on it or you have no capacity and rather expect contribution?

I think @peter-rr or @AayushSaini101 will be interested in picking it up with some support.

We can submit this as a bounty issue for Q3-2024

ok, but then we're talking about July. So until July nobody will be able to use new AsyncAPI Generator

ok, but then we're talking about July. So until July nobody will be able to use new AsyncAPI Generator

@Amzani Should we add then this issue to the current DX Working Group's cycle?

@peter-rr done

Scope update:

• Discover how we can support both generators (v2 and < v2)

Working on the implementation now.