Re: [PATCH RFC] docs: Add minimum version depencency policy document

[George Dunlap <George.Dunlap@xxxxxxxxxx>]

> On Oct 1, 2020, at 1:58 PM, Andrew Cooper <Andrew.Cooper3@xxxxxxxxxx> wrote:
> 
> On 30/09/2020 13:57, George Dunlap wrote:
>> Define a specific criteria for how we determine what tools and
>> libraries to be compatible with.  This will clarify issues such as,
>> "Should we continue to support Python 2.4" moving forward.
> 
> Luckily that one is settled.  Arguably a better option might be "what is
> the minimum toolchain to support" ?
> 
>> Note that CentOS 7 is set to stop receiving "normal" maintenance
>> updates in "Q4 2020"; assuming that 4.15 is released after that, we
>> only need to support CentOS / RHEL 8.
> 
> While I appreciate that this doesn't mean "we'll break CentOS 7 in Q4",
> I'm going to have some substantial development issues if C7 actually
> stops working, at least in the short to medium term.

You’re going to have development issues in the short-to-medium term as C7 stops 
getting bug-fixes anyway.  I’m pretty sure you already re-compile your own 
versions of a lot of the toolchains and libraries; if you stay on C7 you’ll 
just have to add things in one by one (or use updated versions from EPEL) as 
things come up.

>> Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxx>
>> ---
>> 
>> CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
>> CC: Wei Liu <wl@xxxxxxx>
>> CC: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
>> CC: Jan Beulich <jbeulich@xxxxxxxx>
>> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
>> CC: Julien Grall <julien@xxxxxxx>
>> CC: Rich Persaud <persaur@xxxxxxxxx>
>> CC: Bertrand Marquis <Bertrand.Marquis@xxxxxxx>
>> ---
>> docs/index.rst                        |  2 +
>> docs/policies/dependency-versions.rst | 76 +++++++++++++++++++++++++++
>> 2 files changed, 78 insertions(+)
>> create mode 100644 docs/policies/dependency-versions.rst
>> 
>> diff --git a/docs/index.rst b/docs/index.rst
>> index b75487a05d..ac175eacc8 100644
>> --- a/docs/index.rst
>> +++ b/docs/index.rst
>> @@ -57,5 +57,7 @@ Miscellanea
>> -----------
>> 
>> .. toctree::
>> +   :maxdepth: 1
>> 
>> +   policies/dependency-versions
> 
> I think it is great that this is going into Sphinx.
> 
> However, I'd prefer to avoid proliferating random things at the top
> level, to try and keep everything in a coherent structure.

I was hoping for your feedback on where to put this. :-)

> For better or worse, I guestimated at "admin guide" (end user and
> sysadmin guide), "guest docs" (VM ABI, and guest kernel developers), and
> "hypervisors docs" (hacking Xen).

Is “hypervisor” in this sense meant to mean the actual hypervisor 
(xen.git/xen), or the whole hypervisor system (i.e., everything in xen.git)?

It seems to me that we need something like the latter; in which case maybe we 
should change that section to “developer documentation” or something, with 
“hypervisor” as a section under that?

> I'm happy to shuffle the dividing lines if a better arrangement becomes
> obvious.  This particular doc logically lives with "building Xen from
> source".

I don’t see a “building Xen from source” section (except for Hypervisor 
Documentation/Code Coverage/Compiling Xen, which is obviously specific to code 
coverage).

If the main target of the page is to tell admins / downstreams what distros we 
support, then it might go under “Admin Guide” somewhere.  If the main target is 
to tell developers what versions they have to support / don’t have to support, 
then putting it under a newly-created “developer documentation” section would 
probably make the most sense.

I think I’d go with the latter, if you’re OK with it.


