feat(sdk): monorepo repository to add new otel plugin package

Author: hsilan

.github/scripts/ci-checks.sh

@@ -1,18 +1,37 @@
-
 #!/bin/sh
 
 set -e
 
-hatch run test:cov
-echo SUCCESS: tests + coverage
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+PACKAGES=(
+  "packages/aws-durable-execution-sdk-python"
+  "packages/aws-durable-execution-sdk-python-otel"
+)
+
+for package_dir in "${PACKAGES[@]}"; do
+  full_path="$REPO_ROOT/$package_dir"
+  if [ -d "$full_path" ]; then
+    echo "=========================================="
+    echo "Running checks for $package_dir"
+    echo "=========================================="
+    cd "$full_path"
+
+    hatch run test:cov
+    echo "SUCCESS: tests + coverage ($package_dir)"
 
-# type checks
-hatch run types:check
-echo SUCCESS: typings
+    # type checks
+    hatch run types:check
+    echo "SUCCESS: typings ($package_dir)"
 
-# static analysis
-hatch fmt
-echo SUCCESS: linting/fmt
+    # static analysis
+    hatch fmt
+    echo "SUCCESS: linting/fmt ($package_dir)"
+  else
+    echo "WARNING: $package_dir does not exist, skipping"
+  fi
+done
 
-# commit message validation
+# commit message validation (run once from repo root)
+cd "$REPO_ROOT"
 hatch run python .github/scripts/lintcommit.py

.github/workflows/ci.yml

@@ -43,10 +43,42 @@ jobs:
       run: |
         python -m pip install hatch==1.16.5
     - name: static analysis
-      run: hatch fmt --check
+      run: |
+        for pkg in packages/*/; do
+          if [ -f "$pkg/pyproject.toml" ]; then
+            echo "=== Checking format: $pkg ==="
+            cd "$pkg"
+            hatch fmt --check
+            cd "$GITHUB_WORKSPACE"
+          fi
+        done
     - name: type checking
-      run: hatch run types:check
+      run: |
+        for pkg in packages/*/; do
+          if [ -f "$pkg/pyproject.toml" ]; then
+            echo "=== Type checking: $pkg ==="
+            cd "$pkg"
+            hatch run types:check
+            cd "$GITHUB_WORKSPACE"
+          fi
+        done
     - name: Run tests + coverage
-      run: hatch run test:cov
+      run: |
+        for pkg in packages/*/; do
+          if [ -f "$pkg/pyproject.toml" ]; then
+            echo "=== Testing: $pkg ==="
+            cd "$pkg"
+            hatch run test:cov
+            cd "$GITHUB_WORKSPACE"
+          fi
+        done
     - name: Build distribution
-      run: hatch build
+      run: |
+        for pkg in packages/*/; do
+          if [ -f "$pkg/pyproject.toml" ]; then
+            echo "=== Building: $pkg ==="
+            cd "$pkg"
+            hatch build
+            cd "$GITHUB_WORKSPACE"
+          fi
+        done

.github/workflows/pypi-publish.yml

@@ -1,4 +1,4 @@
-# This workflow will upload a Python Package to PyPI when a release is created
+# This workflow will upload Python Packages to PyPI when a release is created
 # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
 
 # This workflow uses actions that are not certified by GitHub.
@@ -18,59 +18,66 @@ permissions:
 jobs:
   release-build:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - name: aws-durable-execution-sdk-python
+            path: packages/aws-durable-execution-sdk-python
+          - name: aws-durable-execution-sdk-python-otel
+            path: packages/aws-durable-execution-sdk-python-otel
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.11"
-      - name: Install Hatch 
-        run: |
-          python -m pip install --upgrade hatch==1.16.5
+
+      - name: Install Hatch
+        run: python -m pip install --upgrade hatch==1.16.5
+
       - name: Build release distributions
-        run: |
-          # NOTE: put your own distribution build steps here.
-          hatch build
+        working-directory: ${{ matrix.package.path }}
+        run: hatch build
 
       - name: Upload distributions
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
-          name: release-dists
-          path: dist/
+          name: release-dists-${{ matrix.package.name }}
+          path: ${{ matrix.package.path }}/dist/
 
   pypi-publish:
     runs-on: ubuntu-latest
     needs:
       - release-build
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - name: aws-durable-execution-sdk-python
+          - name: aws-durable-execution-sdk-python-otel
     permissions:
