cloudflare · hoodmane · Jan 21, 2026
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -41,7 +41,7 @@ repos:
     rev: "v1.14.1"
     hooks:
       - id: mypy
-        exclude: (.*test.*)
+        exclude: (.*test.*|workers-runtime-sdk)
         additional_dependencies:
           - click
 ci:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,11 +23,21 @@ Thank you for your interest in contributing to workers-py! This document provide
 
 ## Development Setup
 
-Follow the [Development section](https://github.com/cloudflare/workers-py#development) of the README for setting up your development environment.
+This is a monorepo containing multiple Python packages. Each package is located in the `packages/` directory:
+
+- `packages/workers-py/` - The main workers-py package
+- `packages/workers-runtime-sdk/` - Python SDK for Cloudflare Workers
+
+### Working with a specific package
+
+```bash
+cd packages/<package-name>
+uv sync
+```
 
 ### Development Dependencies
 
-The project includes these development tools:
+Each package includes these development tools:
 - **pytest**: Testing framework
 - **ruff**: Fast Python linter
 - **mypy**: Static type checking
@@ -39,33 +49,52 @@ The project includes these development tools:
    git checkout -b your-username/your-change-name
    ```
 
-2. Run our code formatter via `uvx ruff format` and linter via `uvx ruff fix .`
+2. Navigate to the package you're modifying:
+   ```bash
+   cd packages/<package-name>
+   ```
+
+3. Run our code formatter via `uvx ruff format` and linter via `uvx ruff fix .`
 
-3. Add or update tests as needed
+4. Add or update tests as needed
 
-4. Run the test suite: `uv clean cache && uv run pytest`
+5. Run the test suite: `uv run pytest`
 
 ## Commit Message Guidelines
 
-This project uses automated semantic versioning via `python-semantic-release` which relies on
-tags in the commit message to determine whether a release should be made.
+This project uses automated semantic versioning via `python-semantic-release` with the
+**conventional-monorepo** parser, which relies on tags and scopes in the commit message
+to determine whether a release should be made for each package.
 
 ### Commit Format
 
 The format parsed by python-semantic-release is https://www.conventionalcommits.org/en/v1.0.0/#summary.
-It looks something like this:
+For monorepo support, use the package-specific scope prefix:
 
 ```
-<tag>(<optional scope>): <subject>
+<tag>(<package-prefix>): <subject>
 
 <body>
 
 <footer>
 ```
 
+### Package Scope Prefixes
+
+- `workers-py-` - For changes to the workers-py package
+- `workers-runtime-sdk-` - For changes to the workers-runtime-sdk package
+
+### Examples
+
+```
+feat(workers-py-): add new CLI command for syncing
+fix(workers-runtime-sdk-): handle edge case in API client
+docs(workers-py-): update README with new usage examples
+```
+
 ### Commit Tags
 
-Including "BREAKING CHANGE" in the commit message (either in the body or footer) will trigger a release.
+Including "BREAKING CHANGE" in the commit message (either in the body or footer) will trigger a major release.
 
 The following tags will trigger a release:
 
@@ -83,7 +112,7 @@ The following tags will not trigger a release:
 
 ## Release Process
 
-This project uses **python-semantic-release** for automated versioning and releases. Here's how it works:
+This project uses **python-semantic-release** with monorepo support for automated versioning and releases. Each package is released independently.
 
 ### Automated Releases
 
@@ -94,12 +123,21 @@ This project uses **python-semantic-release** for automated versioning and relea
 
 2. **Release Trigger**: Releases are created automatically when changes are pushed to the `main` branch
 
-3. **Release Artifacts**:
-   - Git tag (format: `v{version}`)
+3. **Release Artifacts** (per package):
+   - Git tag (format: `<package-name>-v{version}`, e.g., `workers-py-v1.7.0`)
    - Updated `pyproject.toml` version
    - Changelog generation
    - PyPI package publication (via GitHub Actions)
 
+### Manual Release
+
+To manually release a specific package:
+
+```bash
+cd packages/<package-name>
+semantic-release version
+```
+
 ## Submitting Changes
 
 1. **Push your branch** to your fork:
@@ -108,7 +146,7 @@ This project uses **python-semantic-release** for automated versioning and relea
    ```
 
 2. **Create a Pull Request** on GitHub with:
-   - Clear title following conventional commit format
+   - Clear title following conventional commit format with package scope
    - Description of changes made
    - Any breaking changes clearly documented
    - Explanation of how you tested your changes under a "Test Plan" section
@@ -125,4 +163,4 @@ This project uses **python-semantic-release** for automated versioning and relea
 - Check existing issues before creating new ones
 - For questions, use GitHub Discussions or open an issue
 
-Thank you for contributing to workers-py! 🚀
+Thank you for contributing to workers-py!
diff --git a/README.md b/README.md
@@ -1,69 +1,54 @@
-# workers-py
+# workers-py Monorepo
 
-A set of libraries and tools for Python Workers.
+A monorepo containing Python libraries and tools for Cloudflare Workers.
 
+## Packages
 
-## Pywrangler
+| Package | Description |
+|---------|-------------|
+| [workers-py](./packages/workers-py/) | A set of libraries and tools for Python Workers |
+| [workers-runtime-sdk](./packages/workers-runtime-sdk/) | Python SDK for Cloudflare Workers |
 
-A CLI tool for managing vendored packages in a Python Workers project.
+## Development
 
-### Installation
+### Prerequisites
 
-On Linux, you may be able to install the tool globally by running:
+- Python 3.12+
+- [uv](https://github.com/astral-sh/uv) for package management
 
-```
-uv tool install workers-py
-```
-
-Alternatively, you can add `workers-py` to your pyproject.toml:
+### Working with packages
 
-```
-[dependency-groups]
-dev = ["workers-py"]
-```
-
-Then run via `uv run pywrangler`.
-
-### Usage
+Each package is self-contained with its own `pyproject.toml`. To work on a specific package:
 
 ```bash
-uv run pywrangler --help
-uv run pywrangler sync
+cd packages/<package-name>
+uv sync
+uv run pytest
 ```
 
-### Development
+### Releasing
 
-To run the CLI tool while developing it, install it globally:
+This project uses [python-semantic-release](https://python-semantic-release.readthedocs.io/) with the monorepo configuration. Each package is released independently.
 
-```
-uv tool install -e .
-```
-
-Then run it via `pywrangler`.
-
-Alternatively, you can add `workers-py` to your pyproject.toml:
+To release a specific package:
 
+```bash
+cd packages/<package-name>
+semantic-release version
 ```
-[dependency-groups]
-dev = ["workers-py"]
 
-[tool.uv.sources]
-workers-py = { path = "../workers-py" }
-```
+### Commit Conventions
 
-Then run via `uv run pywrangler`.
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) with package-scoped commits for the monorepo. For package-specific changes, use the scope prefix:
 
-#### Lint
+- `feat(workers-py-): add new feature` - Feature for workers-py
+- `fix(workers-runtime-sdk-): fix bug` - Bug fix for workers-runtime-sdk
 
-```
-uv run ruff check --fix
-uv run ruff format
-```
+Tags:
+- `feat`: New feature (triggers minor version bump)
+- `fix`: Bug fix (triggers patch version bump)
+- `docs`, `style`, `refactor`, `test`, `chore`, `ci`: Non-release commits
 
-#### Tests
+## License
 
-```
-$ uv cache clean
-$ uv run pytest
-$ uv run pytest tests/test_cli.py::test_sync_command_handles_missing_pyproject -v # Specific test
-```
+MIT
diff --git a/CHANGELOG.md → packages/workers-py/CHANGELOG.md b/CHANGELOG.md → packages/workers-py/CHANGELOG.md
diff --git a/packages/workers-py/README.md b/packages/workers-py/README.md
@@ -0,0 +1,69 @@
+# workers-py
+
+A set of libraries and tools for Python Workers.
+
+
+## Pywrangler
+
+A CLI tool for managing vendored packages in a Python Workers project.
+
+### Installation
+
+On Linux, you may be able to install the tool globally by running:
+
+```
+uv tool install workers-py
+```
+
+Alternatively, you can add `workers-py` to your pyproject.toml:
+
+```
+[dependency-groups]
+dev = ["workers-py"]
+```
+
+Then run via `uv run pywrangler`.
+
+### Usage
+
+```bash
+uv run pywrangler --help
+uv run pywrangler sync
+```
+
+### Development
+
+To run the CLI tool while developing it, install it globally:
+
+```
+uv tool install -e .
+```
+
+Then run it via `pywrangler`.
+
+Alternatively, you can add `workers-py` to your pyproject.toml:
+
+```
+[dependency-groups]
+dev = ["workers-py"]
+
+[tool.uv.sources]
+workers-py = { path = "../workers-py" }
+```
+
+Then run via `uv run pywrangler`.
+
+#### Lint
+
+```
+uv run ruff check --fix
+uv run ruff format
+```
+
+#### Tests
+
+```
+$ uv cache clean
+$ uv run pytest
+$ uv run pytest tests/test_cli.py::test_sync_command_handles_missing_pyproject -v # Specific test
+```
diff --git a/pyproject.toml → packages/workers-py/pyproject.toml b/pyproject.toml → packages/workers-py/pyproject.toml
@@ -86,13 +86,17 @@ packages = ["src/pywrangler"]
 [tool.semantic_release]
 assets = []
 build_command_env = []
-commit_message = "{version}\n\nAutomatically generated by python-semantic-release"
-commit_parser = "conventional"
+commit_message = """\
+chore(release): workers-py@{version}
+
+Automatically generated by python-semantic-release
+"""
+commit_parser = "conventional-monorepo"
 logging_use_named_masks = false
 major_on_zero = true
 allow_zero_version = false
 no_git_verify = false
-tag_format = "v{version}"
+tag_format = "workers-py-v{version}"
 version_toml = ["pyproject.toml:project.version"]
 build_command = """
   python -m pip install -e .[build]
@@ -144,6 +148,8 @@ env = "GIT_COMMIT_AUTHOR"
 default = "semantic-release <semantic-release>"
 
 [tool.semantic_release.commit_parser_options]
+path_filters = ["."]
+scope_prefix = "workers-py-"
 minor_tags = ["feat"]
 patch_tags = ["fix", "perf"]
 other_allowed_tags = ["build", "chore", "ci", "docs", "style", "refactor", "test"]

diff --git a/src/pywrangler/__init__.py → ...ges/workers-py/src/pywrangler/__init__.py b/src/pywrangler/__init__.py → ...ges/workers-py/src/pywrangler/__init__.py
diff --git a/src/pywrangler/__main__.py → ...ges/workers-py/src/pywrangler/__main__.py b/src/pywrangler/__main__.py → ...ges/workers-py/src/pywrangler/__main__.py
diff --git a/src/pywrangler/cli.py → packages/workers-py/src/pywrangler/cli.py b/src/pywrangler/cli.py → packages/workers-py/src/pywrangler/cli.py
diff --git a/src/pywrangler/metadata.py → ...ges/workers-py/src/pywrangler/metadata.py b/src/pywrangler/metadata.py → ...ges/workers-py/src/pywrangler/metadata.py
diff --git a/src/pywrangler/py.typed → packages/workers-py/src/pywrangler/py.typed b/src/pywrangler/py.typed → packages/workers-py/src/pywrangler/py.typed
diff --git a/src/pywrangler/sync.py → packages/workers-py/src/pywrangler/sync.py b/src/pywrangler/sync.py → packages/workers-py/src/pywrangler/sync.py
diff --git a/src/pywrangler/types.py → packages/workers-py/src/pywrangler/types.py b/src/pywrangler/types.py → packages/workers-py/src/pywrangler/types.py
diff --git a/src/pywrangler/utils.py → packages/workers-py/src/pywrangler/utils.py b/src/pywrangler/utils.py → packages/workers-py/src/pywrangler/utils.py
diff --git a/tests/test_cli.py → packages/workers-py/tests/test_cli.py b/tests/test_cli.py → packages/workers-py/tests/test_cli.py
diff --git a/tests/test_py_version_detect.py → ...orkers-py/tests/test_py_version_detect.py b/tests/test_py_version_detect.py → ...orkers-py/tests/test_py_version_detect.py
diff --git a/tests/test_types.py → packages/workers-py/tests/test_types.py b/tests/test_types.py → packages/workers-py/tests/test_types.py