>>    glossary
>> diff --git a/docs/policies/dependency-versions.rst 
>> b/docs/policies/dependency-versions.rst
>> new file mode 100644
>> index 0000000000..d5eeb848d8
>> --- /dev/null
>> +++ b/docs/policies/dependency-versions.rst
>> @@ -0,0 +1,76 @@
>> +.. SPDX-License-Identifier: CC-BY-4.0
>> +
>> +Build and runtime dependencies
>> +==============================
>> +
>> +Xen depends on other programs and libraries to build and to run.
>> +Chosing a minimum version of these tools to support requires a careful
>> +balance: Supporting older versions of these tools or libraries means
>> +that Xen can compile on a wider variety of systems; but means that Xen
>> +cannot take advantage of features available in newer versions.
>> +Conversely, requiring newer versions means that Xen can take advantage
>> +of newer features, but cannot work on as wide a variety of systems.
>> +
>> +Specific dependencies and versions for a given Xen release will be
>> +listed in the toplevel README, and/or specified by the ``configure``
>> +system.  This document lays out the principles by which those versions
>> +should be chosen.
>> +
>> +The general principle is this:
>> +
>> +    Xen should build on currently-supported versions of major distros
>> +    when released.
>> +
>> +"Currently-supported" means whatever that distro's version of "full
>> +support".  For instance, at the time of writing, CentOS 7 and 8 are
>> +listed as being given "Full Updates", but CentOS 6 is listed as
>> +"Maintenance updates"; under this criterium, we would try to ensure
>> +that Xen could build on CentOS 7 and 8, but not on CentOS 6.
>> +
>> +Exceptions for specific distros or tools may be made when appropriate.
>> +
>> +One exception to this is compiler versions for the hypervisor.
>> +Support for new instructions, and in particular support for new safety
>> +features, may require a newer compiler than many distros support.
>> +These will be specified in the README.
> 
> The problem we have is that xen.git contains two very different things. 
> There is the hypervisor itself, which is embedded, and can easily be
> cross compiled, and there is the content of tools/ which depends on a
> lot of distro infrastructure.
> 
> We expect tools/ to work in any supported distro, without having to do
> weird toolchain gymnastics.
> 
> For xen/ at the moment we have a very obsolete toolchain requirements,
> and this is holding us back in some areas.  We're looking to bring that
> forward, and may consider that being newer than some of the old distros
> is necessary.
> 
> At the moment however, we have quite a lot of functionality which is
> dependent on being able to detect suitable toolchain.  GCOV and CET-SS
> are examples.  These features will turn themselves off in older distros,
> so while you can "build" Xen that far back, you might not get everything.
> 
> For CET in particular, there is no feasible way to support it on older
> toolchains.  (unless someone comes up with an extremely convincing way
> of hand-crafting memory operands using raw .byte's in inline assembler.)
> 
> I definitely don't think it is unreasonable for us to require the use of
> (potentially) bleeding edge toolchains if they want to use (potentially)
> bleeding edge features.  CET-SS isn't bleeding edge any more, but
> CET-IBT is due to the additional linker work required to make it
> function.  A future one which we need to do something about is Control
> Flow Integrity, which is Clang specific, depends on LTO, and caused
> Linux to up their minimum supported version to 10.0.1 which was when all
> the bugfixes got merged.

You seem to be explaining why I wrote this paragraph.  Did you have any 
specific changes you wanted to make? :-)

>> +
>> +Distros we consider when deciding minimum versions
>> +--------------------------------------------------
>> +
>> +We currently aim to support Xen building and running on the following 
>> distributions:
>> +Debian_,
>> +Ubuntu_,
>> +OpenSUSE_,
>> +Arch Linux,
> 
> No link for Arch?

The link points to the page describing the release lifecycles; Arch doesn’t 
really have that concept (as noted in the next section).

I could make it so that links to the release lifecycle page is in the table 
below instead.

> 
>> +SLES_,
>> +Yocto_,
>> +CentOS_,
>> +and RHEL_.
>> +
>> +.. _Debian: https://www.debian.org/releases/
>> +.. _Ubuntu: https://wiki.ubuntu.com/Releases
>> +.. _OpenSUSE: https://en.opensuse.org/Lifetime
>> +.. _SLES: https://www.suse.com/lifecycle/
>> +.. _Yocto: https://wiki.yoctoproject.org/wiki/Releases
>> +.. _CentOS: https://wiki.centos.org/About/Product
>> +.. _RHEL: https://access.redhat.com/support/policy/updates/errata
>> +
>> +Specific distro versions supported in this release
>> +--------------------------------------------------
>> +
>> +======== ==================
>> +Distro   Supported releases
>> +======== ==================
>> +Debian   10 (Buster)
>> +Ubuntu   20.10 (Groovy Gorilla), 20.04 (Focal Fossa), 18.04 (Bionic 
>> Beaver), 16.04 (Xenial Xerus)
>> +OpenSUSE Leap 15.2
>> +SLES     SLES 11, 12, 15
>> +Yocto    3.1 (Dunfell)
>> +CentOS   8
>> +RHEL     8
>> +======== ==================
> 
> How about a 3rd column for "supported until" ?  It would stop this page
> becoming stale simply over time.

If we did that, it would make the table longer, as we’d have a separate row for 
each distro release rather than each distro.

The release manager needs to look at this table before the release; for that 
they’ll have to go to the release lifecycle page of the various distros anyway, 
to pick up new versions of the distro.  So I don’t think having the date here 
adds that much.

> 
>> +
>> +.. note::
>> +
>> +   We also support Arch Linux, but as it's a rolling distribution, the
>> +   concept of "security supported releases" doesn't really apply.
> 
> Should we rationalise this list with the docker containers?

We definitely should.

For distros for which we can’t get docker containers in the gitlab CI (e.g., 
SLES, RHEL), maybe we could consider requiring a “maintainer” to step up and be 
responsible for testing them before each release.

 -George