docs: crosscheck the handoff docs against the tree they describe

HANDOFF and the roadmap had drifted from what is actually there:

- the test count was 552; it is 574.  `tox -e docs` doctests all of doc/,
  not just doc/example/ -- so basics.rst is verified, while test_debug.rst
  and test_ssh_fileserver.rst have no doctests and nothing checks them.
- `execnet info` answers six keys, not five, and "version" is spelled
  "execnet".  Its `protocols` list has no reader anywhere and omits
  `share`, so a Windows remote understates itself -- recorded under
  roadmap item 1, which is where that payload gets settled.
- the file map was missing _trace.py, _gevent_support.py and __main__.py.
- roadmap section 5 "Stale wording" was itself stale: the ExecModel
  docstring and _shim.REMOVED_IN were both fixed already.  Same for the
  changelog, which is renumbered to 3.0.

Elsewhere: the README still advertised zero-install bootstrapping and
eventlet, which 3.0 reversed and killed respectively; and the deselect in
xdist-known-failures.txt justified itself with a launch command
(`python -m execnet._trio_worker`) that is not the launch contract, in the
file a maintainer reads to judge whether the deselect still holds.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: RonnyPfannschmidt

.github/xdist-known-failures.txt

@@ -13,7 +13,7 @@
 
 # Asserts `sys.argv == ["-c"]`, and its own docstring says it is
 # documenting "the behavior due to execnet using `python -c`".  execnet no
-# longer ships source over the wire: workers are launched as
-# `python -m execnet._trio_worker <config>`, so sys.argv legitimately
-# differs.  Needs an xdist-side update, not an execnet fix.
+# longer ships source over the wire: workers are launched through the CLI
+# (`python -m execnet worker --protocol-... --config ...`), so sys.argv
+# legitimately differs.  Needs an xdist-side update, not an execnet fix.
 testing/test_remote.py::test_remote_inner_argv

HANDOFF.md

@@ -11,12 +11,17 @@ This is the doc to read first.  Two companions:
 ## How to work here
 
 ```
-uv run pytest testing/          # 552 passed, 66 skipped
-uv run pytest testing/ -n 12    # must stay green (~7s)
+uv run pytest testing/          # 574 passed, 66 skipped
+uv run pytest testing/ -n 12    # must stay green (~8s)
 uv run pre-commit run -a        # never grep-filter its output
-uv run tox -e docs              # builds with -W and doctests doc/example/
+uv run tox -e docs              # sphinx -W, then doctests all of doc/
 ```
 
+`tox -e docs` doctests the whole `doc/` tree, not just the examples:
+`doc/basics.rst` is executed too, so a `>>>` block there is checked.  The
+two files with no `>>>` in them — `doc/example/test_debug.rst` (the trace
+transcript) and `test_ssh_fileserver.rst` — are prose nothing verifies.
+
 ssh paths have a real local harness in `testing/test_ssh_local.py` (an
 asyncssh server; needs a system ssh client).  Hypothesis stress coverage
 is `testing/test_channel_stress.py` behind `--stress=N`.
@@ -42,8 +47,10 @@ protocol (`Message` framing) is unchanged from 2.1.
 
 **No source is shipped over the wire, ever.**  Workers are launched as
 `execnet worker <transport> <config>`; foreign and remote interpreters are
-uv-provisioned; a dev coordinator builds and ships a wheel.  Version skew
-gets a rough major/minor check (`_trio_worker._check_version`).
+uv-provisioned; a dev coordinator builds and ships a wheel.  A major/minor
+version skew is **refused** by the worker before it touches its stdio
+(`_trio_worker._check_version`); `EXECNET_IGNORE_VERSION_SKEW=1` in its
+environment or its config `env:` downgrades that to a warning.
 
 ### Four namespaces, one per concurrency library you drive execnet from
 
@@ -77,8 +84,10 @@ execnet info
 
 `ADDR` is `unix:/path` or `host:port`.  Everything that starts a worker
 emits these tokens; there is no second launch path.  `execnet info`
-answers JSON (version, trio, executable, platform, protocols) so
-provisioning learns a remote's version *before* connecting.
+answers JSON — keys `execnet`, `trio`, `python`, `executable`, `platform`,
+`protocols` — so provisioning learns a remote's version *before*
+connecting.  `protocols` is advisory today: nothing reads it, and it does
+not list `share` (see roadmap item 1, which is about this payload).
 
 `transport=socket|stdio` is a spec key; **`socket` is the default for
 every worker execnet spawns**, which is why a worker's stdio is free for
@@ -128,6 +137,8 @@ the coordinator's shape does not dictate the worker's.
 | `_cli.py` / `_socketserver.py` / `_provision.py` | the CLI, `execnet server`, uv provisioning + argv builders |
 | `_execmodel.py` | `WORKER_PROFILES`, `resolve_profile`, and the deprecated `ExecModel` xdist shim |
 | `_rsync.py` / `_rsync_remote.py` / `_xspec.py` / `_exec_source.py` | rsync, spec parsing, remote_exec source normalization |
