fix: add the migration guide and nunjucks depreciation notes #1253
Conversation
Gmin2
requested review from
Florence-Njeri,
derberg and
asyncapi-bot-eve
as code owners
🦋 Changeset detectedLatest commit: cc50175 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
|
no, we deprecate it now, inform people that removal will take place in a year. So critical is to inform when and what functionality is removed, and how to migrate to alternative - react |
There was a problem hiding this comment.
Hey @Gmin2 I have left a few suggestions that you can apply to the doc. The only things I noted are:
- We use sentence case for all our docs heading
- Ensure consistency in docs especially what you capitalize e.g if Nunjucks is capital in one place, let make it capitalized everywhere
There was a problem hiding this comment.
- have a look on PR from @lmgyuan about cli deprecation. We need similar detailed information here, about deprecation of nunjucks september 2025
- great we have migration guide, but we also need warning is other generator documents, where nunjucks is explained, and provide clear short note about deprecation, that will link to your guide
- in migration guide please also point people to https://github.com/asyncapi/template-for-generator-templates and explain that in master branch they see all react-features in use and if they switch to nunjucks branch, they see old features. Basically you did not cover all the features, so safe is to link there as well
- in guide please mention that nunjucks filters that people placed in
filtersdir can still be used but as normal functions that you import in your components, and therefore we also recommend to rename them tohelpers. - in guide mention that hooks stay as they are - no change there as it is not render engine related functionality
- also in intro of migration guide, and probably also in description of release, please link to https://www.asyncapi.com/blog/react-as-generator-engine article and introduce as an article why we introduced react in 2021 as alternative, and that the same principles apply to remove nunjucks entirely
- proper code must also be marked as deprecated: https://jsdoc.app/tags-deprecated
@Florence-Njeri in case of CLI deprecation, we no longer mention old ag in docs, only in migration guide. Maybe we should do the same with nunjucks? maybe to make it much easier to maintain documentation, all documentation should be updated and mention react only - except of the guide from @Gmin2 ? For example we probably should:
- remove https://github.com/asyncapi/generator/blob/master/apps/generator/docs/nunjucks-render-engine.md?plain=1 and provide redirect to migration guide?
- and probably remove any mention from any documents like https://github.com/asyncapi/generator/blob/master/apps/generator/docs/template.md?plain=1
thoughts?
| } | ||
| ``` | ||
|
|
||
| ### 4. Macros |
There was a problem hiding this comment.
|
any updates @Gmin2 ? |
@derberg dont you think this needed to be in the issue itself, not in the PR, as this is a migration guide thoughts @lmgyuan @Florence-Njeri ? |
|
@Gmin2 that was 3 weeks ago so I don't 100% remember what I was referring to, but afaik, it was about the README.md |
| @@ -21,6 +22,7 @@ module.exports.registerFilters = async (nunjucks, templateConfig, templateDir, f | |||
|
|
|||
| /** | |||
| * Registers the local template filters. | |||
| * @deprecated since version 3.0 | |||
There was a problem hiding this comment.
i have assumed this to be included in the next major release, is this fine @derberg ?
There was a problem hiding this comment.
no it won't, so we cannot predict version of the release since it is deprecated
just write @deprecated without any specific note
There was a problem hiding this comment.
if jsdocs allows it, please use a link, and text specifying that more info someone can find in https://www.asyncapi.com/docs/tools/generator/nunjucks-react-migration
|
Hey updated the changes, take a look |
|
|
||
| ### Conclusion | ||
|
|
||
| Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable. You can learn more about why we introduced ther React render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine) |
There was a problem hiding this comment.
| Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable. You can learn more about why we introduced ther React render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine) | |
| Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable. You can learn more about why we introduced ther React render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine) |
| Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable. You can learn more about why we introduced ther React render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine) | |
| Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable code. You can learn more about why we introduced the React render engine [here](https://www.asyncapi.com/blog/react-as-generator-engine) |
There was a problem hiding this comment.
@Gmin2 when you apply this change, please also improve the list - as per my other comment about links
Hey @Gmin2, I have left a few suggestions. Please try and run the docs in Grammarly to catch some of the spelling mistakes
derberg
changed the title
|
derberg
changed the title
There was a problem hiding this comment.
@Gmin2 sorry mate but still a bit of work to do
@Florence-Njeri please also have a look, I need you in few areas
| @@ -0,0 +1,5 @@ | |||
| --- | |||
| "@asyncapi/generator": major | |||
There was a problem hiding this comment.
it is not a major release, otherwise we would use ! in the PR title prefix.
Major is when we introduce breaking changes - and here are no breaking changes, we just need to release minor to make sure added deprecation notes are visible to the user in the distro.
| "@asyncapi/generator": major | |
| "@asyncapi/generator": minor |
| weight: 170 | ||
| --- | ||
|
|
||
| ## Migration Guide from nunjucks render engine to react render engine |
There was a problem hiding this comment.
please remove
| ## Migration Guide from nunjucks render engine to react render engine |
@Florence-Njeri @Gmin2 below you can see a preview from website, how would this document render - we would have strange duplication.
|
|
||
| ## Migration Guide from nunjucks render engine to react render engine | ||
|
|
||
| ### Introduction |
There was a problem hiding this comment.
| ### Introduction |
when you see other generator docs, we don't write "introduction" we just write it without heading
- https://www.asyncapi.com/docs/tools/generator/template-context
- https://www.asyncapi.com/docs/tools/generator/model-generation
- https://www.asyncapi.com/docs/tools/generator/react-render-engine
we can of course change it if you think it is wrong, but then it should be a followup PR that unifies approach in all generator docs
|
|
||
| ### Introduction | ||
|
|
||
| The asyncAPI generator is moving away from Nunjucks templates in favor of React templates. This guide will help you migrate your existing Nunjucks templates to React. For a comprehensive understanding of why we introduced React as an alternative in 2021 and why we're now removing Nunjucks entirely, please read our article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine). The principles discussed in this article still apply to our current transition. |
There was a problem hiding this comment.
| The asyncAPI generator is moving away from Nunjucks templates in favor of React templates. This guide will help you migrate your existing Nunjucks templates to React. For a comprehensive understanding of why we introduced React as an alternative in 2021 and why we're now removing Nunjucks entirely, please read our article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine). The principles discussed in this article still apply to our current transition. | |
| The generator is moving away from Nunjucks templates in favor of React templates. This guide will help you migrate your existing Nunjucks templates to React. For a comprehensive understanding of why we introduced React as an alternative in 2021 and why we're now removing Nunjucks entirely, please read our article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine). The principles discussed in this article still apply to our current transition. |
| "@asyncapi/generator": major | ||
| --- | ||
|
|
||
| Migrating from Nunjucks render engine to React render engine |
There was a problem hiding this comment.
| Migrating from Nunjucks render engine to React render engine | |
| [Nunjucks render engine](https://www.asyncapi.com/docs/tools/generator/nunjucks-render-engine) is deprecated and will be removed in October 2025. Use [React render engine](https://www.asyncapi.com/docs/tools/generator/react-render-engine) instead. If you already use Nunjucks in production, we have a [migration guide](https://www.asyncapi.com/docs/tools/generator/nunjucks-react-migration) that will help you understand how to migrate to a new engine. |
| @@ -21,6 +22,7 @@ module.exports.registerFilters = async (nunjucks, templateConfig, templateDir, f | |||
|
|
|||
| /** | |||
| * Registers the local template filters. | |||
| * @deprecated since version 3.0 | |||
There was a problem hiding this comment.
no it won't, so we cannot predict version of the release since it is deprecated
just write @deprecated without any specific note
| @@ -21,6 +22,7 @@ module.exports.registerFilters = async (nunjucks, templateConfig, templateDir, f | |||
|
|
|||
| /** | |||
| * Registers the local template filters. | |||
| * @deprecated since version 3.0 | |||
There was a problem hiding this comment.
if jsdocs allows it, please use a link, and text specifying that more info someone can find in https://www.asyncapi.com/docs/tools/generator/nunjucks-react-migration
|
|
||
| The asyncAPI generator is moving away from Nunjucks templates in favor of React templates. This guide will help you migrate your existing Nunjucks templates to React. For a comprehensive understanding of why we introduced React as an alternative in 2021 and why we're now removing Nunjucks entirely, please read our article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine). The principles discussed in this article still apply to our current transition. | ||
|
|
||
| ### Step-by-step migration guide |
There was a problem hiding this comment.
probably because of my previous comments you will have to do changes to heading sizes, and start this from "##" and update the rest as well
| #### 6. File template | ||
|
|
||
| The detailed guide on file template can be found in [this](file-templates.md) guide. | ||
|
|
There was a problem hiding this comment.
| #### 7. Models generation | |
| If you have a template written with Nunjucks, it is almost certain that you have your own custom models/classes/types templates in place. Instead of migrating them to React render engine we strongly advise you to delegate models generation to AsyncAPI Modelina project. Learn more on [how to add models generation using Modelina](https://www.asyncapi.com/docs/tools/generator/model-generation). | |
totally new section that I think is important to have, to safe people time
| 1. Run the generator using your new React template | ||
| 2. Compare the output with the previous Nunjucks template output | ||
| 3. Check for any missing or incorrectly rendered content | ||
|
|
There was a problem hiding this comment.
| You might want to consider implementing snapshot tests for your template before starting migration. This will ease the review of changes in content rendered after render engine changes. Snapshot tests allow you to have tests that will persist expected output from Nunjucks template, and compare it with output produced after you do the migration. Check the [example of such snapshot integration test for our internal react template we use for development and testing](https://github.com/asyncapi/generator/blob/master/apps/generator/test/integration.test.js#L66). | |
Description
Add a migration guide markdown to migrate from nunjucks to react render engine
Related to #1255