HelpersTask657_Improve_the_file_linking_flow

docs/tools/dev_system/all.replace_common_files_with_script_links.md

@@ -1,18 +1,15 @@
-
-
 <!-- toc -->
 
 - [Managing Symbolic Links Between Directories](#managing-symbolic-links-between-directories)
-  * [Define](#define)
+  * [Summary](#summary)
   * [Why Do We Need This Approach?](#why-do-we-need-this-approach)
+  * [Nomenclature](#nomenclature)
   * [Workflow and Commands](#workflow-and-commands)
     + [Step 1: Replace Files with Symbolic Links](#step-1-replace-files-with-symbolic-links)
     + [Step 2: Stage Files for Modification](#step-2-stage-files-for-modification)
     + [Step 3: Restore Symbolic Links After Modifications](#step-3-restore-symbolic-links-after-modifications)
     + [Workflow Summary](#workflow-summary)
     + [Example Directory Structure](#example-directory-structure)
-    + [Notes and Best Practices](#notes-and-best-practices)
-    + [Conclusion](#conclusion)
 
 <!-- tocstop -->
 
@@ -21,29 +18,48 @@
 ## Summary
 
 - This document describes two scripts, `create_links.py` and
-  `stage_linked_file.py` used to manage symbolic links between a
-  source directory and a destination directory
+  `stage_linked_file.py` used to manage symbolic links between a source
+  directory and a destination directory
 - These tools simplify workflows where you want to create read-only symbolic
   links for files, stage modifications, and later restore the links
 
 ## Why Do We Need This Approach?
 
-- In our codebases, it is common to have duplicate files or files
-  that are identical between two directories. Maintaining these files manually
-  can lead to inefficiencies and errors:
+- In our codebases, it is common to have files that are identical between two
+  directories. Maintaining these files manually can lead to inefficiencies and
+  errors:
   - Synchronization: If changes are made in one location, they may not reflect
     in the other, leading to inconsistencies
   - Accidental Modifications: Directly modifying files that should remain
     synchronized can result in unintended discrepancies
 
 - With our approach:
   - We avoid file duplication by creating links that point to the original files
-  - Links in the destination directory remain read-only, reducing the risk of
-    accidental changes
+  - Links in the destination directory are marked as read-only, reducing the
+    risk of accidental changes
   - If modifications are needed, the "staging process" ensures you can work
     safely on copies without altering the original source files
-  - After the code has been developed, one can then convert copies of files, back
-    to links
+  - After the code has been developed, one can then convert copies of files,
+    back to links
+
+## Nomenclature
+
+- Links are often confusing since it's not clear what is linked to and what is
+  linked from, e.g.,
+  - `ln -s foo bar` creates a symbolic link named `foo` that points to `bar`
+    ```bash
+    foo -> bar
+    ```
+  - This convention seems the opposite of `cp foo bar` where a new file called
+    `bar` is created with the content of `foo`
+
+- Also referring to "source" and "destination" is confusing since it is unclear
+  if "destination" is the "destination" of the link (i.e., the head of the
+  arrow) or the "destination" of the operation of copy (the tail of the arrow)
+
+- In the rest of this document we will refer to the file being created as
+  "destination"
+  - E.g., `ln -s new_file old_file`
 
 ## Workflow and Commands
 
@@ -55,7 +71,8 @@
   links to the corresponding files in `src_dir`
 
   Command:
-  ```
+
+  ```bash
   > create_links.py --src_dir /path/to/src --dst_dir /path/to/dst --replace_links
   ```
 
@@ -76,16 +93,20 @@
 - If you want to edit the files in `dst_dir` (which are currently symbolic
   links), use `stage_linked_file.py` to stage them. Staging replaces the
   symbolic links with writable copies of the original files
+- At this point, you can just modify the files in `dst_dir` to achieve the
+  desired goal, without worries of altering the source files
+  - Often you don't know which files need to be changed and how to change files
+    so all the files are staged for modification
 
 - Command:
-  ```
+
+  ```bash
   > stage_linked_file.py --dst_dir /path/to/dst
   ```
 
 - What it does:
   - Finds all the symbolic links in `dst_dir`
-  - Replaces each symbolic link with a writable copy of the file it points
-    to
+  - Replaces each symbolic link with a writable copy of the file it points to
   - Sets file permissions to `644` (writable)
 
 - Why it is important:
@@ -95,11 +116,12 @@
 
 ### Step 3: Restore Symbolic Links After Modifications
 
-- Once you’ve finished modifying the files, you can restore the symbolic links
+- Once you've finished modifying the files, you can restore the symbolic links
   by running `create_links.py` again with the `--replace_links` flag
 
 - Command:
-  ```
+
+  ```bash
   > create_links.py --src_dir /path/to/src --dst_dir /path/to/dst --replace_links
   ```
 
@@ -115,22 +137,23 @@
 
 ### Workflow Summary
 
-- Set up `symbolic links`:
-  ```
-  > create_links.py --src_dir /path/to/src --dst_dir /path/to/dst --replace_links
-  ```
+1. Set up symbolic links:
 
-- Stage `symbolic links` for modification:
-  ```
-  > stage_linked_file.py --dst_dir /path/to/dst
-  ```
+   ```bash
+   > create_links.py --src_dir /path/to/src --dst_dir /path/to/dst --replace_links
+   ```
 
-- Modify files as required
+2. Stage symbolic links for modification:
+   ```
+   > stage_linked_file.py --dst_dir /path/to/dst
+   ```
 
-- After modifications, restore the `symbolic links`:
-  ```
-  > create_links.py --src_dir /path/to/src --dst_dir /path/to/dst --replace_links
-  ```
+3. Modify files as required
+
+4. After modifications, restore the symbolic links:
+   ```
+   > create_links.py --src_dir /path/to/src --dst_dir /path/to/dst --replace_links
+   ```
 
 ### Example Directory Structure