Hi,

A question came up in #d-mentors about whether the `unshare` backend
provided `isolation-container`. I thought this would be reasonably
simply, I just look up the man page for autopkgtest and it will say, right?

No, but it does have:
on the qemu example (seems reasonable enough that the main man page
cannot list all backends). But autopkgtest-virt-unshare does not mention
the restriction(s) it supports, nor that it does not support any of them.

The autopkgtest-virt-qemu man page does not mention `isolation` either
despite autopkgtest(1) seemingly calling it out as an example of
something that would provide `isolation-machine`. I am now 3 man pages
in and I have given up answering the question, because I have lost faith
in the man pages to provide the documentation I was hoping for (I was
not going to reverse engineer/code search for this one).

I think this situation could be improved by having each of the
`autopkgtest-virt-X` man pages list the capabilities they provide with
exactly the same label used in the `Restrictions` field.

It could be as simple as:

```
The autopkgtest-virt-X backend provides capabilities to run tests with
the following restrictions:

  * `isolation-machine` (which implies `isolation-container`)

  * `needs-internet` provided `--network=allow-internet`

```

or

```
The autopkgtest-virt-unshare backend does **not** provide capabilities
to run tests that have any restrictions such as `isolation-container`.
Consider `autopkgtest-virt-X` if you need stronger isolation.
```

Another alternative is to have a matrix of backend vs. restrictions
linked from autopkgtest(1).

For me, the key feature being tags like `isolation-container` and
`restriction` is what I find in autopkgtests documentation, so I know I
should find it if I search for words like those.

Best regards,
Niels

PS: I think it is more obvious what kind of capabilities each backend
has if you know what the tool stack does (such as `qemu` providing
`isolation-machine`). But it is still not always clear. As an example,
given `unshare(1)` can do network namespacing, it does seem reasonable
that it would provide `isolation-container` given that restriction seems
to be mostly about local network stacks.

   But `autopkgtest-virt-unshare` does not provide `isolation-container`
based on feedback in #d-mentors, so my gut reaction on would have been
the wrong answer. "Fortunately", I got stuck in the docs and the true
answer came out first.