Skip to content

Commit 9e7f010

Browse files
Florence-NjeriFlorence-Njeri
authored
Merge branch 'master' into cli.js-deprecation
2 parents 6ab60db + 6f60d50 commit 9e7f010

File tree

18 files changed

+267
-153
lines changed

18 files changed

+267
-153
lines changed

‎.all-contributorsrc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,15 @@
196196
"test",
197197
"doc"
198198
]
199+
},
200+
{
201+
"login": "DhairyaMajmudar",
202+
"name": "Dhairya Majmudar",
203+
"avatar_url": "https://avatars.githubusercontent.com/u/124715224?v=4",
204+
"profile": "https://dhaiyra-majmudar.netlify.app/",
205+
"contributions": [
206+
"bug"
207+
]
199208
}
200209
],
201210
"contributorsPerLine": 3,

‎.eslintrc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ extends:
1313
- plugin:sonarjs/recommended
1414

1515
parserOptions:
16-
ecmaVersion: 2018
16+
ecmaVersion: 2020
1717
sourceType: module
1818
ecmaFeatures:
1919
jsx: true

‎.github/workflows/update-docs-in-website.yml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ on:
66
- 'master'
77
paths:
88
- 'apps/generator/docs/*.md'
9+
- '.github/workflows/update-docs-in-website.yml'
910

