From 6c8666ce100740bbba8e633a9427c4b1b9069a9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alexandre=20An=C3=ADcio?=
 <58861037+anicioalexandre@users.noreply.github.com>
Date: Mon, 30 Dec 2024 15:25:50 -0300
Subject: [PATCH] BA-1986: improve docs (#163)

---
 .../{add-catalogs.js => restore-catalogs.js}  |  0
 README.md                                     | 53 +++++++++++--------
 package.json                                  |  2 +-
 3 files changed, 33 insertions(+), 22 deletions(-)
 rename .scripts/{add-catalogs.js => restore-catalogs.js} (100%)

diff --git a/.scripts/add-catalogs.js b/.scripts/restore-catalogs.js
similarity index 100%
rename from .scripts/add-catalogs.js
rename to .scripts/restore-catalogs.js
diff --git a/README.md b/README.md
index 84b020ca..7776be73 100644
--- a/README.md
+++ b/README.md
@@ -102,14 +102,7 @@ Cataloging reused dependencies also facilitates easier updates and reduces the c
 
 Make sure to keep [`@baseapp-frontend's catalog`](https://github.com/silverlogic/baseapp-frontend/blob/master/pnpm-workspace.yaml) always up to date.
 
-
-## **Using Package Versions from GitHub**
-
-If you need to install a package version that hasn't been published yet, follow the steps below. We use GitHub as the source for unpublished versions.
-
-### **Steps:**
-
-1. **Remove Catalog Entries**:
+### **Remove Catalog Entries**:
 
   Before using a package from GitHub, remove its catalog entry. This is necessary because pnpm doesn't handle catalogs well when using non-published versions. To remove the catalogs for the desired package, run the following command:
 
@@ -121,6 +114,30 @@ If you need to install a package version that hasn't been published yet, follow
   pnpm replace-catalogs
   ```
 
+### **Restore Catalog Entries**:
+
+  To restore the catalog entries to their original state, run the following command:
+
+  ```bash
+  # will restore catalogs for utils and authentication packages
+  pnpm restore-catalogs utils authentication
+
+  # will restore catalogs for all packages
+  pnpm restore-catalogs
+  ```
+
+  This will update all package.json files to include catalog entries again.
+
+## **Using Package Versions from GitHub**
+
+If you need to install a package version that hasn't been published yet, follow the steps below. We use GitHub as the source for unpublished versions.
+
+### **Steps:**
+
+1. **Remove Catalog Entries**:
+
+  Refer to the (Remove Catalog Entries)[https://github.com/silverlogic/baseapp-frontend/blob/master/README.md#remove-catalog-entries] section above to temporarily remove catalogs for the relevant packages.
+
 2. **Commit and Push**:
 
   After making the change, commit and push your code. This makes it easy to undo once the package has been published.
@@ -135,7 +152,7 @@ If you need to install a package version that hasn't been published yet, follow
 
 4. **Update Consumer App**:
 
-  In the consumer app (the app that will use the non-published version), update the package entry to point to the GitHub source. Replace `<commit-hash>` with the actual commit hash you copied:
+  In the consumer app (the app that will use the non-published version), update the package entry to the GitHub source. Replace `<commit-hash>` with the actual commit hash you copied:
 
   ```json
   "@baseapp-frontend/components": "git+https://github.com/silverlogic/baseapp-frontend.git#<commit-hash>&path:packages/components",
@@ -145,25 +162,19 @@ If you need to install a package version that hasn't been published yet, follow
 
   Once you’ve finished testing or using the non-published version, you can restore the catalog entries in one of two ways:
 
-  - Option 1: Revert the Commit
+  - Option 1: Run the `restore-catalogs` script
+
+    Refer to the (Restore Catalog Entries)[https://github.com/silverlogic/baseapp-frontend/blob/master/README.md#restore-catalog-entries] section to reapply catalog entries.
+  
+  - Option 2: Revert the Commit
 
     Revert the commit that removed the catalogs to restore them to their previous state:
 
     ```bash
     git revert <commit-hash>
     ```
-    This will effectively undo the catalog removal and bring back the original entries.
-
-  - Option 2: Run the `add-catalogs` script
-
-    Run the `add-catalogs` script to reapply catalog entries without reverting the commit:
-
-    ```bash
-    pnpm add-catalogs
-    ```
-    This will update all package.json files to include catalog entries again.
 
-After using either option, proceed with committing and merging the changes
+  Both options will effectively undo the catalog removal, restore the original entries, and allow you to proceed with committing and merging the changes.
 
 ## Packages Versioning and Publishing
 
diff --git a/package.json b/package.json
index 38c2595c..488047bc 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,7 @@
     "storybook": "turbo storybook",
     "clean": "turbo clean && git clean -xdf node_modules",
     "format": "prettier --write \"**/*.{ts,tsx,md}\"",
-    "add-catalogs": "node .scripts/add-catalogs.js",
+    "restore-catalogs": "node .scripts/restore-catalogs.js",
     "replace-catalogs": "node .scripts/replace-catalogs.js",
     "prepare": "husky"
   },