From bfa188172edbf0cbd40c8347e2e98e9c0e58d669 Mon Sep 17 00:00:00 2001
From: Robert Jackson <robert.jackson@glean.com>
Date: Sun, 1 Jun 2025 09:29:27 -0400
Subject: [PATCH] docs(restructuring): Update the README for restructuring
 script

This now more closely matches the final shipping version.
---
 .github/scripts/README.md | 88 +++++----------------------------------
 1 file changed, 10 insertions(+), 78 deletions(-)

diff --git a/.github/scripts/README.md b/.github/scripts/README.md
index 9b6bf678..5c47b7fa 100644
--- a/.github/scripts/README.md
+++ b/.github/scripts/README.md
@@ -3,45 +3,31 @@
 This directory contains a script to restructure the glean package from:
 
 ```
-src/glean/          # All implementation files
+src/glean/              # All implementation files
 ```
 
 To:
 
 ```
-src/glean/          # Implicit namespace package (no __init__.py)
+src/glean/              # Implicit namespace package (no __init__.py)
 src/glean/api_client/   # All implementation files moved here
 ```
 
 ## Usage
 
-### Analyze what would change (recommended first step)
-
-```bash
-python scripts/restructure_to_namespace.py --dry-run
-```
-
-This shows you:
-
-- Which files would be moved
-- Which import statements would be updated
-- Current state of the transformation
-
-### Perform the restructuring
-
 ```bash
 python scripts/restructure_to_namespace.py
 ```
 
 This script:
 
-- **Detects Speakeasy regeneration** and automatically handles it
+- Detects Speakeasy regeneration and automatically handles it
 - Creates a backup and moves all files
 - Uses implicit namespace packages (no `__init__.py` needed)
 - Can be run multiple times safely
 - Updates all import statements throughout the codebase
 
-## Smart Speakeasy Integration
+## Speakeasy Integration
 
 The script automatically detects when Speakeasy has regenerated files:
 
@@ -49,74 +35,20 @@ The script automatically detects when Speakeasy has regenerated files:
 2. **After Speakeasy regeneration**: Detects new files in `src/glean/`, removes old `api_client/`, and re-runs the transformation
 3. **Subsequent runs**: Detects already-transformed structure and skips
 
-This means you can safely run the script as part of your build process!
-
-## Examples
-
-```bash
-# First, see what would be changed
-python scripts/restructure_to_namespace.py --dry-run
-
-# If it looks good, perform the restructuring
-python scripts/restructure_to_namespace.py
-
-# Safe to run multiple times - it will detect and handle various states
-python scripts/restructure_to_namespace.py  # Skips if already done
-python scripts/restructure_to_namespace.py  # Auto-detects Speakeasy regeneration
-```
-
 ## What the restructuring does
 
 1. **Creates a backup** of the current `src/glean` directory
 2. **Moves all files** from `src/glean/` to `src/glean/api_client/`
 3. **Creates an implicit namespace package** (no `__init__.py` - Python 3.3+ feature)
 4. **Updates all import statements** in tests, examples, and internal files
-5. **Handles Speakeasy regeneration** automatically
-
-## After restructuring
-
-Users will need to update their imports:
-
-### Before
-
-```python
-from glean import Glean, models, errors
-from glean.utils import parse_datetime
-```
-
-### After
-
-```python
-from glean.api_client import Glean, models, errors
-from glean.api_client.utils import parse_datetime
-```
 
 ## Workflow Integration
 
-You can integrate this into your build process:
-
-```bash
-# In your build script or CI
-speakeasy generate  # Regenerates files to src/glean/
-python scripts/restructure_to_namespace.py  # Automatically detects and re-transforms
-```
-
-## Recovery
+The repository includes a GitHub Actions workflow (`.github/workflows/patch-speakeasy-pr.yml`) that automatically runs the restructuring script.
 
-If something goes wrong, the script provides the path to the backup directory:
-
-```bash
-rm -rf src/glean
-cp -r /path/to/backup/glean src/glean
-```
-
-## Testing after restructuring
-
-```bash
-# Run tests
-python -m pytest
-
-# Try importing
-python -c "from glean.api_client import Glean; print('Success!')"
-```
+- **Triggers**: Runs on PRs with "Update SDK - Generate" in the title (Speakeasy PRs) or manual dispatch
+- **Process**: Automatically runs the restructuring script when Speakeasy regenerates the SDK
+- **Auto-commit**: Commits and pushes the restructured files back to the same PR branch
 
+This means Speakeasy PRs are automatically transformed to the namespace
+structure without manual intervention.