Developer experience goals
Goal for SDK 0.3.0 / ABConnect 8_01
A developer with provisioned staging credentials can install the package, make a first read-only call, understand the inventory/handling-unit and shipment model, and migrate a supported legacy call using the published documentation. Release success includes an installable PyPI package and matching Read the Docs content, both verified from the same release commit.
Acceptance measures
Outcome |
Measurement |
|---|---|
First successful call in 10 minutes |
A developer unfamiliar with the SDK follows the quickstart in a clean environment with provisioned credentials; record elapsed time and blockers. Credential provisioning time is excluded. |
Find a common task in two navigation steps |
From the docs home, reach setup, What’s New, inventory/handling units, multiple shipments, compatibility, or troubleshooting in at most two clicks. Verify those links in rendered HTML. |
Examples match the installed release |
Every changed public method has a complete example with imports, inputs, a real SDK call, and expected response shape or evidence link. Verify signatures offline and capture safe staging behavior. |
Migrate without guessing |
The compatibility matrix maps every affected legacy SDK entry point to its supported route or adapter, warning, replacement, and evidence. No unclassified affected entry remains at release. |
Operate on the intended shipment |
A two-active-shipment scenario proves an operation targeting A leaves B unchanged and ambiguous mutations require context. |
Diagnose the common failures |
Setup/auth, scope, model validation, API errors, and shipment selection have concrete next steps; an onboarding review can find them. |
Package and docs agree |
PyPI install, artifact version, Git tag/commit, RTD versioned build, and stable docs match. Capture URLs and commit IDs in the release record. |
0.3.0 evidence and continuing goals
The automated clean-wheel smoke check completed installation, import/CLI discovery, and the first authenticated staging read in 2.13 seconds with provisioned credentials. An independent first-time developer has not completed a timed study; the 10-minute human onboarding target remains an ongoing usability measure.
The docs home directly links setup, What’s New, migration, and troubleshooting. The migration guide covers inventory/handling units, explicit shipment identifiers, rate preview versus saved selection, conflict handling, and compatibility. Generated endpoint pages show Python/CLI signatures and model fields. Reviewed staging captures and two-shipment isolation checks accompany the contract tests.
The compatibility matrix classifies affected methods. Removed server contracts fail before HTTP instead of silently losing fields. Some endpoints have contract/source coverage without live mutation certification; the validation report records that boundary and the normal-carrier-cancellation failure.
The maintainer executing the release verifies PyPI installation and the matching Read the Docs version, stable routing, and release commit using the runbook. Publication evidence belongs in the GitHub release. Future DX work includes a first-time developer review and broader carrier/endpoint live coverage. These goals must not be reported as measured until evidence exists.