From cfd2ceb70b4343518b69ea7836f84bb451682dd7 Mon Sep 17 00:00:00 2001 From: utnim2 Date: Sun, 11 Aug 2024 01:31:29 +0530 Subject: [PATCH 1/5] added the developement guide --- Development.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 Development.md diff --git a/Development.md b/Development.md new file mode 100644 index 000000000..656111e7a --- /dev/null +++ b/Development.md @@ -0,0 +1,77 @@ +# Development Guide + +This guide will help you set up the `generator` locally, run tests, and use Docker for isolated testing. + +## Getting Started + +1. Clone the repository: + +```bash +git clone https://github.com/asyncapi/generator.git +cd generator +``` + +2. Install dependencies: + +```bash +npm install +``` + +## Running Tests + +### Local Testing + +To run all tests locally: + +- Unit tests: `npm run generator:test:unit` +- Integration tests: `npm run generator:test:integration` +- CLI tests: `npm run generator:test:cli` + +### Adding Tests + +1. Create new test files in the appropriate directory under `test/`: + +2. Follow the existing test patterns. + +3. Run your new tests using the commands mentioned above. + +## Docker Isolated Testing + +To run tests in an isolated Docker environment: + +1. Ensure Docker is installed and running on your machine. + +2. Run the following command from the project root: + +```bash +docker run --rm -v ${PWD}:/app -w /app node:18 sh -c " +cp -r /app /tmp/app && +cd /tmp/app && +npm install && +npm test +" +``` + +This command does the following: +- Mounts the current directory to `/app` in the container +- Copies the project to a temporary directory +- Installs dependencies +- Runs all tests + +Note: This approach ensures a clean environment for each test run by removing any existing `node_modules`. + +## Additional Commands + +- Lint the code: `npm run lint` +- Generate documentation: `npm run docs` +- Build Docker image: `npm run docker:build` + +## Troubleshooting + +If you encounter any issues during development or testing, please check the following: + +1. Ensure you're using the correct Node.js version (18.12.0 or higher) and npm version (8.19.0 or higher). +2. Clear the `node_modules` directory and reinstall dependencies if you encounter unexpected behavior. +3. For Docker-related issues, make sure Docker is running and you have sufficient permissions. + +If problems persist, please open an issue on the GitHub repository. \ No newline at end of file From 0b477f911bfdfce9725a9fdb81f7920793374e43 Mon Sep 17 00:00:00 2001 From: utnim2 Date: Wed, 28 Aug 2024 15:20:04 +0530 Subject: [PATCH 2/5] mentioned about this guide in readme and fixed some typo --- Development.md | 16 ++++++++-------- README.md | 2 ++ 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/Development.md b/Development.md index 656111e7a..c0acad8bd 100644 --- a/Development.md +++ b/Development.md @@ -1,8 +1,8 @@ -# Development Guide +# Development guide This guide will help you set up the `generator` locally, run tests, and use Docker for isolated testing. -## Getting Started +## Getting started 1. Clone the repository: @@ -17,9 +17,9 @@ cd generator npm install ``` -## Running Tests +## Running tests -### Local Testing +### Local testing To run all tests locally: @@ -27,7 +27,7 @@ To run all tests locally: - Integration tests: `npm run generator:test:integration` - CLI tests: `npm run generator:test:cli` -### Adding Tests +### Adding tests 1. Create new test files in the appropriate directory under `test/`: @@ -35,7 +35,7 @@ To run all tests locally: 3. Run your new tests using the commands mentioned above. -## Docker Isolated Testing +## Docker isolated testing To run tests in an isolated Docker environment: @@ -52,7 +52,7 @@ npm test " ``` -This command does the following: +This command above does the following: - Mounts the current directory to `/app` in the container - Copies the project to a temporary directory - Installs dependencies @@ -60,7 +60,7 @@ This command does the following: Note: This approach ensures a clean environment for each test run by removing any existing `node_modules`. -## Additional Commands +## Additional commands - Lint the code: `npm run lint` - Generate documentation: `npm run docs` diff --git a/README.md b/README.md index 74d2c5056..3e899b40e 100644 --- a/README.md +++ b/README.md @@ -153,6 +153,8 @@ feat: add new feature ## Contributing +For developement setup you can follow the detailed guide in [Developement guide](Development.md) + Read [CONTRIBUTING](CONTRIBUTING.md) guide. ## Contributors ✨ From a778bba487a44a0e4a6b6a99d1f6e2d2ac574fcc Mon Sep 17 00:00:00 2001 From: utnim2 Date: Mon, 16 Sep 2024 13:51:19 +0530 Subject: [PATCH 3/5] added how to manually test generator with the inbuilt templates --- Development.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/Development.md b/Development.md index c0acad8bd..01b1cd366 100644 --- a/Development.md +++ b/Development.md @@ -4,13 +4,17 @@ This guide will help you set up the `generator` locally, run tests, and use Dock ## Getting started -1. Clone the repository: +1. Fork & Clone the repository: + +First fork the repository from github and then clone it, ```bash git clone https://github.com/asyncapi/generator.git cd generator ``` +After cloning the repository, you should setup the fork properly and configure the `remote` repository as described [here](https://github.com/asyncapi/community/blob/master/git-workflow.md) + 2. Install dependencies: ```bash @@ -29,7 +33,7 @@ To run all tests locally: ### Adding tests -1. Create new test files in the appropriate directory under `test/`: +1. Create new test files in the appropriate directory under `generator/apps/test/`: 2. Follow the existing test patterns. @@ -60,6 +64,25 @@ This command above does the following: Note: This approach ensures a clean environment for each test run by removing any existing `node_modules`. +### Manually testing with test templates + +To test template features manually we have `react-template` and `nunjucks-template` in `apps/generator/test/templates`, you can use this templates to manually test your changes like this: + +1. Navigate to the generator directory: + +```bash +cd apps/generator +``` +2.Modify the react-template in `./test/test-templates/react-template` to test different features. + +3. Run the generator with the react-template: + +```bash +asyncapi generate fromTemplate ./test/docs/dummy.yml ./test/test-templates/react-template -o ./test/output --force-write +``` + +4. Check the output in the `./test/output` directory to verify the output that you desired. + ## Additional commands - Lint the code: `npm run lint` From 75b94e891b03319aaa383540326c204639850241 Mon Sep 17 00:00:00 2001 From: utnim2 Date: Wed, 18 Sep 2024 13:33:06 +0530 Subject: [PATCH 4/5] added the release flow --- Development.md | 60 ++++++++++++++++++- README.md | 57 +----------------- .../react-template/package.json | 2 +- 3 files changed, 60 insertions(+), 59 deletions(-) diff --git a/Development.md b/Development.md index 01b1cd366..362581490 100644 --- a/Development.md +++ b/Development.md @@ -9,7 +9,7 @@ This guide will help you set up the `generator` locally, run tests, and use Dock First fork the repository from github and then clone it, ```bash -git clone https://github.com/asyncapi/generator.git +git clone https://github.com/{your_username}/generator.git cd generator ``` @@ -33,7 +33,7 @@ To run all tests locally: ### Adding tests -1. Create new test files in the appropriate directory under `generator/apps/test/`: +1. Create new test files in the appropriate directory under `apps/generator/test/`: 2. Follow the existing test patterns. @@ -73,7 +73,7 @@ To test template features manually we have `react-template` and `nunjucks-templa ```bash cd apps/generator ``` -2.Modify the react-template in `./test/test-templates/react-template` to test different features. +2. Modify the react-template in `./test/test-templates/react-template` to test different features. 3. Run the generator with the react-template: @@ -83,6 +83,60 @@ asyncapi generate fromTemplate ./test/docs/dummy.yml ./test/test-templates/reac 4. Check the output in the `./test/output` directory to verify the output that you desired. +## Release process + +To release a major/minor/patch: + +### Conventional Commits: + +To maintain a clear git history of commits and easily identify what each commit changed and whether it triggered a release, we use conventional commits. The feat and fix prefixes are particularly important as they are needed to trigger changesets. Using these prefixes ensures that the changes are correctly categorized and the versioning system functions as expected. + +For Example: +``` +feat: add new feature +``` + +#### Manual + +1. Create a new release markdown file in the `.changeset` directory. The filename should indicate what the change is about. + +2. Add the following content to the file in this particular format: + + ```markdown + --- + "@package-name-1": [type] (major/minor/patch) + "@package-name-2": [type] + --- + + [Provide a brief description of the changes. For example: Added a new Release GitHub Flow to the Turborepo. No new features or bugfixes were introduced.] + ``` + + For Example: + + ```markdown + --- + "@asyncapi/generator": minor + --- + + Adding new Release Github Flow to the Turborepo. No new features or bugfixes were introduced. + + ``` + +3. Include the file in your pull request. + +#### Using CLI + +1. Create a new release markdown file using changeset CLI. Below command will trigger an interactive prompt that you can use to specify release type and affected packages. + ```cli + npx -p @changesets/cli@2.27.7 changeset + ``` + +2. Include the file in your pull request. + +> [!TIP] +> For more detailed instructions, you can refer to the official documentation for creating a changeset: +[Adding a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) + ## Additional commands - Lint the code: `npm run lint` diff --git a/README.md b/README.md index f763b774e..451285201 100644 --- a/README.md +++ b/README.md @@ -62,61 +62,6 @@ This library consists of: - Custom filters. Check out [API docs](apps/nunjucks-filters/docs/api.md) for complete list - Lodash-powered filters. For the list of all available filters check [official docs](https://lodash.com/docs/) -## Release Process - -To release a major/minor/patch: - -### Conventional Commits: - -To maintain a clear git history of commits and easily identify what each commit changed and whether it triggered a release, we use conventional commits. The feat and fix prefixes are particularly important as they are needed to trigger changesets. Using these prefixes ensures that the changes are correctly categorized and the versioning system functions as expected. - -For Example: -``` -feat: add new feature -``` - -#### Manual - -1. Create a new release markdown file in the `.changeset` directory. The filename should indicate what the change is about. - -2. Add the following content to the file in this particular format: - - ```markdown - --- - "@package-name-1": [type] (major/minor/patch) - "@package-name-2": [type] - --- - - [Provide a brief description of the changes. For example: Added a new Release GitHub Flow to the Turborepo. No new features or bugfixes were introduced.] - ``` - - For Example: - - ```markdown - --- - "@asyncapi/generator": minor - --- - - Adding new Release Github Flow to the Turborepo. No new features or bugfixes were introduced. - - ``` - -3. Include the file in your pull request. - -#### Using CLI - -1. Create a new release markdown file using changeset CLI. Below command will trigger an interactive prompt that you can use to specify release type and affected packages. - ```cli - npx -p @changesets/cli@2.27.7 changeset - ``` - -2. Include the file in your pull request. - -> [!TIP] -> For more detailed instructions, you can refer to the official documentation for creating a changeset: -[Adding a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) - - ### Release Flow: @@ -151,6 +96,8 @@ feat: add new feature - After the PR is merged, the CI/CD pipeline triggers again. The `changesets/action` step identifies that the PR was created by itself. It then verifies if the current version of the package is greater than the previously released version. If a difference is detected, it executes the publish command to release the updated package. + To know more about release process you can read[](Development.md#Release-Process) + ## Contributing For developement setup you can follow the detailed guide in [Developement guide](Development.md) diff --git a/apps/generator/test/test-templates/react-template/package.json b/apps/generator/test/test-templates/react-template/package.json index 5f430552e..ee383f64b 100644 --- a/apps/generator/test/test-templates/react-template/package.json +++ b/apps/generator/test/test-templates/react-template/package.json @@ -7,7 +7,7 @@ }, "generator": { "renderer": "react", - "api": "v3", + "apiVersion": "v3", "parameters": { "version": { "description": "Custom version to be used" From e4290897a27a6cf50e50070d02e5f57a9f3c6a5a Mon Sep 17 00:00:00 2001 From: utnim2 Date: Wed, 18 Sep 2024 16:15:10 +0530 Subject: [PATCH 5/5] added release flow --- Development.md | 33 +++++++++++++++++++++++++++++++++ README.md | 36 ------------------------------------ 2 files changed, 33 insertions(+), 36 deletions(-) diff --git a/Development.md b/Development.md index 362581490..f62d50476 100644 --- a/Development.md +++ b/Development.md @@ -137,6 +137,39 @@ feat: add new feature > For more detailed instructions, you can refer to the official documentation for creating a changeset: [Adding a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) +### Release Flow: + +1. **Add a Changeset**: + - When you make changes that need to be released, create a markdown file in the `.changeset` directory stating the package name and level of change (major/minor/patch). + +2. **Open a Pull Request**: + - Push your changes and open a Pull Request (PR). After the PR is merged the changeset file helps communicate the type of changes (major, minor, patch). + +3. **CI Processes Changeset**: + - After PR is merged, a dedicated GitHub Actions release workflow runs using changeset action, + + - This action reads the markdown files in the `.changeset` folder and creates a PR with the updated version of the package and removes the markdown file. For example: + + Before: + ```json + "name": "@asyncapi/generator", + "version": "2.0.1", + ``` + + After: + ```json + "name": "@asyncapi/generator", + "version": "3.0.1", + ``` + + - The new PR will also contain the description from the markdown files, + + - AsyncAPI bot automatically merge such release PR. + +4. **Release the Package**: + + - After the PR is merged, the CI/CD pipeline triggers again. The `changesets/action` step identifies that the PR was created by itself. It then verifies if the current version of the package is greater than the previously released version. If a difference is detected, it executes the publish command to release the updated package. + ## Additional commands - Lint the code: `npm run lint` diff --git a/README.md b/README.md index 451285201..5fe3c6018 100644 --- a/README.md +++ b/README.md @@ -62,42 +62,6 @@ This library consists of: - Custom filters. Check out [API docs](apps/nunjucks-filters/docs/api.md) for complete list - Lodash-powered filters. For the list of all available filters check [official docs](https://lodash.com/docs/) - -### Release Flow: - -1. **Add a Changeset**: - - When you make changes that need to be released, create a markdown file in the `.changeset` directory stating the package name and level of change (major/minor/patch). - -2. **Open a Pull Request**: - - Push your changes and open a Pull Request (PR). After the PR is merged the changeset file helps communicate the type of changes (major, minor, patch). - -3. **CI Processes Changeset**: - - After PR is merged, a dedicated GitHub Actions release workflow runs using changeset action, - - - This action reads the markdown files in the `.changeset` folder and creates a PR with the updated version of the package and removes the markdown file. For example: - - Before: - ```json - "name": "@asyncapi/generator", - "version": "2.0.1", - ``` - - After: - ```json - "name": "@asyncapi/generator", - "version": "3.0.1", - ``` - - - The new PR will also contain the description from the markdown files, - - - AsyncAPI bot automatically merge such release PR. - -4. **Release the Package**: - - - After the PR is merged, the CI/CD pipeline triggers again. The `changesets/action` step identifies that the PR was created by itself. It then verifies if the current version of the package is greater than the previously released version. If a difference is detected, it executes the publish command to release the updated package. - - To know more about release process you can read[](Development.md#Release-Process) - ## Contributing For developement setup you can follow the detailed guide in [Developement guide](Development.md)