From 2eb9765a8b8f2f538cc83ff5838501540ffe8db0 Mon Sep 17 00:00:00 2001 From: Martin Belanger Date: Fri, 17 Jul 2026 11:30:02 -0400 Subject: [PATCH] doc: add NEWS.md Proposed release notes file, modeled on systemd's NEWS, for discussion before the format is settled. Signed-off-by: Martin Belanger --- NEWS.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 NEWS.md diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000000..0cafd6d882 --- /dev/null +++ b/NEWS.md @@ -0,0 +1,121 @@ + +# NEWS + +> This file tracks user-facing changes for each release: new +> features, behavior changes, and anything that could break an +> existing setup. Loosely modeled on systemd's NEWS file +> (https://github.com/systemd/systemd/blob/main/NEWS): one prose +> paragraph per entry, "Feature removals and incompatible changes" +> listed first in each release section since that's what someone +> upgrading most needs to see, then changes grouped by component. +> Add an entry here alongside the change that introduces it, not +> after the fact at release time -- it's much easier to describe a +> change accurately while it's fresh than to reconstruct it later +> from a commit log. +> +> Lines in this file are wrapped at ~75 columns on purpose, unlike +> our other markdown docs: this file is meant to still read cleanly +> in a plain editor or if a section is copy-pasted into an email, +> not only when viewed through a renderer. + +## Changes in 3.0 (unreleased) + +### Feature removals and incompatible changes + +* `nvme disconnect-all` with no options no longer disconnects every + fabric controller. It now only disconnects controllers with no + recorded owner in the new ownership registry (see below); a + controller owned by another orchestrator is silently skipped. To + restore the old disconnect-everything behavior, use `--force` + (prompts for confirmation when run interactively), or use + `--owner NAME` to disconnect only the controllers owned by a + specific orchestrator. + +* Hostname entries in the legacy `config.json` connection file are + now rejected with a clear error instead of sometimes silently + resolving. Previously this worked via `nvme connect-all`/`nvme + discover` but already failed via `nvme connect -J`; both paths now + fail the same way. Direct CLI usage is unaffected: `nvme connect + -a `, `--host-traddr `, and discovery.conf + entries all still resolve exactly as before. Convert `config.json` + to the new INI connection format (see below) to keep using + hostnames in a file. + +* libnvme itself no longer resolves hostnames. `libnvmf_add_ctrl()` + and `libnvmf_connect_ctrl()` now fail immediately on a hostname + traddr/host_traddr instead of resolving it internally -- the + caller is responsible for resolving first. A deliberate, permitted + 3.0 API break; nvme-stas (the only external consumer using this + path) already resolves before calling, so this is a non-issue + there in practice. + +* Transport IDs (TIDs), the identifier now shared internally by the + registry, the exclusion list, and connection matching, only accept + a numeric traddr/host_traddr for the tcp and rdma transports; a + hostname is rejected at construction time rather than silently + accepted. + +* *(pending, not yet merged)* The default installation will stop + shipping the essentially-empty `/etc/nvme/discovery.conf` stub (a + comment-only template with no real entries). Nothing should have + been relying on its mere presence for scripting purposes; it was + never meant to be more than a placeholder. + +### New: ownership registry and exclusion list + +* A new ownership registry (`nvme registry`, backed by + `/run/nvme/registry/`) records which orchestrator -- a daemon like + nvme-stas or nvme-discoverd, or a manual connect -- owns each + connected controller. This is what lets `disconnect-all` (above) + and future orchestrator tooling avoid tearing down a connection + another component depends on. See `libnvme/design/REGISTRY.md`. + +* A new system-wide exclusion list (`nvme exclusion`, backed by + `/etc/nvme/exclusions.conf` and `exclusions.conf.d/` drop-ins) + lets an administrator block specific controllers -- by transport, + address, or NQN -- from being auto-connected. It's aimed + primarily at auto-discovered controllers, which have no config + entry to remove in order to suppress an unwanted connection. See + `libnvme/design/EXCLUSIONS.md`. + +### nvme-cli + +* `nvme connect` gained `--idempotent` and `--devid-file`. + `--idempotent` makes connecting to an already-connected controller + succeed instead of erroring. `--devid-file` writes the resulting + `nvmeX` device name to the given file on success, so a caller that + doesn't know the device name at connect time (for example, a + systemd unit spawned before the device exists) can look it up + afterward instead of scraping `dmesg` or polling sysfs. + +### libnvme + +* A new INI-format connection configuration parser and writer have + been added (`nvme-fabrics.conf` + `nvme-fabrics.conf.d/` drop-ins, + intended to eventually replace `config.json`/`discovery.conf`). + Not yet used by `nvme connect-all`/`nvme discover` -- that + integration is still in progress. See `libnvme/design/CONFIG.md` + for the format. + +* Read-only Python bindings for the new config format + (`config_read()`, `config_validate()`) are available now for early + adopters (e.g. nvme-stas) that want to start reading the new + format ahead of the CLI's own switch-over. + +* The accessor generator that produces libnvme's getter/setter + boilerplate (`accessors.c`/`.h`) has been rewritten in Python, + with the struct annotations it reads now living in-source in + `private.h` instead of a separate spec file. Relevant to + developers extending libnvme's public structs, not to CLI end + users. + +> Open question, not yet decided: whether to also generate a +> mechanically-produced contributor list per release (roughly `git +> shortlog -sn ..HEAD`), the way systemd's own +> announcement emails do. Cheap to produce, credits everyone who +> touched the release. + +## Older changes + +Not backfilled. See the git log and GitHub release/tag history for +anything before this file existed.