Deployment and Operations
Overview
How DevWorkWire is built, verified, published, and diagnosed.
Documents
| Document | Description |
|---|---|
| deployment-architecture.md | Distribution model and channels, supported platforms, version adoption and rollback, data durability, environment strategy |
| ci-cd-pipeline.md | Branching and PR conventions, GitHub Actions pipeline stages, the test matrix, security-critical tests, the publish flow, hotfixes, state-store migration |
| monitoring-observability.md | Local logging and run_id correlation, failure surfacing, why there is no telemetry, privacy in observability |
The Constraint That Shapes This Domain
A published release cannot be recalled. Yanking a version blocks new installs; every already-installed copy keeps running, on a machine holding a live Jira token. There is no control plane, no rollout, no canary, and — by deliberate choice — no telemetry to detect a bad release.
Three consequences run through all three documents:
- Verification is front-loaded. The publish pipeline gates PyPI behind a TestPyPI clean-install smoke test, which is what actually enforces NFR-009-01 rather than hoping for it.
- Supply-chain controls are weighted heavily. Trusted Publishing (no long-lived token to steal) plus PEP 740 attestations — see Security Architecture.
- Detection depends on users reporting. So
run_idcorrelation, an accurate version string, redacted-by-default output, and easy-to-find issue reporting are the monitoring strategy, not a substitute for one.
Key Decisions
| Decision | Value |
|---|---|
| CI/CD | GitHub Actions — required for the OIDC identity behind Trusted Publishing |
| Test matrix | Linux + macOS × Python 3.11 / 3.12 / 3.13 (6 jobs) |
| Windows | Not supported, stated explicitly rather than left ambiguous |
| Branch protection | PRs required, force pushes blocked, CI must pass; 0 approvals while single-maintainer, rising to 1/2 when a second joins |
| Release trigger | Tag vX.Y.Z on main → TestPyPI → clean-install smoke test → PyPI → Homebrew tap |
| Versioning | Manual SemVer bump and hand-written changelog, verified by CI (FR-009-04) |
| Telemetry | None, and none planned |
Related ADRs
- ADR-007 — build backend, distribution, and release integrity
- ADR-008 — CI platform, quality gates, and security tests
- ADR-009 — no telemetry; local diagnosability only
- ADR-010 — two-branch fork-based workflow, CI as the merge gate
- ADR-002 — Python floor and supported platforms
Requirements Coverage
| Requirement | Where addressed |
|---|---|
| FR-009-01 | PyPI publish pipeline; dwire console script verified by the smoke test |
| FR-009-02 | pipx documented as the recommended channel |
| FR-009-03 | Homebrew tap updated from the publish pipeline with a pinned sdist hash |
| FR-009-04 | SemVer rules tied to the tool/CLI surface; CI fails the release without a matching version and changelog entry |
| NFR-009-01 | TestPyPI clean-install smoke test gates the PyPI publish |
| NFR-X01 | pip-audit blocking on Critical/High; CodeQL; Dependabot; Trusted Publishing |
| NFR-X03 | Coverage gate (≥80% on WorkItemService and provider adapters) enforced in CI |
| NFR-X06 | Text-prefixed errors and warnings; verified by review and non-TTY output checks |
NFR-X04 / NFR-X05 | Still TBD. No deployment-side constraint exists; targets remain unset in requirements |