Migration Guide to md & post-installation script to deprecate cli.js

[lmgyuan]

Per discussions about the #1226, we want to include a post-installation script to notify people that we are deprecating the cli.js in generator repository and offer them migration information. We also want to have a migration guide in the ReadMe or Website to guide developers on how to migrate from ag to AsyncAPI CLI.

[lmgyuan]

Adding a markdown version of the migration guide for discussions.

Migration Guide from “ag/asyncapi-generator” to AsyncAPI CLI

Overview

With the introduction of the AsyncAPI CLI, the use of Cli.js for documentation generation in the AsyncAPI generator repository is being deprecated. This guide provides detailed instructions on how to transition from ag to the new AsyncAPI CLI.

Why Migrate?

• Enhanced Features: The AsyncAPI CLI offers advanced features and improvements.
• Consistency: Ensures consistent command usage across different environments.
• Support and Maintenance: Future updates and support will focus on the AsyncAPI CLI.

Deprecated ag/asyncapi-generator Options and Their AsyncAPI CLI Equivalents

Here is a list of ag/asyncapi-generator options and their equivalents in the AsyncAPI CLI:

• -d, --disable-hook [hooks...]

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --disable-hook <hookType>=<hookName>

• --debug

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --debug

• -i, --install

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --install

• -n, --no-overwrite

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --no-overwrite <glob>

• -o, --output

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --output <outputDir>

• -p, --param <name=value>

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --param <name=value>

• --force-write

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --force-write

• --watch-template

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --watch

• --map-base-url url:folder

  • AsyncAPI CLI Equivalent: asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --map-base-url <url:folder>

Migration Steps

1. Install AsyncAPI CLI

First, ensure you have the AsyncAPI CLI installed:

npm install -g @asyncapi/cli

2. Update Your Commands

Replace the deprecated Cli.js commands with their AsyncAPI CLI equivalents. Below are examples of how to update your commands:
Example Migration:
Before Migration (Using Cli.js):

ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName

After Migration (Using AsyncAPI CLI):

asyncapi generate fromTemplate ./asyncapi.yaml ./template --output ./output --param param1=value1 --debug --install --disable-hook hookType=hookName

3. Verify and Test

Run the updated commands to ensure they work as expected. Verify the output and ensure that all files are generated correctly.

4. Enable Watch Mode (Optional)

If you were using the --watch-template option, you can now use the watch mode in the AsyncAPI CLI:

asyncapi generate fromTemplate ./asyncapi.yaml ./template --output ./output --watch

Additional Resources

CLI Documentation: AsyncAPI CLI Documentation
Installation: AsyncAPI CLI Installation
Usage: AsyncAPI CLI Usage
Support: For any issues or questions, please create an issue in our CLI repository.

Conclusion

By following this migration guide, you can smoothly transition from Cli.js to the AsyncAPI CLI, taking advantage of its enhanced features and improved performance. If you have any questions or need further assistance, feel free to contact us.

Happy coding!

[lmgyuan]

The post-installation script to display after developers install the generator:

// postinstall.js
console.log(`
*************************************
*                                   *
*  DEPRECATION NOTICE               *
*                                   *
*************************************

The use of 'Cli.js' for documentation generation is deprecated and will be removed in future releases.

Please migrate to the new AsyncAPI CLI using the following guide:

1. Install AsyncAPI CLI:
   $ npm install -g @asyncapi/cli

2. Update your commands:
   Replace the deprecated 'Cli.js' commands with their AsyncAPI CLI equivalents.

Example Migration:

Before Migration (Using 'Cli.js'):
$ node Cli.js ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName

After Migration (Using AsyncAPI CLI):
$ asyncapi generate fromTemplate ./asyncapi.yaml ./template --output ./output --param param1=value1 --debug --install --disable-hook hookType=hookName

For more details, please visit: [Migration Guide URL]

Thank you for your understanding and cooperation.
`);

[lmgyuan]

We should talk to Thulie about adding a link or a short paragraph in her newsletter about the migration.

[lmgyuan]

https://www.asyncapi.com/blog/2024-july-summary

add a paragraph about Nunjucks and cli.js deprecation in the spec x tooling section

Final agreements on where to put the guide:
ReadMe, a paragraph on the website, Thulie's newsletter