+| `_trace.py` / `_gevent_support.py` | `EXECNET_DEBUG` tracing; the gevent wait backend's hub plumbing |
+| `__main__.py` / `_version.py` | `python -m execnet` → `_cli.main`; the generated version |
 | `_shim.py` + `gateway*.py`, `multi.py`, `rsync*.py`, `xspec.py` | the deprecated pre-Trio module names, warning and forwarding |
 
 ## Invariants — do not regress

README.rst

@@ -13,8 +13,8 @@ execnet: distributed Python deployment and communication
 .. image:: https://github.com/pytest-dev/execnet/workflows/test/badge.svg
     :target: https://github.com/pytest-dev/execnet/actions?query=workflow%3Atest
 
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/python/black
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+    :target: https://github.com/astral-sh/ruff
 
 .. _execnet: https://execnet.readthedocs.io
 
@@ -29,7 +29,9 @@ a minimal and fast API targeting the following uses:
 Features
 --------
 
-* zero-install bootstrapping: no remote installation required!
+* automatic provisioning: a target environment that lacks execnet is set up
+  with uv_, so no manual remote installation is required -- and no source of
+  our own is ever shipped over the wire
 
 * flexible communication: send/receive as well as
   callback/queue mechanisms supported
@@ -40,5 +42,8 @@ Features
 
 * interoperable between Windows and Unix-ish systems.
 
-* integrates with different threading models, including standard
-  os threads, eventlet and gevent based systems.
+* one namespace per concurrency library you drive it from: threads
+  (``execnet``), trio (``execnet.trio``), asyncio (``execnet.aio``) and
+  gevent (``execnet.gevent``).
+
+.. _uv: https://docs.astral.sh/uv/

ROADMAP-3.0.md

@@ -6,8 +6,7 @@ for.
 
 ## Why 3.0, not 2.2
 
-The branch was drafted as 2.2 and the changelog still called it that.  It
-is a major release:
+The branch was drafted as 2.2.  It is a major release:
 
 - the launch contract changed — a worker is `execnet worker …`, and no
   source is bootstrapped over the wire;
@@ -80,6 +79,12 @@ prefer it and fall back to `"trio"` only for a 2.x-vintage remote.  Keep
 emitting `"trio"` indefinitely.  One line, and it buys the freedom to
 answer honestly from an engine that is not Trio.
 
+Settle the rest of the payload in the same pass, since it is the same
+cross-version contract.  It is `execnet`, `trio`, `python`, `executable`,
+`platform`, `protocols` today; `protocols` has no reader at all and does
+not list `share`, so a Windows remote understates what it can do.  Either
+give it a reader or say in the docs that it is informational.
+
 ### 2. Deprecated names out of `__all__`
 
 `set_execmodel` is advertised as supported API by `execnet.__all__` and
@@ -167,12 +172,6 @@ we are); adopt the private-stdlib trick and own its seams; or note that
 makes `execnet.gevent` work in the environment gevent users actually have.
 Decide before 3.0, because it is what the namespace promises.
 
-### 5. Stale wording
-
-`_execmodel.ExecModel`'s docstring still describes the `loop=`/`exec=`/
-`wait=` axes, which were dropped before they shipped.  `_shim.REMOVED_IN`
-says `execnet 3.0`, which is now wrong per the policy above.
-
 ## What pins us to Trio
 
 Two futures get conflated and have different answers:
@@ -330,9 +329,8 @@ arriving.
 ## Suggested order
 
 1. `execnet info` capability key, `__all__` cleanups, underscore the engine
-   methods, fix the stale wording — small, and item 1 cannot be changed
-   after release.
-2. Changelog and docs renumbered to 3.0; undraft PR #422.
+   methods — small, and item 1 cannot be changed after release.
+2. Undraft PR #422.  (The changelog and docs are renumbered already.)
 3. Decide the execnet/xdist split for provisioning + workspaces, then build
    points 1–3 of that section.  This is what the next xdist waits on.
 4. Kubernetes: decide in-tree versus extension point, then the proxy.

doc/basics.rst

@@ -396,9 +396,10 @@ The execnet command line
     and forwards here with a ``DeprecationWarning``.
 
 ``execnet info``
-    Print this interpreter's execnet version, trio availability, executable,
-    platform and supported transports as JSON.  A coordinator uses it to
-    decide whether a ``python=`` interpreter can host a worker directly.
+    Print this interpreter's execnet version, trio availability, Python
+    version, executable, platform and supported protocols as JSON.  A
+    coordinator uses it to decide whether a ``python=`` interpreter can host
+    a worker directly.
 
 ``execnet worker ...``
     The launch contract between a coordinator and the worker process it

doc/example/test_ssh_fileserver.rst

@@ -11,7 +11,7 @@ And here is some code to use it to retrieve remote contents::
 
     import execnet
     import servefiles
-    gw = execnet.makegateway("ssh=codespeak.net")
+    gw = execnet.makegateway("ssh=myhost")
     channel = gw.remote_exec(servefiles)
 
     for fn in ('/etc/passwd', '/etc/group'):