From 601f325fb93f57b8ba0c303c1156e921b5ad3761 Mon Sep 17 00:00:00 2001
From: Zahary Karadjov <zahary@gmail.com>
Date: Mon, 4 Jul 2022 15:29:17 +0300
Subject: [PATCH] Update the README to cover the vendor folder interop scripts

---
 README.md                                     | 36 +++++++++++++++++++
 ...ll-vendor-dirs => add-all-vendor-projects} |  0
 scripts/sync-vendor-revisions-to-workspace    |  2 +-
 scripts/sync-workspace-revisions-to-vendor    |  3 +-
 4 files changed, 39 insertions(+), 2 deletions(-)
 rename scripts/{develop-all-vendor-dirs => add-all-vendor-projects} (100%)

diff --git a/README.md b/README.md
index f5f00f9..7a2c7d6 100644
--- a/README.md
+++ b/README.md
@@ -26,3 +26,39 @@ be installed in the Nimble cache.
 Projects can be removed from the workspace by just deleting the respective
 directory. This will result in Nimble installing the project's package in
 the global cache during the next `nimble build`.
+
+### `add-all-vendor-projects`
+
+This script must be executed within a repository using a `vendor` forder. It
+will try to add all vendored submodules as folders in the workspace.
+
+### `sync-vendor-revisions-to-workspace`
+
+This script must be executed within a repository using a `vendor` folder. It
+will copy the current revisions of submodules in the vendor folder to the
+matching folder in the workspace if present. Typically, the scrupt is executed
+after pulling git revisions that bump vendor sumbodules without also bumping
+the same packages in the Nimble lock file. To resolve the discrepancy, the
+developer would execute the following commands:
+
+```bash
+# Pull the project files as usual
+cd top-level-project
+git pull
+make update # or git submodule update --init --recursive
+
+# Fix the lock file
+sync-vendor-revisions-to-workspace
+nimble lock
+git add nimble.lock
+git commit -m "Update the lock file"
+git push
+```
+
+### `sync-workspace-revisions-to-vendor`
+
+This script must be executed within a repository using a `vendor` folder. It
+will copy the revisions from the current workspace folders to the matching
+submodules in the vendor folder. When you use a workspace and make changes
+to the lockfile (by changing any of the dependencies) you must execute this
+script before commiting to reflect the same change in the vendor folder.
diff --git a/scripts/develop-all-vendor-dirs b/scripts/add-all-vendor-projects
similarity index 100%
rename from scripts/develop-all-vendor-dirs
rename to scripts/add-all-vendor-projects
diff --git a/scripts/sync-vendor-revisions-to-workspace b/scripts/sync-vendor-revisions-to-workspace
index 3dd89c8..2cd18dd 100755
--- a/scripts/sync-vendor-revisions-to-workspace
+++ b/scripts/sync-vendor-revisions-to-workspace
@@ -17,6 +17,6 @@ source ../scripts/lib/git-helpers
 for submodule in vendor/*/; do
   WORKSPACE_DIR="../$(basename "$submodule")"
   if [ -d "$WORKSPACE_DIR" ]; then
-    copy_revision "$WORKSPACE_DIR" "$submodule"
+    copy_revision "$submodule" "$WORKSPACE_DIR"
   fi
 done
diff --git a/scripts/sync-workspace-revisions-to-vendor b/scripts/sync-workspace-revisions-to-vendor
index 2cd18dd..812efef 100755
--- a/scripts/sync-workspace-revisions-to-vendor
+++ b/scripts/sync-workspace-revisions-to-vendor
@@ -17,6 +17,7 @@ source ../scripts/lib/git-helpers
 for submodule in vendor/*/; do
   WORKSPACE_DIR="../$(basename "$submodule")"
   if [ -d "$WORKSPACE_DIR" ]; then
-    copy_revision "$submodule" "$WORKSPACE_DIR"
+    copy_revision "$WORKSPACE_DIR" "$submodule"
+    git add "vendor/$submodule"
   fi
 done