Merge pull request #13 from IsmaelMartinez/fix-update-dependencies

Fix update dependencies and improve documentation
IsmaelMartinez · Oct 25, 2024 · 889fd85 · 889fd85
2 parents 275ed81 + 8200e86
commit 889fd85
Show file tree

Hide file tree

Showing 5 changed files with 481 additions and 646 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -5,7 +5,7 @@
 
 version: 2
 updates:
-  - package-ecosystem: "pnpm" # See documentation for possible values
-    directory: "/" # Location of package manifests
+  - package-ecosystem: 'pnpm' # See documentation for possible values
+    directory: '/' # Location of package manifests
     schedule:
-      interval: "weekly"
+      interval: 'weekly'
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,56 +5,61 @@ We welcome contributions to this project.
 ## Getting started
 
 1. Fork the repository
+
+   Look at the [fork a repo](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) github documentation to learn how to fork a repository.
+
 1. Clone the repository
 
-```sh
-git clone [email protected]:ismaelmartinez/generator-compass-event-catalog.git
-```
+   Once forked, clone the repository to your machine.
+
+   ```sh
+   git clone [email protected]:ismaelmartinez/generator-compass-event-catalog.git
+   ```
 
 1. Install the dependencies
 
-```sh
-pnpm install
-```
+   The project uses [pnpm](https://pnpm.io/) as the package manager.
 
-1. Run your tests
+   ```sh
+   pnpm install
+   ```
+
+## Developing
+
+It uses [vitest](https://vitest.dev/) for testing.
 
 ```sh
 pnpm test
 ```
 
-1. Link the project
-
-Link the project so it can be used in your EventCatalog
+You can link the project to your EventCatalog to test your generator.
 
 ```sh
 npm link
 ```
 
-1. Using the package in your EventCatalog
-
-Navigate to your EventCatalog directory, then link the package.
+After linking, then you can navidate to your EventCatalog directory and link back the package.
 
 ```sh
 npm link @ismaelmartinez/generator-atlassian-compass-event-catalog
 ```
 
-1. Compile and watch your plugin
+Then, in the generator project, you can run the build command to build the project.
 
 ```sh
 pnpm run build
 ```
 
-1. Run the generator
-
-In your EventCatalog directory run:
+Finally, you can run the generator in your EventCatalog project.
 
 ```sh
 npm run generate
 ```
 
 This will run your generator code and interact with your Catalog.
 
-You can now add your custom code to your generator to test against your catalog.
+Now you are ready to start developing your generator.
+
+EventCatalog uses [EventCatalog SDK](https://www.eventcatalog.dev/docs/sdk) to interact with the Catalog.
 
-You can use the [EventCatalog SDK](https://www.eventcatalog.dev/docs/sdk) to get utils to read, write and delete files in your Catalog easier.
+You can also explore the [get started building compass apps](https://developer.atlassian.com/cloud/compass/integrations/get-started-integrating-with-Compass/#get-started-building-compass-apps) to learn more about the Compass API. I haven't explore it yet.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Atlassian Compass EventCatalog Generator
 
-This generator can be used to create services in Event Catalog from an Atlassian Compass file.
+This generator can be used to create services in Event Catalog from an [Atlassian Compass file].
 
 # Getting started
 
@@ -10,61 +10,59 @@ _Make sure you are on the latest version of EventCatalog_.
 
 1. Install the package
 
-```sh
-npm install -g @ismaelmartinez/generator-atlassian-compass-event-catalog
-```
+   ```sh
+   npm install -g @ismaelmartinez/generator-atlassian-compass-event-catalog
+   ```
 
-2. Configure your EventCatalog to use your generator
+1. Configure your EventCatalog to use your generator
 
-Edit your `eventcatalog.config.js` file and add the generator
+   Edit your `eventcatalog.config.js` file and add the generator
 
-```js
-...
-generators: [
-    [
-        "@ismaelmartinez/generator-atlassian-compass-event-catalog",
-        // These are options to give your generator
-        {
-            services: [
-                {
-                    path: ["path/to/your/compass/file"],
-                    version: "1.0.0" //Optional (defaults to 0.0.0)
-                    id: "your-service-id" //Optional (defaults to the `name` in the compass file)
-                }, // Repeat for each service
-            ],
-            compassUrl: "https://your.atlassian.compass.url",
-            domain: { id: 'orders', name: 'Compass', version: '1.0.0' }, //Optional
-            debug: false //Optional
-        }
-        // Repeat for each domain
-    ]
-]
-...
-```
+   ```js
+   ...
+   generators: [
+       [
+           "@ismaelmartinez/generator-atlassian-compass-event-catalog",
+           // These are options to give your generator
+           {
+               services: [
+                   {
+                       path: ["path/to/your/compass/file"],
+                       version: "1.0.0" //Optional (defaults to 0.0.0)
+                       id: "your-service-id" //Optional (defaults to the `name` in the compass file)
+                   }, // Repeat for each service
+               ],
+               compassUrl: "https://your.atlassian.compass.url",
+               domain: { id: 'orders', name: 'Compass', version: '1.0.0' }, //Optional
+               debug: false //Optional
+           }
+           // Repeat for each domain
+       ]
+   ]
+   ...
+   ```
 
-If a domain is provided, the services will be added to it. If the domain does not exist, it will be created.
+   [Example configuration file](examples/eventcatalog.config.js)
 
-Domain support versioning, while services require versioning. As Atlassian Compass doesn't have the concept of versions, services version will default to 0.0.0. If you want to version your services, you can provide a version in the generator configuration.
+   NOTE: If a domain is provided, the services will be added to it. If the domain does not exist, it will be created.
 
-[(See full event catalog example)](examples/eventcatalog.config.js)
+1. Generate your services
 
-3. Run the generate command
+   On your EventCatalog project, run the generate command:
 
-On your EventCatalog project, run the generate command:
+   ```sh
+   npm run generate
+   ```
 
-```sh
-npm run generate
-```
+1. And explore your services in your catalog:
 
-4. See your new domains, services and messages, run
-
-```sh
-npm run dev
-```
+   ```sh
+   npm run dev
+   ```
 
 ## Features
 
-Currently, the generator only supports generating services from an Atlassian Compass file.
+Currently, the generator only supports generating services from an [Atlassian Compass file].
 
 By design, the links with name 'null' are ignored. This is to allow having the links to EventCatalog in the Compass file without having to worry to show the link in the EventCatalog Service page.
 
@@ -79,3 +77,5 @@ See [LICENSE](LICENSE).
 ## Contributing
 
 See the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
+
+[Atlassian Compass file]: https://developer.atlassian.com/cloud/compass/config-as-code/structure-and-contents-of-a-compass-yml-file/
diff --git a/package.json b/package.json
@@ -23,11 +23,11 @@
   "license": "ISC",
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.16.1",
+    "@types/node": "^22.8.0",
     "prettier": "^3.3.3",
-    "tsup": "^8.1.0",
-    "typescript": "^5.5.3",
-    "vitest": "^2.0.2"
+    "tsup": "^8.3.4",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.3"
   },
   "files": [
     "dist",
@@ -37,9 +37,9 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@changesets/cli": "^2.27.8",
-    "@eventcatalog/sdk": "^0.0.12",
-    "chalk": "^4",
+    "@changesets/cli": "^2.27.9",
+    "@eventcatalog/sdk": "^1.1.3",
+    "chalk": "^5.3.0",
     "change-case": "^5.4.4",
     "js-yaml": "^4.1.0"
   }