From b6743d52265045203dfd9fedd531643c11e77195 Mon Sep 17 00:00:00 2001 From: ShortArrow Date: Fri, 24 Jul 2026 10:39:58 +0900 Subject: [PATCH] docs: define QA and support responsibility scope Add ADR 0047 fixing the quality-assurance boundary: per-release verification matrix, pre-1.0 compatibility contract (--json schemas and config.toml are stable; breaks need a minor bump + CHANGELOG), point-in-time verified-instrument list, and best-effort/latest-only support. Add SECURITY.md (private vulnerability reporting, scope notes). Surface the user-facing summary in README (EN/JP) with the Kikusui PWR801L entry, and link the ADR from CONTRIBUTING (EN/JP). Refresh the README status line to v0.2.8. --- README.md | 22 +++- SECURITY.md | 37 ++++++ docs/CONTRIBUTING.jp.md | 4 + docs/CONTRIBUTING.md | 4 + docs/README.jp.md | 22 +++- ...047-quality-assurance-and-support-scope.md | 108 ++++++++++++++++++ 6 files changed, 195 insertions(+), 2 deletions(-) create mode 100644 SECURITY.md create mode 100644 docs/adr/0047-quality-assurance-and-support-scope.md diff --git a/README.md b/README.md index 76aff46..4f59089 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ `ivi-cli` is an integrated CLI for managing, diagnosing, and operating instruments addressed via VISA/IVI. -> Status: **v0.2.7 (pre-1.0.0).** Phase 1–3 are landed: CLI core, HiSLIP / VXI-11 / SOCKET gateways, scenario-driven mock-VISA container (ghcr.io/shortarrow/ivi-cli-mock), Management HTTP / WebSocket API with PAT + TLS + audit, OpenTelemetry, and LAN discovery (LXI mDNS + VXI-11 broadcast, plus opt-in `--port` socket sweep). Breaking changes are still possible. See [CHANGELOG.md](docs/CHANGELOG.md). +> Status: **v0.2.8 (pre-1.0.0).** Phase 1–3 are landed: CLI core, HiSLIP / VXI-11 / SOCKET gateways, scenario-driven mock-VISA container (ghcr.io/shortarrow/ivi-cli-mock), Management HTTP / WebSocket API with PAT + TLS + audit, OpenTelemetry, and LAN discovery (LXI mDNS + VXI-11 broadcast, plus opt-in `--port` socket sweep). Breaking changes are still possible. See [CHANGELOG.md](docs/CHANGELOG.md). ## Highlights @@ -170,6 +170,26 @@ flowchart LR The internal layering — Clean Architecture with a one-way dependency direction, enforced by an architecture-test suite — is a contributor concern, intentionally omitted from this user-facing README. +## Support & quality + +**What every release verifies.** A `vX.Y.Z` release is published only after, at the tagged commit: + +- each of the six binaries (win / linux / osx × x64 / arm64) is built, passes the unit + architecture test suite, and is smoke-run **on a native runner of the same OS and architecture**; +- the mock container passes a HEALTHCHECK + SCPI round-trip smoke natively on **both** amd64 and arm64 before the multi-arch push; +- the tag, project version, and CHANGELOG entry agree. + +The integration suite (real sockets, PyVISA interop) runs nightly on three OSes; it is not a release gate. + +**Compatibility promise (pre-1.0).** While the version is 0.x, two surfaces are stable contracts: the **`--json` output schemas** and the **`config.toml` / scenario TOML schema**. Breaking either requires a minor version bump (0.Y → 0.Y+1) with an explicit CHANGELOG entry — patch releases never break them. Everything else (human-readable output, log text, Management API shape, container internals) may change in any release until 1.0. + +**Verified instruments.** Entries are point-in-time: verified at the recorded version, not re-verified on later releases. Instruments not listed fall under best-effort standards conformance (HiSLIP, VXI-11, raw SOCKET, IEEE 488.2 / SCPI) — incompatibility with a spec-conforming instrument is a bug; attach an `IVICLI_CAPTURE` traffic log to the report. + +| Instrument | Verified at | Result | +| --- | --- | --- | +| Kikusui PWR801L | v0.2.6 | SOCKET (5025) and HiSLIP (4880) round-trips work; LAN discovery finds it. VXI-11 portmapper resolution works, but queries are blocked by a device-side Core-port issue. | + +**Support.** GitHub issues, best-effort, no SLA. Only the latest release is supported — fixes ship as new releases, no backports. For vulnerabilities see [SECURITY.md](SECURITY.md). + ## Documentation - [PRD](docs/PRD.md) — full product requirements diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..dcf6297 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,37 @@ +# Security Policy + +## Supported versions + +Only the **latest release** receives security fixes. Fixes ship as a +new release from `main`; there are no backport branches. If you are +pinned to an older version, upgrade to the latest release before +reporting. + +## Reporting a vulnerability + +Please **do not open a public issue** for security problems. Use +GitHub's private vulnerability reporting instead: + +1. Go to the repository's **Security** tab. +2. Choose **Report a vulnerability** and describe the issue — + affected command/component, reproduction steps, and impact. + +Reports are acknowledged on a best-effort basis (this is a +volunteer-maintained project, no SLA). Confirmed vulnerabilities are +fixed in the next release and credited in the advisory unless you +ask otherwise. + +## Scope notes + +- The **Management API** (`ivicli api start`) binds to loopback by + default; binding beyond loopback is designed to be used with PAT + authentication and TLS. Configurations that expose the API without + them are out of scope. +- The **gateway servers** (HiSLIP / VXI-11 / SOCKET) implement + instrument protocols that have no authentication by design. Run + them on trusted networks only; "an unauthenticated peer can send + SCPI to the gateway" is inherent to those protocols, not a + vulnerability. +- The **mock container** is a test fixture. Reports about hardening + the image are welcome, but it is not intended for exposure to + untrusted networks. diff --git a/docs/CONTRIBUTING.jp.md b/docs/CONTRIBUTING.jp.md index 4f1f0b1..a945885 100644 --- a/docs/CONTRIBUTING.jp.md +++ b/docs/CONTRIBUTING.jp.md @@ -43,6 +43,10 @@ xUnit + Shouldly + Testably.Abstractions。テストは `src/` を 1:1 でミラ Integration テストは `[Trait("Category", "Integration")]` を付与し、PR ビルドでは既定で skip され、`nightly.yml` で実行されます。 +## 品質保証とサポート範囲 + +各リリースが検証する内容、pre-1.0 の互換性契約、動作確認済み計測器の方針、サポート水準 — [ADR 0047](adr/0047-quality-assurance-and-support-scope.md) を参照。プラットフォームカバレッジ（出荷 RID ごとのネイティブテスト + スモーク）— [ADR 0016](adr/0016-cross-platform-policy.md) を参照。脆弱性は public issue ではなく [SECURITY.md](../SECURITY.md) を通して報告してください。 + ## ADR Accepted な意思決定はすべて [`docs/adr/`](adr/) に置きます。ADR は生きたドキュメントとして通常の PR で更新し、本質的な反転がある場合にのみ supersede します。索引ファイルは設けません。 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 6fbff09..119b952 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -43,6 +43,10 @@ xUnit + Shouldly + Testably.Abstractions. Tests mirror `src/` 1:1 (`IviCli. ステータス: **v0.2.7 (pre-1.0.0)。** Phase 1〜3 が landed: CLI core、HiSLIP / VXI-11 / SOCKET gateway、シナリオ駆動 mock-VISA コンテナ (ghcr.io/shortarrow/ivi-cli-mock)、Management HTTP / WebSocket API (PAT + TLS + audit)、OpenTelemetry、LAN discovery (LXI mDNS + VXI-11 broadcast、および opt-in の `--port` socket sweep)。1.0.0 までは 破壊的変更の可能性が残ります。[CHANGELOG.md](CHANGELOG.md) も参照。 +> ステータス: **v0.2.8 (pre-1.0.0)。** Phase 1〜3 が landed: CLI core、HiSLIP / VXI-11 / SOCKET gateway、シナリオ駆動 mock-VISA コンテナ (ghcr.io/shortarrow/ivi-cli-mock)、Management HTTP / WebSocket API (PAT + TLS + audit)、OpenTelemetry、LAN discovery (LXI mDNS + VXI-11 broadcast、および opt-in の `--port` socket sweep)。1.0.0 までは 破壊的変更の可能性が残ります。[CHANGELOG.md](CHANGELOG.md) も参照。 ## ハイライト @@ -170,6 +170,26 @@ flowchart LR 内部の層構成（Clean Architecture と一方向の依存方向、アーキテクチャテストで強制）は、コントリビュータ向けの関心事であり、この利用者向け README には含めていません。 +## サポートと品質 + +**各リリースが検証していること。** `vX.Y.Z` リリースは、タグ付けされたコミットで以下すべてが通過した場合のみ公開されます: + +- 6 種のバイナリ (win / linux / osx × x64 / arm64) それぞれについて、ビルド + unit / architecture テストスイート通過に加え、**同一 OS・同一アーキテクチャのネイティブランナー上で** 起動スモークを実行; +- mock コンテナが multi-arch push の前に、amd64 / arm64 **両方の** ネイティブ環境で HEALTHCHECK + SCPI round-trip スモークを通過; +- タグ・プロジェクトバージョン・CHANGELOG エントリの一致。 + +Integration スイート（実ソケット、PyVISA 相互運用）は 3 OS 上で nightly 実行されますが、リリースゲートではありません。 + +**互換性の約束 (pre-1.0)。** バージョンが 0.x の間、次の 2 面を安定した契約として扱います: **`--json` 出力スキーマ** と **`config.toml` / scenario TOML スキーマ**。いずれかを破壊する変更には minor バージョンアップ (0.Y → 0.Y+1) と CHANGELOG への明示的な記載が必須です — patch リリースはこれらを壊しません。それ以外（human-readable 出力、ログ文言、Management API の形状、コンテナ内部）は 1.0 まではどのリリースでも変わり得ます。 + +**動作確認済み計測器。** エントリは point-in-time です: 記録されたバージョンで確認したものであり、以降のリリースで再確認はしません。リストにない計測器は標準規格準拠 (HiSLIP, VXI-11, raw SOCKET, IEEE 488.2 / SCPI) を目標とする best-effort の扱いです — 規格準拠の計測器と互換性がない場合はバグとして扱います。報告には `IVICLI_CAPTURE` のトラフィックログを添付してください。 + +| 計測器 | 確認バージョン | 結果 | +| --- | --- | --- | +| Kikusui PWR801L | v0.2.6 | SOCKET (5025) と HiSLIP (4880) の round-trip が動作。LAN discovery で発見可能。VXI-11 は portmapper 解決まで動作するが、機器側の Core ポート問題により query は不可。 | + +**サポート。** GitHub issues による best-effort、SLA なし。サポート対象は最新リリースのみ — 修正は新リリースとして出荷し、backport は行いません。脆弱性は [SECURITY.md](../SECURITY.md) を参照。 + ## ドキュメント - [PRD](PRD.jp.md) — プロダクト要件 diff --git a/docs/adr/0047-quality-assurance-and-support-scope.md b/docs/adr/0047-quality-assurance-and-support-scope.md new file mode 100644 index 0000000..aa0fe5e --- /dev/null +++ b/docs/adr/0047-quality-assurance-and-support-scope.md @@ -0,0 +1,108 @@ +# 0047. Quality Assurance and Support Scope + +- Status: Accepted +- Date: 2026-07-24 + +## Context + +ivi-cli is pre-1.0 and ships through four channels — self-contained +binaries for six RIDs, a `dotnet tool` package, the mock-VISA +container, and source ([ADR 0018](0018-deployment-strategy.md)). Its +primary external consumers are **3rd-party e2e pipelines that embed +the mock container in their CI** and lab operators driving real +instruments. Both need to know what they can depend on: which +artifacts were actually executed before release, which interfaces are +safe to script against, and what happens when a real instrument +misbehaves. Until now that boundary existed only implicitly — in the +CI workflows, in scattered ADRs, and in the licenses' warranty +disclaimers, none of which tell a consumer what the maintainers *aim* +to uphold. + +This ADR fixes the quality-assurance and support responsibility +scope in one place. The licenses (MIT OR Apache-2.0) continue to +disclaim all legal warranty; everything below is a maintenance +commitment, not a guarantee. + +## Decision + +### 1. What every release verifies + +A `vX.Y.Z` release is blocked unless all of the following pass, in a +clean CI environment, at the tagged commit: + +| Artifact | Verification | +| --- | --- | +| Self-contained binary, each of 6 RIDs | Build + unit/architecture suite + start-up smoke of the published binary, on a **native runner of the same OS/arch** ([ADR 0016](0016-cross-platform-policy.md)) | +| Mock container (`linux/amd64` + `linux/arm64`) | HEALTHCHECK + SCPI round-trip smoke, each architecture natively, before the multi-arch push | +| `dotnet tool` nupkg | Packed from the same commit; carries the same IL as the smoke-run binaries, not separately executed | +| Version metadata | Tag = `Directory.Build.props` `` = CHANGELOG entry (release guard job) | + +Known, accepted gap: the Integration suite (real sockets, PyVISA +interop) runs on `nightly.yml` across three OSes but is **not** a +release gate; a release may ship between a regression and the nightly +that catches it. + +### 2. Compatibility contract (pre-1.0) + +While the version is 0.x, two surfaces are treated as **stable +contracts**: + +1. **`--json` output schemas** of every command. +2. **`config.toml` schema** (devices, servers, routes, and the + scenario TOML format). + +A breaking change to either requires a **minor** version bump +(0.Y → 0.Y+1) and an explicit CHANGELOG entry naming the break; +patch releases never break them. Both surfaces are pinned in CI by +Verify snapshots and parser tests, so an accidental break fails the +PR, not the consumer. + +Everything else — human-readable output, log text and levels, the +Management API shape, exit-message wording, container internals +(base image, layout), and all .NET APIs of the shipped assemblies — +may change in any release until 1.0. From 1.0 on, Semantic +Versioning applies to the whole public surface. + +### 3. Real-instrument compatibility: point-in-time verified list + +Compatibility with physical instruments is handled by a +**verified-instrument list** (published in the README): + +- An entry records the instrument model, the protocols exercised, + the ivi-cli version at which the verification happened, and any + device-side caveats found. +- Entries are **point-in-time**: they state what was observed at the + recorded version and are *not* re-verified on subsequent releases. + Continuous re-verification would grow an unbounded hardware test + matrix; protocol behaviour is instead protected by the automated + suites (gateway round-trips, PyVISA interop, RPC/framing unit + tests), which do run on every change. +- Instruments not on the list fall under **best-effort standards + conformance**: ivi-cli targets the published HiSLIP, VXI-11, + raw-SOCKET, and IEEE 488.2 / SCPI specifications, and instrument + incompatibilities are treated as bugs when the instrument follows + those specifications. Reports with an `IVICLI_CAPTURE` traffic log + attached are the expected input. + +### 4. Support level + +- Support happens through **GitHub issues, best-effort, no SLA**. +- Only the **latest release** is supported. Fixes ship as a new + release from `main`; there are no backport branches + ([ADR 0022](0022-branching-strategy.md) — trunk only). +- Vulnerability reports go through the private channel defined in + `SECURITY.md`, not public issues. + +## Consequences + +- Consumers can pin CI on the two contract surfaces (`--json`, + `config.toml`) with a documented upgrade signal (minor bump + + CHANGELOG), instead of guessing which parts of a 0.x tool are safe + to script. +- The verified-instrument list gives buyers of bench time an honest + datum without committing the project to a hardware regression + matrix it cannot sustain. +- "Latest release only" keeps the maintenance surface at one branch; + users who cannot upgrade must vendor a fix themselves. +- The README's user-facing summary of this scope must be kept in + sync with this ADR when either changes.