[PyPI examples] Manage Drake version consistently

.github/dependabot.yml

@@ -5,3 +5,9 @@ updates:
     directory: /
     schedule:
       interval: weekly
+  - package-ecosystem: pip
+    directories:
+      - /drake_pip
+      - /drake_poetry
+    schedule:
+      interval: weekly

.github/workflows/pip.yml

@@ -9,6 +9,8 @@ jobs:
   macos_sonoma_arm_pip:
     name: macos sonoma 14 arm
     runs-on: macos-14
+    env:
+      PYTHON_VERSION: '3.12'
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -26,10 +28,10 @@ jobs:
       - name: python setup
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: venv setup and install
         working-directory: drake_pip
-        run: setup/setup_env 3.12
+        run: setup/setup_env $PYTHON_VERSION
         shell: zsh -eufo pipefail {0}
       - name: pip build and test
         working-directory: drake_pip

.github/workflows/poetry.yml

@@ -9,6 +9,8 @@ jobs:
   macos_sonoma_arm_poetry:
     name: macos sonoma 14 arm
     runs-on: macos-14
+    env:
+      PYTHON_VERSION: '3.12'
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -26,12 +28,12 @@ jobs:
       - name: python setup
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: poetry setup
         working-directory: drake_poetry
         run: |
           .github/setup
-          setup/install_prereqs 3.12
+          setup/install_prereqs $PYTHON_VERSION
         shell: zsh -efuo pipefail {0}
       - name: poetry test
         working-directory: drake_poetry

drake_pip/.github/workflows/ci.yml

@@ -21,6 +21,8 @@ jobs:
   macos_sonoma_arm_pip:
     name: macos sonoma 14 arm
     runs-on: macos-14
+    env:
+      PYTHON_VERSION: '3.12'
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -38,10 +40,10 @@ jobs:
       - name: python setup
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: venv setup and install
         working-directory: drake_pip
-        run: setup/setup_env 3.12
+        run: setup/setup_env $PYTHON_VERSION
         shell: zsh -eufo pipefail {0}
       - name: pip build and test
         working-directory: drake_pip

drake_pip/README.md

@@ -19,7 +19,8 @@ If on Ubuntu, first install the required packages:
 setup/install_prereqs
 ```
 
-This script will also run `setup/setup_env`, which creates the virtual environment for this project and installs Drake.
+This script will also run `setup/setup_env`,
+which creates the virtual environment for this project and installs Drake.
 
 To start programming, simply activate the environment by calling:
 
@@ -33,7 +34,8 @@ If on Mac OS X, simply ensure the correct version of Python
 is installed from Homebrew by referring to the
 [Supported Configurations](https://drake.mit.edu/installation.html#supported-configurations).
 
-Then, run the following script to create the virtual environment for this project and install Drake:
+Then, run the following script to create the virtual environment
+for this project and install Drake:
 
 ```bash
 setup/setup_env

drake_pip/requirements.txt

@@ -1,3 +1,7 @@
-# Currently, this only includes the most recent version of drake.
-# Feel free to add more packages for your own project!
-drake
+# Currently, this only includes a recent version of Drake.
+# Feel free to add more packages for your own project below!
+# Note: When specifying a compatible version of Drake with ~=,
+# use 'drake~=x.y' instead of 'drake~=x.y.z'. See
+# https://packaging.python.org/en/latest/specifications/version-specifiers/#compatible-release
+# for more details.
+drake~=1.38

drake_poetry/.github/workflows/ci.yml

@@ -21,6 +21,8 @@ jobs:
   macos_sonoma_arm_poetry:
     name: macos sonoma 14 arm
     runs-on: macos-14
+    env:
+      PYTHON_VERSION: '3.12'
     steps:
       - name: checkout
         uses: actions/checkout@v4
@@ -38,12 +40,12 @@ jobs:
       - name: python setup
         uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: poetry setup
         working-directory: drake_poetry
         run: |
           .github/setup
-          setup/install_prereqs 3.12
+          setup/install_prereqs $PYTHON_VERSION
         shell: zsh -efuo pipefail {0}
       - name: poetry test
         working-directory: drake_poetry

drake_poetry/README.md

@@ -1,24 +1,26 @@
 # Python Project with Drake Installed from Poetry
 
 This installs Drake using [`poetry`](https://python-poetry.org/),
-the Python package manager.
-
-For an introduction to `poetry`,
+the Python package manager. For an introduction to `poetry`,
 see [Basic usage](https://python-poetry.org/docs/basic-usage/).
 
 # Instructions
 
 The `pyproject.toml` file found in this directory contains all
-that is needed to start a Poetry project using the most recent
-version of Drake.
+that is needed to start a Poetry project using Drake.
 
 First, follow the [Installation Instructions](https://python-poetry.org/docs/#installation)
 to install Poetry using your preferred method.
 
 Run the installation script to perform the following:
 
 * install the required system packages for Drake (Ubuntu only)
-* set up your Poetry environment and install the most recent version of Drake
+* set up your Poetry environment and install Drake
+  - The `poetry.lock` file listing all dependencies and their versions is not
+    included with this example in order to reduce confusion and keep the version
+    of Drake up to date. It will be created once the environment is set up,
+    and it is encouraged to include this file in your own project's version
+    control in order to manage your project's dependencies.
 
 ```bash
 setup/install_prereqs