chore(gapic): update status and conductor files

Author: chalmerlowe

.conductor/prompt.md

@@ -0,0 +1,37 @@
+# Project Context: Python Version Upgrade for Handwritten Libraries
+
+## Mission Statement
+To update handwritten client libraries in the `google-cloud-python` monorepo to drop support for older Python versions and align with current support policies.
+
+## Core Workflow
+Before doing any work, you MUST read the workflow file:
+1. Read `.conductor/workflow.md` for the step-by-step process.
+
+## Project Persona
+Adopt the persona of a meticulous Python software developer who:
+- Values clean, maintainable code and clear documentation.
+- Creates small, focused commits with descriptive messages following Conventional Commits.
+- Thoroughly verifies changes before pushing.
+
+## Technical Context
+- **Stack:** Python 3
+- **Tools:** `version_scanner.py` (custom script for finding version references).
+
+## Guidelines
+- **Commit Style:** Conventional Commits (`feat(scope): ...`, `chore(scope): ...`).
+- **Candor:** Prioritize correctness over flattery. Suggest improvements if found.
+- **Scope of Review:** Remember to check for both package-level and repo-wide references (like in `ci/` and `.github/`) when reviewin' scan results.
+
+## Handling Version References in Comments
+When running the version scanner, you will find references to old versions (e.g., 3.7) in comments. Follow these three principles to handle them:
+1. **Principle of Ubiquity (Remove):** If a comment references a version older than our minimum supported version and the feature is now standard, remove the reference or the comment.
+2. **Principle of Tracked Debt (TODO + Issue):** If the reference points to a potential improvement (tech debt), remove the version reference and replace it with a tracked TODO referencing an issue number (e.g., `# TODO: See Issue #XYZ to use feature...`).
+3. **Principle of Explicit Exception (Ignore Pragma):** If you MUST keep the version reference for critical technical context, keep the comment and add `# version-scanner: ignore` at the end of the line.
+
+## Lessons Learned (from proto-plus PR)
+- **Leapfrogging:** It is feasible to jump multiple versions (e.g., 3.7 to 3.10) in one go for packages with few references, saving time and reducing PR count.
+- **Ambiguous Refs:** Use full refs like `refs/remotes/origin/main` when branching off remote main to avoid ambiguity if local branches with similar names exist.
+- **Worktree Cleanliness:** New worktrees might inherit modifications if the base branch has uncommitted changes in the index. Use `git stash` to clean them up before switching branches.
+- **GitHub CLI Limitations:** `gh pr edit` may fail due to GraphQL warnings (e.g., Projects classic deprecation). Always be ready to provide the PR description for manual copy-paste as a fallback.
+- **PR Descriptions:** Use `gh pr create --body-file` with a temporary file to avoid shell escaping issues with newlines (`\n`).
+- **Tech Debt Hygiene:** Prefer tracked TODOs with issue numbers over vague comments about version features to avoid false positives in the scanner.

.conductor/status.md