-      # IMPORTANT: this permission is mandatory for trusted publishing
       id-token: write
 
-    # Dedicated environments with protections for publishing are strongly recommended.
-    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
     environment:
       name: pypi
-      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
-      # url: https://pypi.org/p/aws-durable-execution-sdk-python
-      #
-      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
-      # ALTERNATIVE: exactly, uncomment the following line instead:
-      url: https://pypi.org/project/aws-durable-execution-sdk-python/${{ github.event.release.name }}
+      url: https://pypi.org/project/${{ matrix.package.name }}/${{ github.event.release.name }}
 
     steps:
       - name: Retrieve release distributions
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
         with:
-          name: release-dists
+          name: release-dists-${{ matrix.package.name }}
           path: dist/
 
-      - name: Publish release distributions to PyPI
+      - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
         with:
           packages-dir: dist/
 
   notify-release:
+    if: always() && contains(needs.pypi-publish.result, 'success')
     needs: [pypi-publish]
     uses: ./.github/workflows/notify-release.yml
     with:

CONTRIBUTING.md

@@ -9,7 +9,35 @@ information to effectively respond to your bug report or contribution.
 ## Dependencies
 Install [hatch](https://hatch.pypa.io/dev/install/).
 
+## Repository Structure
+
+This is a monorepo containing multiple packages under the `packages/` directory:
+
+```
+packages/
+├── aws-durable-execution-sdk-python/       # Core SDK
+│   ├── pyproject.toml
+│   ├── src/
+│   ├── tests/
+│   └── examples/
+└── aws-durable-execution-sdk-python-otel/  # OpenTelemetry instrumentation
+    ├── pyproject.toml
+    ├── src/
+    └── tests/
+```
+
+Shared files (`.github/`, `LICENSE`, `CONTRIBUTING.md`, etc.) live at the repository root.
+
 ## Developer workflow
+
+All `hatch` commands must be run from within a specific package directory:
+
+```bash
+cd packages/aws-durable-execution-sdk-python
+# or
+cd packages/aws-durable-execution-sdk-python-otel
+```
+
 These are all the checks you would typically do as you prepare a PR:
 ```
 # just test
@@ -25,7 +53,7 @@ hatch run types:check
 hatch fmt
 ```
 
-There is a convenience script for the above that you can run from the root of the repo as you prepare your PR:
+There is a convenience script that runs checks across all packages from the root of the repo:
 ```
 .github/scripts/ci-checks.sh
 ```
@@ -131,7 +159,8 @@ class WaitOptions:
 
 ## Set up your IDE
 Point your IDE at the hatch virtual environment to have it recognize dependencies
-and imports.
+and imports. Run these commands from within the package directory you're working on
+(e.g., `packages/aws-durable-execution-sdk-python`).
 
 You can find the path to the hatch Python interpreter like this:
 ```
@@ -148,6 +177,7 @@ errors finding the interpreter. You can create a local .venv file symlink _witho
 in the path:
 
 ```bash
+# From within the package directory, e.g. packages/aws-durable-execution-sdk-python
 # create a symlink at: ./.venv/bin/python
 rm -rf .venv && ln -s "$(hatch env find)" .venv
 ```
@@ -179,6 +209,8 @@ These `settings.json` settings are useful:
 
 ## Testing
 ### How to run tests
+Run these commands from within a package directory (e.g., `packages/aws-durable-execution-sdk-python`).
+
 To run all tests:
 ```
 hatch test
@@ -220,7 +252,8 @@ tests/mypackage/mymodule_test.py
 
 ## Examples and Deployment
 
-The project includes a unified CLI tool for managing examples, deployment, and AWS account setup:
+The project includes a unified CLI tool for managing examples, deployment, and AWS account setup.
+Run these commands from the core SDK package directory (`packages/aws-durable-execution-sdk-python`):
 
 ### Bootstrap AWS Account
 ```bash

RELEASING.md

@@ -0,0 +1,106 @@
+# Releasing
+
+This document describes how to cut a release for packages in this monorepo and how the automated PyPI publishing workflow is triggered.
+
+## Packages
+
+This monorepo contains the following packages:
+
+| Package | Path | Tag Prefix |
+|---------|------|------------|
+| `aws-durable-execution-sdk-python` | `packages/aws-durable-execution-sdk-python` | `sdk` |
+| `aws-durable-execution-sdk-python-otel` | `packages/aws-durable-execution-sdk-python-otel` | `otel` |
+
+## Versioning
+
+Each package maintains its own version in its respective `__about__.py` file:
+
+- SDK: `packages/aws-durable-execution-sdk-python/src/aws_durable_execution_sdk_python/__about__.py`
+- OTel: `packages/aws-durable-execution-sdk-python-otel/src/aws_durable_execution_sdk_python_otel/__about__.py`
+
+Bump the version in the appropriate `__about__.py` file(s) and merge to `main` before creating a release.
+
+## Cutting a Release
+
+### 1. Bump the version
+
+Update the `__version__` string in the relevant `__about__.py` file(s). Commit and merge to `main`.
+
+### 2. Create a GitHub Release
+
+1. Go to the [Releases page](https://github.com/aws/aws-durable-execution-sdk-python/releases) on GitHub.
+2. Click **Draft a new release**.
+3. Create a new tag following the tagging convention below.
+4. Set the release title (typically the same as the tag).
+5. Write release notes following the format described in [Release Notes Format](#release-notes-format).
+6. Click **Publish release**.
+
+### Tagging Convention
+
+The tag should be the version of the package being bumped, prepended with a descriptive prefix:
+
+- **SDK only:** `sdk-v<version>` (e.g., `sdk-v1.6.0`)
+- **OTel only:** `otel-v<version>` (e.g., `otel-v0.3.0`)
+- **Both packages in a single release:** comma-separate the sub-tags (e.g., `sdk-1.6.0,otel-0.3.0`)
+
+Examples:
+
+```
+sdk-1.6.0
+otel-0.3.0
+sdk-1.6.0,otel-0.3.0
+```
+
+If additional packages are added to the monorepo in the future, follow the same pattern: choose a short descriptive prefix for the package and use `<prefix>-<version>`.
+
+## How Publishing Works
+
+Creating a GitHub Release triggers the [`pypi-publish.yml`](.github/workflows/pypi-publish.yml) workflow automatically. The workflow:
+
+1. **Builds** both packages using [Hatch](https://hatch.pypa.io/) (`hatch build`).
+2. **Uploads** the built distributions as artifacts.
+3. **Publishes** each package to [PyPI](https://pypi.org/) using trusted publishing (OIDC-based, no API tokens required).
+
+The workflow runs on the `release: [published]` event, so it fires whenever a release is published on GitHub — no manual intervention is needed beyond creating the release.
+
+> **Note:** The workflow builds and publishes all packages in the matrix. Ensure the version in each package's `__about__.py` is correct before publishing. If only one package has a version bump, PyPI will reject the re-upload of the unchanged package (which is expected and harmless since `fail-fast: false` is set).
+
+## Release Notes Format
+
+Release notes should maintain separate timelines for each package. Use the following structure:
+
+```markdown
+## aws-durable-execution-sdk-python v1.6.0
+
+### Features
+- Added support for X
+- New `context.foo()` API
+
+### Bug Fixes
+- Fixed issue with Y under Z conditions
+
+### Breaking Changes
+- Removed deprecated `bar()` method
+
+---
+
+## aws-durable-execution-sdk-python-otel v0.3.0
+
+### Features
+- Added tracing for `map` operations
+
+### Bug Fixes
+- Fixed span context propagation in child contexts
+```
+
+If only one package is being released, include only that package's section. Each package's changelog should be self-contained so users can follow the history of the package they depend on independently.
+
+## Checklist
+
+Before publishing a release:
+
+- [ ] Version bumped in the relevant `__about__.py` file(s)
+- [ ] Changes merged to `main`
+- [ ] CI checks pass on `main`
+- [ ] Release notes written with separate sections per package
+- [ ] Tag follows the naming convention (`sdk-X.Y.Z`, `otel-X.Y.Z`, or comma-separated)