diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 52e5b60d..9491cb2d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,19 +2,25 @@ ## Project Overview -This is the Durable Task Python SDK, providing a client and worker for -building durable orchestrations. The repo contains two packages: +This repository provides the Durable Task Python SDK and Azure Functions +provider implementations for building durable orchestrations. It contains +three packages: - `durabletask` — core SDK (in `durabletask/`) - `durabletask.azuremanaged` — Azure Durable Task Scheduler provider (in `durabletask-azuremanaged/`) +- `azure-functions-durable` — Azure Durable Functions provider (in + `azure-functions-durable/`) ## Changelog Requirements -- ALWAYS document user-facing changes in the appropriate changelog under - `## Unreleased`. -- Update `CHANGELOG.md` for core SDK changes and - `durabletask-azuremanaged/CHANGELOG.md` for provider changes. -- If a change affects both packages, update both changelogs. +- ALWAYS document user-facing changes in the applicable changelog under + `## Unreleased`. Create that section if the changelog does not yet have one. +- Update `CHANGELOG.md` for core SDK changes, + `durabletask-azuremanaged/CHANGELOG.md` for Durable Task Scheduler provider + changes, and `azure-functions-durable/CHANGELOG.md` for Azure Functions + provider changes. +- If a change affects multiple packages, update each affected package's + changelog. - Include changelog entries for externally observable outcomes only, such as new public APIs, behavior changes, bug fixes users can notice, breaking changes, and new configuration capabilities. @@ -24,8 +30,14 @@ building durable orchestrations. The repo contains two packages: - When in doubt, write the changelog entry in terms of user impact (what users can now do or what behavior changed), not implementation mechanism (how it was implemented internally). +- Changelogs are not covered by the CI Markdown lint step. Review changes to + them manually. +- Use the current unindented changelog style: category labels such as `ADDED`, + `CHANGED`, and `FIXED` are plain, unindented lines, and wrapped entry text + remains unindented rather than being aligned beneath the bullet. Examples: + - Include: "Added `get_orchestration_history()` to retrieve orchestration history from the client." - Exclude: "Added internal helper functions to aggregate streamed history chunks." @@ -61,10 +73,16 @@ priority over style. ## Python Linting This repository uses [flake8](https://flake8.pycqa.org/) for Python -linting. Run it after making changes to verify there are no issues: +linting. Run it after making changes to verify there are no issues. Lint +package source and its tests separately, matching CI: ```bash -python -m flake8 path/to/changed/file.py +python -m flake8 durabletask +python -m flake8 tests/durabletask +python -m flake8 durabletask-azuremanaged +python -m flake8 tests/durabletask-azuremanaged +python -m flake8 azure-functions-durable +python -m flake8 tests/azure-functions-durable ``` ## Markdown Style @@ -117,18 +135,42 @@ python -m pip install -r dev-requirements.txt ## Building and Testing -Install the packages locally in editable mode: +Use the repository-root `.venv` for core and Azure Managed development, and +for Azure Functions Durable linting, type checking, and unit tests. The Azure +Functions Durable package requires Python 3.13+, so use a 3.13+ root virtual +environment for that work. Install packages locally in editable mode: ```bash -python -m pip install -e . -e ./durabletask-azuremanaged +python -m pip install -e . -e ./durabletask-azuremanaged \ + -e ./azure-functions-durable ``` -Run tests with pytest: +Run the applicable unit tests with pytest. Azure Functions Durable unit tests +exclude tests that require an Azure Functions host or external services: ```bash python -m pytest +python -m pytest tests/azure-functions-durable \ + -m "not dts and not azurite and not functions_e2e" +``` + +Run Azure Functions Durable E2E tests through Nox, not directly from the root +virtual environment. Nox creates an isolated Python 3.13 session environment, +installs the local packages editable, and links it into each sample Function +app so the Functions worker loads the app's grpc/protobuf dependencies. The +suite requires Azure Functions Core Tools (`func`) on `PATH` and a running +Azurite instance with blob storage on port 10000: + +```bash +nox -s functions_e2e ``` +After the first successful run, use `nox -R -s functions_e2e` for E2E reruns. +`-R` reuses the Nox environment and skips reinstalls; because the packages are +editable, source changes are still picked up. Pass pytest selectors after `--`, +for example `nox -R -s functions_e2e -- -k "dtask_client"`. Do not manually +activate or modify the per-app `.venv` directories created by Nox. + ## Project Structure - `durabletask/` — core SDK source @@ -140,10 +182,23 @@ python -m pytest - `testing/` — in-memory backend for testing without a sidecar - `internal/` — protobuf definitions, gRPC helpers, tracing (not public API) - `durabletask-azuremanaged/` — Azure managed provider source +- `azure-functions-durable/` — Azure Durable Functions provider source - `examples/` — example orchestrations (see `examples/README.md`) - `tests/` — test suite - `dev-requirements.txt` — development dependencies +## External Dependencies + +The Azure Functions Durable provider integrates with APIs and runtime behavior +owned by these repositories. Consult their current source when changing +decorators, bindings, converters, or worker integration behavior: + +- [Azure Functions Python library](https://github.com/Azure/azure-functions-python-library) + — application, decorator, and binding APIs. +- [Azure Functions Python worker](https://github.com/Azure/azure-functions-python-worker) + — function loading, binding conversion, dependency isolation, and invocation + behavior. + ## Cross-Package Compatibility The `durabletask-azuremanaged` package extends the core `durabletask` diff --git a/.github/skills/release-prep/SKILL.md b/.github/skills/release-prep/SKILL.md index e2680c73..f3d95cc4 100644 --- a/.github/skills/release-prep/SKILL.md +++ b/.github/skills/release-prep/SKILL.md @@ -1,25 +1,31 @@ --- name: release-prep description: >- - Prepare a release for durabletask and durabletask.azuremanaged. Use when the - user asks for release prep, version bumping, changelog updates, or release - body drafting. Trigger phrases include: release prep, prepare vX.Y.Z, - changelog for release, and draft GitHub release notes. + Prepare a release for durabletask, durabletask.azuremanaged, or + azure-functions-durable. Use when the user asks for release prep, version + bumping, changelog updates, or release body drafting. Trigger phrases include: + release prep, prepare vX.Y.Z, changelog for release, and draft GitHub release + notes. --- # Release Prep -This skill prepares a coordinated release for both packages in this repository: +This skill prepares a coordinated release for all packages in this repository: - `durabletask` - `durabletask.azuremanaged` +- `azure-functions-durable` The skill accepts a target version (for example `1.4.0`) and performs the -required changes consistently. +required changes consistently. A single-package release is an exception: only +release one package when the user explicitly requests it, and record that +exception in the release-preparation instructions for that release. ## Inputs - `version`: Target semantic version (for example `1.4.0`) +- Optional: `packages` limits the release to named packages only when the user + explicitly requests a single-package release. - Optional: `baseTag` overrides for comparison if tags are non-standard If `version` is not provided, ask the user before continuing. @@ -30,31 +36,43 @@ If `version` is not provided, ask the user before continuing. - Root package range: `v..HEAD` - Azure managed package range: `azuremanaged-v..HEAD` +- Azure Functions package range: `azurefunctions-v..HEAD` - Use commit subjects and touched files to classify each change as: - `durabletask` only - `durabletask.azuremanaged` only + - `azure-functions-durable` only - shared/infra/docs changes ### 2. Update package versions -Update both project versions: +Update all project versions: - `pyproject.toml` -> `version = ""` - `durabletask-azuremanaged/pyproject.toml` -> `version = ""` +- `azure-functions-durable/pyproject.toml` -> `version = ""` -Update azuremanaged dependency floors: +Update Azure Managed dependency floors: - `durabletask>=` - `durabletask[azure-blob-payloads]>=` +Update the `azure-functions-durable` `durabletask` dependency floor when the +coordinated release establishes a new compatible core SDK minimum. For an +explicit single-package Azure Functions release, do not change that floor +solely because the provider package version changes. + ### 3. Update changelogs -- Add a new `## v` section directly under `## Unreleased` in: - - `CHANGELOG.md` - - `durabletask-azuremanaged/CHANGELOG.md` +- Add a new `## v` section directly under `## Unreleased` in every + package's changelog. Create `## Unreleased` if it is absent: + - `CHANGELOG.md` for `durabletask` + - `durabletask-azuremanaged/CHANGELOG.md` for `durabletask.azuremanaged` + - `azure-functions-durable/CHANGELOG.md` for `azure-functions-durable` - Ensure user-facing changes since the previous release tags are represented. - Keep entries concise and grouped by type (`ADDED`, `CHANGED`, `FIXED`, `REMOVED`) where applicable. +- Follow the repository's unindented changelog style. Changelogs are not + covered by CI Markdown linting, so review their formatting manually. - Exclude internal-only changes from changelogs (for example CI/workflow-only updates, test-only changes, and implementation refactors with no public behavior or API impact). @@ -71,23 +89,26 @@ Before creating draft releases in GitHub UI, require explicit user confirmation of both conditions: - The version-bump/release-prep PR is merged -- Tags `v` and `azuremanaged-v` already exist in the target - repository +- Tags for every package already exist in the target repository: + `v` for `durabletask`, `azuremanaged-v` for + `durabletask.azuremanaged`, and `azurefunctions-v` for + `azure-functions-durable` If either condition is not met, stop after preparing release body text and ask the user to confirm once merge and tags are complete. ### 6. Draft GitHub release bodies -Draft two release body texts for the GitHub Releases UI (do not add files to +Draft three release body texts for the GitHub Releases UI (do not add files to the repository): -- Tag: `v` -- Tag: `azuremanaged-v` +- `durabletask`: `v` +- `durabletask.azuremanaged`: `azuremanaged-v` +- `azure-functions-durable`: `azurefunctions-v` Match existing release structure: -- Title (`# v` or `# azuremanaged-v`) +- Title matching the package tag - `## What's Changed` - `## External Links` - `### Contributors` diff --git a/README.md b/README.md index ac532ffb..3b4f3041 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,15 @@ MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/ Validation](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml/badge.svg)](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml) [![PyPI version](https://badge.fury.io/py/durabletask.svg)](https://badge.fury.io/py/durabletask) -This repo contains a Python SDK for use with the [Azure Durable Task -Scheduler](https://github.com/Azure/Durable-Task-Scheduler). With this SDK, you can define, -schedule, and manage durable orchestrations using ordinary Python code. +This repository contains Python SDKs for building durable orchestrations with +[Azure Durable Task Scheduler](https://github.com/Azure/Durable-Task-Scheduler) +and [Azure Durable Functions](https://learn.microsoft.com/azure/azure-functions/durable/): -> Note that this SDK is **not** currently compatible with [Azure Durable -Functions](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview). If -you are looking for a Python SDK for Azure Durable Functions, please see [this -repo](https://github.com/Azure/azure-functions-durable-python). +- [`durabletask`](./durabletask/) is the core orchestration SDK. +- [`durabletask.azuremanaged`](./durabletask-azuremanaged/) is the Azure Durable + Task Scheduler provider. +- [`azure-functions-durable`](./azure-functions-durable/) is a preview Azure + Durable Functions provider built on `durabletask`. ## References @@ -21,6 +22,7 @@ repo](https://github.com/Azure/azure-functions-durable-python). - [Available Features](./docs/features.md) - [Getting Started](./docs/getting-started.md) - [Development Guide](./docs/development.md) +- [Azure Functions Durable 2.x](./azure-functions-durable/README.md) - [Contributing Guide](./CONTRIBUTING.md) ## Optional Features diff --git a/azure-functions-durable/README.md b/azure-functions-durable/README.md index 1ac9bef9..7063e2db 100644 --- a/azure-functions-durable/README.md +++ b/azure-functions-durable/README.md @@ -38,6 +38,9 @@ calls (`context.call_http(...)`), recurring scheduled tasks, and history export. - [Changelog](CHANGELOG.md) - [Durable Functions documentation](https://learn.microsoft.com/azure/azure-functions/durable/) - [`durabletask` on PyPI](https://pypi.org/project/durabletask/) +- [Azure Functions Durable 1.x source](https://github.com/Azure/azure-functions-durable-python) +- [Azure Functions Python library](https://github.com/Azure/azure-functions-python-library) +- [Azure Functions Python worker](https://github.com/Azure/azure-functions-python-worker) - [Repository](https://github.com/microsoft/durabletask-python) ## License