chore: Make samples default to use PyPI for the SDK

Author: abeiderman

.github/workflows/ci.yml

@@ -91,5 +91,9 @@ jobs:
         with:
           enable-cache: true
 
-      # Each sample resolves the SDK by local path, so it is not locked against a release.
+      # Each sample pins a released SDK from PyPI, so this checks the published wheel.
       - run: make samples
+
+      # And again against this working tree, which is what catches a breaking API change before
+      # it ships. Both matter: the first can fail on a bad release, the second on a bad commit.
+      - run: make samples-local

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install hooks lint format typecheck test coverage build verify-lock dist-check samples profile check check-all clean
+.PHONY: install hooks lint format typecheck test coverage build verify-lock dist-check samples samples-local profile check check-all clean
 
 install:
 	uv sync --all-extras
@@ -50,14 +50,32 @@ dist-check: build
 			"import configdirector; print('wheel imports cleanly:', configdirector.__version__)"; \
 	status=$$?; rm -rf "$$tmp"; exit $$status
 
-# Samples resolve the SDK by local path, so this is what catches a breaking API change.
+# Samples resolve the SDK from PyPI, so this checks the published release against the sample
+# code -- it does NOT exercise the working tree, and will not catch a breaking API change here.
 samples:
 	@for sample in samples/*/; do \
 		[ -f "$$sample/pyproject.toml" ] || continue; \
 		printf '\n\033[1m==> sample %s\033[0m\n' "$$(basename $$sample)"; \
 		(cd "$$sample" && uv sync --quiet && uv run mypy && uv run pytest) || exit 1; \
 	done
 
+# Companion to `samples`: the same apps, resolved against the SDK in this working tree instead
+# of the released wheel. `samples` proves the published release still works with the sample code;
+# this proves an unreleased API change has not broken it. Without this target a breaking change
+# passes every check, because the samples pin a version from PyPI.
+#
+# uv sync installs the pinned release, then the editable install replaces it in the same
+# environment, and --no-sync stops uv from undoing that before the checks run. The override is
+# not written to any file, so nothing here can be committed by accident; the next plain
+# `make samples` restores the released version.
+samples-local:
+	@for sample in samples/*/; do \
+		[ -f "$$sample/pyproject.toml" ] || continue; \
+		printf '\n\033[1m==> sample %s (working-tree SDK)\033[0m\n' "$$(basename $$sample)"; \
+		(cd "$$sample" && uv sync --quiet && uv pip install --quiet -e ../.. \
+			&& uv run --no-sync mypy && uv run --no-sync pytest) || exit 1; \
+	done
+
 # Exploratory load profile of the Flask sample: see profiling/README.md. Deliberately not part
 # of `check-all` — it needs a real server SDK key, takes minutes, and measures the machine it
 # ran on as much as the SDK. Pass options through, e.g. `make profile ARGS="--rps 100"`.
@@ -69,7 +87,7 @@ profile:
 check: lint typecheck test
 
 # Everything CI runs. The pre-push hook calls this.
-check-all: verify-lock lint typecheck test dist-check samples
+check-all: verify-lock lint typecheck test dist-check samples samples-local
 	@printf '\n\033[1m✓ all checks passed\033[0m\n'
 
 clean:

samples/README.md

@@ -7,9 +7,15 @@ different web frameworks.
 |---|---|---|
 | [flask/](flask/) | [Flask](https://flask.palletsprojects.com/) | Minimal WSGI app: client lifecycle, per-request evaluation, SSR hydration |
 
-Each sample is an independent project with its own `pyproject.toml`. They depend on the SDK
-through a local path (`configdirector-server-sdk = { path = "../.." }`) so that they always run
-against the working copy in this repository rather than a published release.
+Each sample is an independent project with its own `pyproject.toml`, depending on the released
+`configdirector-server-sdk` from PyPI exactly as a real app would. They do not run against the
+working copy in this repository; to try a local change in a sample, add a temporary source
+override to that sample and remove it before committing:
+
+```toml
+[tool.uv.sources]
+configdirector-server-sdk = { path = "../..", editable = true }
+```
 
 To run one:
 

samples/flask/pyproject.toml

@@ -4,7 +4,9 @@ version = "0.0.0"
 description = "Flask sample app for the ConfigDirector Python server SDK"
 requires-python = ">=3.10"
 dependencies = [
-  "configdirector-server-sdk",
+  # Resolved from PyPI, like any consuming app would. The SDK is pre-1.0, so a 0.x minor is
+  # allowed to break: cap the range rather than tracking the newest release blindly.
+  "configdirector-server-sdk>=0.2,<0.3",
   "flask>=3.1",
   "python-dotenv>=1.0",
 ]
@@ -16,10 +18,6 @@ dev = ["mypy>=1.14", "pytest>=8.3"]
 # A runnable app, not a distributable package: install the dependencies, not this project.
 package = false
 
-[tool.uv.sources]
-# Always run against the SDK in this repository rather than a published release.
-configdirector-server-sdk = { path = "../..", editable = true }
-
 [tool.ruff]
 # Inherit the SDK's style, but resolve first-party imports against this directory so that
 # `configdirector` sorts as the third-party dependency it is here.