@@ -0,0 +1,50 @@
+# Status: Python Version Upgrade for Handwritten Libraries
+
+**Current State:** Prepped PRs for 3 packages to leapfrog to Python 3.10.
+
+## Completed Packages
+
+### 1. proto-plus
+- **Status:** PR Created
+- **PR:** #16912
+- **Branch:** `chore/update-python-version-proto-plus`
+- **Changes:**
+    - Dropped Python 3.7, 3.8, 3.9 support.
+    - Required Python >= 3.10 in `pyproject.toml`.
+    - Updated `noxfile.py` matrix.
+    - Refactored `repeated.py` to use walrus operator.
+    - Tracked tech debt in Issue #16911 for `_ignore_` usage.
+
+### 2. sqlalchemy-spanner
+- **Status:** PR Created
+- **PR:** #16913
+- **Branch:** `chore/update-python-version-sqlalchemy-spanner`
+- **Changes:**
+    - Dropped Python 3.7, 3.8, 3.9 support.
+    - Required Python >= 3.10 in `setup.py`.
+    - Updated `noxfile.py` matrix and removed dead code.
+
+### 3. django-google-spanner
+- **Status:** PR Created
+- **PR:** #16914
+- **Branch:** `chore/update-python-version-django-google-spanner`
+- **Changes:**
+    - Dropped Python 3.7, 3.8, 3.9 support.
+    - Required Python >= 3.10 in `setup.py`.
+    - Updated `noxfile.py` matrix and removed dead code.
+
+### 4. gapic-generator
+- **Status:** PR Updated (#16910)
+- **Branch:** `feat/gapic-version-fixes`
+- **Changes:**
+    - Leapfrogged to Python 3.10.
+    - Updated `setup.py`, `noxfile.py`, and templates.
+    - Refactored `wrappers.py` to use `@functools.cache`.
+    - Removed stale 3.9 constraints templates.
+    - Added ignore pragmas for false positives (and updated scanner to support `ignore-next-line`).
+    - Verified clean scan (except root workflows and Pandoc).
+
+## Next Steps
+- [ ] Wait for feedback on how to handle generated code entanglement in `gapic-generator`.
+- [ ] Review and merge PRs #16910, #16912, #16913, #16914.
+- [ ] Continue with other packages in the small packages list if approved.

.conductor/workflow.md

@@ -0,0 +1,41 @@
+# Workflow: Updating Packages for Python Version Upgrades
+
+This workflow outlines the steps to take a package or set of packages and update them against a new runtime version (e.g., dropping 3.7 or upgrading to a new min version).
+
+## Steps
+
+1.  **Branching and Worktree:**
+    *   Create a new branch for the updates (e.g., `chore/update-python-<version>-<pkg>`).
+    *   Use the dedicated worktree (`chore-update-handwritten`) for these updates. You do not need a new worktree for every package.
+    *   Keep the scanner branch (`feat/add-version-scanner`) open in the `main` worktree for tool fixes.
+    *   Ensure the branch is up to date with the latest `main` from GitHub (`git fetch origin` and `git merge origin/main`).
+
+2.  **Scanning:**
+    *   Run the `version_scanner.py` script to identify references to the version being updated or dropped.
+    *   Example command:
+        ```bash
+        python3 scripts/version_scanner/version_scanner.py -d python -v <version> --package <package-name> -p <worktree-path>
+        ```
+    *   Use `--package-file` if targeting multiple packages.
+
+3.  **Analysis:**
+    *   Review the scan results (CSV file or Google Sheet).
+    *   Filter out false positives (e.g., version numbers in package names or unrelated strings like `pandoc-3.7`).
+    *   Identify actual references that need updates.
+    *   **[IMPORTANT] Check for Root-Level Matches:** When reviewin' scan results, always look for matches labeled as `[Root/None]` in the package summary. These often represent shared CI scripts (`ci/`) or GitHub workflows (`.github/`) that may need updates to align with the new Python version requirements of the package being processed.
+
+4.  **Implementation:**
+    *   **Documentation:** Update references to minimum supported versions in `README.rst`, `docs/index.rst`, etc.
+    *   **Configuration:** Update `setup.py`, `pyproject.toml`, `mypy.ini`, etc.
+    *   **CI Scripts:** Update matrix or checks in `ci/run_single_test.sh`, `ci/run_conditional_tests.sh`, or `noxfile.py`.
+    *   **Post-Processing:** Update or remove dead code in `.librarian` YAML files if applicable.
+    *   **Comments:** Apply the principles in `prompt.md` when handling version references in comments (Ubiquity, Tracked Debt, Explicit Exception).
+
+5.  **Review and Commit:**
+    *   Review edits with the user or team.
+    *   Create **small, tightly focused commits** for each file or logical change.
+    *   Follow Conventional Commits specification.
+
+6.  **Push and PR:**
+    *   Push the branch to GitHub.
+    *   Create a Pull Request.