1011
jobs:
1112
Make-PR:
@@ -39,7 +40,7 @@ jobs:
3940
mkdir -p ./markdown/docs/tools/generator
4041
rm ../generator/apps/generator/docs/README.md
4142
rm -r ../generator/apps/generator/docs/jsdoc2md-handlebars
42-
printf "%s\ntitle: Generator\nweight: 3\n%s" "---" "---"> ../generator/docs/_section.md
43+
printf "%s\ntitle: Generator\nweight: 3\n%s" "---" "---"> ../generator/apps/generator/docs/_section.md
4344
mv ../generator/apps/generator/docs/*.md ./markdown/docs/tools/generator
4445
- name: Commit and push
4546
working-directory: ./website

‎.prettierignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
**

‎Development.md

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Development guide
2+
3+
This guide will help you set up the `generator` locally, run tests, and use Docker for isolated testing.
4+
5+
## Getting started
6+
7+
1. Fork & Clone the repository:
8+
9+
First fork the repository from github and then clone it,
10+
11+
```bash
12+
git clone https://github.com/{your_username}/generator.git
13+
cd generator
14+
```
15+
16+
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)
17+
18+
2. Install dependencies:
19+
20+
```bash
21+
npm install
22+
```
23+
24+
## Running tests
25+
26+
### Local testing
27+
28+
To run all tests locally:
29+
30+
- Unit tests: `npm run generator:test:unit`
31+
- Integration tests: `npm run generator:test:integration`
32+
- CLI tests: `npm run generator:test:cli`
33+
34+
### Adding tests
35+
36+
1. Create new test files in the appropriate directory under `apps/generator/test/`:
37+
38+
2. Follow the existing test patterns.
39+
40+
3. Run your new tests using the commands mentioned above.
41+
42+
## Docker isolated testing
43+
44+
To run tests in an isolated Docker environment:
45+
46+
1. Ensure Docker is installed and running on your machine.
47+
48+
2. Run the following command from the project root:
49+
50+
```bash
51+
docker run --rm -v ${PWD}:/app -w /app node:18 sh -c "
52+
cp -r /app /tmp/app &&
53+
cd /tmp/app &&
54+
npm install &&
55+
npm test
56+
"
57+
```
58+
59+
This command above does the following:
60+
- Mounts the current directory to `/app` in the container
61+
- Copies the project to a temporary directory
62+
- Installs dependencies
63+
- Runs all tests
64+
65+
Note: This approach ensures a clean environment for each test run by removing any existing `node_modules`.
66+
67+
### Manually testing with test templates
68+
69+
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:
70+
71+
1. Navigate to the generator directory:
72+
73+
```bash
74+
cd apps/generator
75+
```
76+
2. Modify the react-template in `./test/test-templates/react-template` to test different features.
77+
78+
3. Run the generator with the react-template:
79+
80+
```bash
81+
asyncapi generate fromTemplate ./test/docs/dummy.yml ./test/test-templates/react-template -o ./test/output --force-write
82+
```
83+
84+
4. Check the output in the `./test/output` directory to verify the output that you desired.
85+
86+
## Release process
87+
88+
To release a major/minor/patch:
89+
90+
### Conventional Commits:
91+
92+
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.
93+
94+
For Example:
95+
```
96+
feat: add new feature
97+
```
98+
99+
#### Manual
100+
101+
1. Create a new release markdown file in the `.changeset` directory. The filename should indicate what the change is about.
102+
103+
2. Add the following content to the file in this particular format:
104+
105+
```markdown
106+
---
107+
"@package-name-1": [type] (major/minor/patch)
108+
"@package-name-2": [type]
109+
---
110+
111+
[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.]
112+
```
113+
114+
For Example:
115+
116+
```markdown
117+
---
118+
"@asyncapi/generator": minor
119+
---
120+
121+
Adding new Release Github Flow to the Turborepo. No new features or bugfixes were introduced.
122+
123+
```
124+
125+
3. Include the file in your pull request.
126+
127+
#### Using CLI
128+
129+
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.
130+
```cli
131+
npx -p @changesets/[email protected] changeset
132+
```
133+
134+
2. Include the file in your pull request.
135+
136+
> [!TIP]
137+
> For more detailed instructions, you can refer to the official documentation for creating a changeset:
138+
[Adding a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md)
139+
140+
### Release Flow:
141+
142+
1. **Add a Changeset**:
143+
- 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).
144+
145+
2. **Open a Pull Request**:
146+
- 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).
147+
148+
3. **CI Processes Changeset**:
149+
- After PR is merged, a dedicated GitHub Actions release workflow runs using changeset action,
150+
151+
- 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:
152+
153+
Before:
154+
```json
155+
"name": "@asyncapi/generator",
156+
"version": "2.0.1",
157+
```
158+
159+
After:
160+
```json
161+
"name": "@asyncapi/generator",
162+
"version": "3.0.1",
163+
```
164+
165+
- The new PR will also contain the description from the markdown files,
166+
167+
- AsyncAPI bot automatically merge such release PR.
168+
169+
4. **Release the Package**:
170+
171+
- 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.
172+
173+
## Additional commands
174+
175+
- Lint the code: `npm run lint`
176+
- Generate documentation: `npm run docs`
177+
- Build Docker image: `npm run docker:build`
178+
179+
## Troubleshooting
180+
181+
If you encounter any issues during development or testing, please check the following:
182+
183+
1. Ensure you're using the correct Node.js version (18.12.0 or higher) and npm version (8.19.0 or higher).
184+
2. Clear the `node_modules` directory and reinstall dependencies if you encounter unexpected behavior.
185+
3. For Docker-related issues, make sure Docker is running and you have sufficient permissions.
186+
187+
If problems persist, please open an issue on the GitHub repository.

‎README.md

Lines changed: 3 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -63,97 +63,10 @@ This library consists of:
6363
- Custom filters. Check out [API docs](apps/nunjucks-filters/docs/api.md) for complete list
6464
- Lodash-powered filters. For the list of all available filters check [official docs](https://lodash.com/docs/)
6565

66-
## Release Process
67-
68-
To release a major/minor/patch:
69-
70-
### Conventional Commits:
71-
72-
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.
73-
74-
For Example:
75-
```
76-
feat: add new feature
77-
```
78-
79-
#### Manual
80-
81-
1. Create a new release markdown file in the `.changeset` directory. The filename should indicate what the change is about.
82-
83-
2. Add the following content to the file in this particular format:
84-
85-
```markdown
86-
---
87-
"@package-name-1": [type] (major/minor/patch)
88-
"@package-name-2": [type]
89-
---
90-
91-
[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.]
92-
```
93-
94-
For Example:
95-
96-
```markdown
97-
---
98-
"@asyncapi/generator": minor
99-
---
100-
101-
Adding new Release Github Flow to the Turborepo. No new features or bugfixes were introduced.
102-
103-
```
104-
105-
3. Include the file in your pull request.
106-
107-
#### Using CLI
108-
109-
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.
110-
```cli
111-
npx -p @changesets/[email protected] changeset
112-
```
113-
114-
2. Include the file in your pull request.
115-
116-
> [!TIP]
117-
> For more detailed instructions, you can refer to the official documentation for creating a changeset:
118-
[Adding a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md)
119-
120-
121-
122-
### Release Flow:
123-
124-
1. **Add a Changeset**:
125-
- 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).
126-
127-
2. **Open a Pull Request**:
128-
- 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).
129-
130-
3. **CI Processes Changeset**:
131-
- After PR is merged, a dedicated GitHub Actions release workflow runs using changeset action,
132-
133-
- 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:
134-
135-
Before:
136-
```json
137-
"name": "@asyncapi/generator",
138-
"version": "2.0.1",
139-
```
140-
141-
After:
142-
```json
143-
"name": "@asyncapi/generator",
144-
"version": "3.0.1",
145-
```
146-
147-
- The new PR will also contain the description from the markdown files,
148-
149-
- AsyncAPI bot automatically merge such release PR.
150-
151-
4. **Release the Package**:
152-
153-
- 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.
154-
15566
## Contributing
15667

68+
For developement setup you can follow the detailed guide in [Developement guide](Development.md)
69+
15770
Read [CONTRIBUTING](CONTRIBUTING.md) guide.
15871

15972
## Contributors ✨
@@ -192,6 +105,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
192105
</tr>
193106
<tr>
194107
<td align="center" valign="top" width="33.33%"><a href="https://github.com/pierrick-boule"><img src="https://avatars.githubusercontent.com/u/3237116?v=4?s=100" width="100px;" alt="pierrick-boule"/><br /><sub><b>pierrick-boule</b></sub></a><br /><a href="https://github.com/asyncapi/generator/commits?author=pierrick-boule" title="Code">💻</a> <a href="https://github.com/asyncapi/generator/commits?author=pierrick-boule" title="Tests">⚠️</a> <a href="https://github.com/asyncapi/generator/commits?author=pierrick-boule" title="Documentation">📖</a></td>
108+
<td align="center" valign="top" width="33.33%"><a href="https://dhaiyra-majmudar.netlify.app/"><img src="https://avatars.githubusercontent.com/u/124715224?v=4?s=100" width="100px;" alt="Dhairya Majmudar"/><br /><sub><b>Dhairya Majmudar</b></sub></a><br /><a href="https://github.com/asyncapi/generator/issues?q=author%3ADhairyaMajmudar" title="Bug reports">🐛</a></td>
195109
</tr>
196110
</tbody>
197111
</table>

‎apps/generator/docs/generator-template.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ To see this in action, navigate to the **python-mqtt-client-template** directory
159159

160160
``` cmd
161161
Generation in progress. Keep calm and wait a bit... done
162-
Check out your shiny new generated files at output.
162+
Check out your shiny new generated files at test/project.
163163
```
164164

165165
Navigating to the **test/project** directory. You should see a **client.py** file; the only content is `Temperature Service`.

‎apps/generator/lib/generator.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -562,8 +562,8 @@ class Generator {
562562

563563
try {
564564
installedPkg = getTemplateDetails(this.templateName, PACKAGE_JSON_FILENAME);
565-
pkgPath = installedPkg && installedPkg.pkgPath;
566-
packageVersion = installedPkg && installedPkg.version;
565+
pkgPath = installedPkg?.pkgPath;
566+
packageVersion = installedPkg?.version;
567567
log.debug(logMessage.templateSource(pkgPath));
568568
if (packageVersion) log.debug(logMessage.templateVersion(packageVersion));
569569

@@ -759,7 +759,7 @@ class Generator {
759759
// Check if the filename dictates it should be separated
760760
let wasSeparated = false;
761761
for (const prop in fileNamesForSeparation) {
762-
if (Object.prototype.hasOwnProperty.call(fileNamesForSeparation, prop) && stats.name.includes(`$$${prop}$$`)) {
762+
if (Object.hasOwn(fileNamesForSeparation, prop) && stats.name.includes(`$$${prop}$$`)) {
763763
await this.generateSeparateFiles(asyncapiDocument, fileNamesForSeparation[prop], prop, stats.name, root);
764764
const templateFilePath = path.relative(this.templateContentDir, path.resolve(root, stats.name));
765765
fs.unlink(path.resolve(this.targetDir, templateFilePath), next);

‎apps/generator/lib/logMessages.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ const TEMPLATE_INSTALL_FLAG_MSG = 'because you passed --install flag';
22

33
const TEMPLATE_INSTALL_DISK_MSG = 'because the template cannot be found on disk';
44

5-
const NODE_MODULES_INSTALL ='Remember that your local template must have its own node_modules installed first, \"npm install\" is not triggered by the generator.';
5+
const NODE_MODULES_INSTALL = 'Remember that your local template must have its own node_modules installed first, "npm install" is not triggered by the generator.';
66

77
const NPM_INSTALL_TRIGGER = 'Installation of template located on disk technically means symlink creation betweed node_modules of the generator and template sources. Your local template must have its own node_modules, "npm install" is not triggered.';
88

@@ -19,7 +19,7 @@ function templateNotFound(templateName) {
1919
}
2020

2121
function packageNotAvailable(packageDetails) {
22-
if (packageDetails && packageDetails.pkgPath) {
22+
if (packageDetails?.pkgPath) {
2323
return `Unable to resolve template location at ${packageDetails.pkgPath}. Package is not available locally.`;
2424
}
2525

‎apps/generator/lib/parser.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ function convertOldOptionsToNew(oldOptions, generator) {
6363
}
6464

6565
const resolvers = [];
66-
if (generator && generator.mapBaseUrlToFolder && generator.mapBaseUrlToFolder.url) {
66+
if (generator?.mapBaseUrlToFolder?.url) {
6767
resolvers.push(...getMapBaseUrlToFolderResolvers(generator.mapBaseUrlToFolder));
6868
}
6969
if (oldOptions.resolve) {

0 commit comments

Comments
 (0)