docs: added the migration guide for depreciation of nunjucks #1253
Conversation
Gmin2
requested review from
Florence-Njeri,
derberg and
asyncapi-bot-eve
as code owners
🦋 Changeset detectedLatest commit: 826f203 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
|
|
||
| ### 5. File template | ||
|
|
||
| //TODO: we can add a link to Florence docs once it is merged |
There was a problem hiding this comment.
Hey @Gmin2 You can already link the doc since I updated the current File template doc
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 |
|
Description
Add a migration guide markdown to migrate from nunjucks to react render engine
Related to #1255