generator

generator copied to clipboard

Release 3.0 spec getting closer, although it's unclear when it will be released :smile:

Due to the fact that most probably 3.0 will have a lot of breaking changes, which introduce breaking changes in our parser-js, we should think about a new major version of the generator.

NOTE: The 2.0 parse-js's release will result in a 2.0 generator's release due to the fact that the models API will be different and this will cause incompatibility with templates.

Since the 2.0 release is dictated by the 2.0 parser release, we should consider what we would expect from the 2.0 generator release. We can release 2.0 only with the new parser API included, but we can also fix some things that we currently can't fix because it would cause a new major version.

Here is my list of things we can fix in the new version:

• rewrite to TS (part of https://github.com/asyncapi/generator/issues/468) - cli, server-api which use generator will only benefit from this, because they are written in TS
• defining the generator parameters as JSON Schema for better validation (https://github.com/asyncapi/generator/issues/414) - this will not only help us to get a better UX but also allow us to create for example forms in the studio for the parameters (based on JSON Schema) and allow better validation of the parameters on the server-api side. We can also think about prompts as nice feature :)
• in-memory generation (https://github.com/asyncapi/generator/issues/468) - the biggest change I would like to see. There are few use cases where such generation would have benefits rather than current solution (file generation):
  • easier, safer and faster generation of templates in a typical server-side environment, where you shouldn't have to operate on files. The current solution in server-api is to save the whole generated template in temporary folder, then save the folder to a zip, send it to the client and delete the folder. Very bad solution, we should prevent IO as much as possible.
  • easier handling of generated files in generator hooks. For example, here we are operating again on a filesystem, but we should rather operate on a virtual filesystem.
  • easier to handle --watch-templates cli flag
  • future use case: combining template generation with studio and server-api on AsyncAPI doc changes in the studio using streams :)
• remove cli from generator repo and move it to the cli repo - we will force people to use it :trollface:
• we can also go forward with https://github.com/asyncapi/generator/issues/580 and with https://github.com/asyncapi/generator/issues/538

So what do you think? What other changes would you like to see? I purposely didn't give Nunjucks removal because it needs to be discussed whether it makes sense if most of the templates are written in Nunjucks anyway and not in JSX. And anyway we should change name of React to JSX renderer because it's not the same. React is only an implementation of JSX.

Comments are more than welcome :)

yo, please correct me but not of the above changes must be breaking changes, thus I do not see correlation with spec release.

For example: removing CLI is not breaking change, we just remove it, but won't remove old versions from npm, right? or actually it is not doable without breaking stuff 🤔

No comments from my side about rewriting... 😄

@derberg

yo, please correct me but not of the above changes must be breaking changes, thus I do not see correlation with spec release.

No everything, this can be handled as fix/feat, not feat!, but other things should be consider as breaking change

For example: removing CLI is not breaking change, we just remove it, but won't remove old versions from npm, right? or actually it is not doable without breaking stuff 🤔

I think that's the breaking change, because people can use generator in the cli by installing latest version (in some script) from 1.X.X (by npx ...), so yeah it will broke their logic. We can say: from 1.X.X we will remove cli and move it to the @asyncapi/cli and it's a breaking change, we will remove huge part from source code. If removing a flag from the current generator cli would be considered a breaking change, what about removing the entire cli? And moving to another repo still results in deleting the cli in that repo.

Similar situation we have in the one spec feature https://github.com/asyncapi/spec-json-schemas/pull/146#issuecomment-1016290582

I also wondered if https://github.com/asyncapi/generator/issues/414 should be breaking change but I think should, because an object in JSON Schema should have required field outside parameters/properties and not inside parameter/property like current we have.

And memory-generation - it will be huge change, especially for hooks. Atm it's impossible to implement such a feature, due to fact that some hooks operate on the FS and IO operation like here https://github.com/asyncapi/html-template/blob/master/hooks/01_removeNotRelevantParts.js#L24 so we need always write content to the files, we cannot "hang" that content in the memory.

No comments from my side about rewriting... 😄

Don't worry, Glee is already rewritten, ParserJS will be too, it's just a matter of time that the generator will be too :trollface:

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

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 :heart:

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

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 :heart:

Maybe after ParserJS 2.0.0 release I will handle that task 😏

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

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 :heart:

leaving it closed no need to have roadmap to 2.0

if there is a feature that requires 2.0, do it, if after a month there is a new one that requires 3.0 release - do it