[ovs-dev,ovn,v3] Document process for compatibility between OVS and OVN.

This document serves to provide an explanation for how OVN will remain
compatible with OVS. It provides instructions for OVN contributors for
how to maintain compatibility even across older versions of OVS when
possible.

It also creates a document to detail compatibility of specific OVN
versions.

Signed-off-by: Mark Michelson <mmichels@redhat.com>
---
v2 -> v3:
* Removed RFC designation
* Added the compatibility document for specific versions of OVS and OVN
* Clarified compatibility concerns prior to the split
* Mentioned possibility of a change to OVS major version as a reason for
  dropping compatibility.
* Clarified where warning messages should be output in the case that
  feature incompatibility is detected.
* Added mention of "tested" and "untested" versions of OVS for
  compatibility.
 ---
 Documentation/automake.mk                          |   1 +
 Documentation/internals/contributing/index.rst     |   1 +
 .../contributing/ovs-ovn-compatibility.rst         | 153 +++++++++++++++++++++
 Documentation/topics/index.rst                     |   1 +
 Documentation/topics/ovs-compatibility.rst         |  69 ++++++++++
 5 files changed, 225 insertions(+)
 create mode 100644 Documentation/internals/contributing/ovs-ovn-compatibility.rst
 create mode 100644 Documentation/topics/ovs-compatibility.rst

Bleep bloop.  Greetings Mark Michelson, I am a robot and I have tried out your patch.
Thanks for your contribution.

I encountered some error that I wasn't expecting.  See the details below.


checkpatch:
WARNING: Line is 80 characters long (recommended limit is 79)
#81 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:30:
This document discusses the general policy of compatibility between OVS and OVN.

WARNING: Line is 80 characters long (recommended limit is 79)
#104 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:53:
which versions of OVS. When incompatibilities are discovered, it is important to

WARNING: Line is 80 characters long (recommended limit is 79)
#107 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:56:
The split of OVS and OVN happened in the run-up to the release of OVS 2.12. As a

WARNING: Line is 80 characters long (recommended limit is 79)
#115 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:64:
The first way that the projects can become incompatible is if the C code for OVN

WARNING: Line is 80 characters long (recommended limit is 79)
#128 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:77:
incompatibility. OVN developers will be expected to regularly update the version

WARNING: Line is 80 characters long (recommended limit is 79)
#148 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:97:
common way this would happen is if new OpenFlow capabilities are added to OVS as

WARNING: Line has trailing whitespace
#162 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:111:
2. Make the necessary changes to OVN. 

WARNING: Line has trailing whitespace
#165 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:114:
     is not present, then output an informational message to the logs that 

WARNING: Line is 80 characters long (recommended limit is 79)
#189 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:138:
withdraw compatibility support with a previous OVS version, for reasons such as:

WARNING: Line is 80 characters long (recommended limit is 79)
#202 FILE: Documentation/internals/contributing/ovs-ovn-compatibility.rst:151:
OVS. Therefore, we will maintain a list of "tested" and "untested" compabitility

WARNING: Line is 82 characters long (recommended limit is 79)
#263 FILE: Documentation/topics/ovs-compatibility.rst:41:
    OVN version X.Y is 100% feature compatible with OVS versions A.B.C and higher.

WARNING: Line is 80 characters long (recommended limit is 79)
#276 FILE: Documentation/topics/ovs-compatibility.rst:54:
    OVN version X.Y has not been tested against OVS versions prior to A.(B-3).0,

WARNING: New doc ovs-compatibility.rst not listed in Documentation/automake.mk
Lines checked: 294, Warnings: 13, Errors: 0


Please check this out.  If you feel there has been an error, please email aconole@redhat.com

Thanks,
0-day Robot

Thanks Mark. Please see minor comments inlined. Also:
Acked-by: Han Zhou <hzhou8@ebay.com>

On Wed, Sep 25, 2019 at 10:33 AM Mark Michelson <mmichels@redhat.com> wrote:
>
> This document serves to provide an explanation for how OVN will remain
> compatible with OVS. It provides instructions for OVN contributors for
> how to maintain compatibility even across older versions of OVS when
> possible.
>
> It also creates a document to detail compatibility of specific OVN
> versions.
>
> Signed-off-by: Mark Michelson <mmichels@redhat.com>
> ---
> v2 -> v3:
> * Removed RFC designation
> * Added the compatibility document for specific versions of OVS and OVN
> * Clarified compatibility concerns prior to the split
> * Mentioned possibility of a change to OVS major version as a reason for
>   dropping compatibility.
> * Clarified where warning messages should be output in the case that
>   feature incompatibility is detected.
> * Added mention of "tested" and "untested" versions of OVS for
>   compatibility.
>  ---
>  Documentation/automake.mk                          |   1 +
>  Documentation/internals/contributing/index.rst     |   1 +
>  .../contributing/ovs-ovn-compatibility.rst         | 153
+++++++++++++++++++++
>  Documentation/topics/index.rst                     |   1 +
>  Documentation/topics/ovs-compatibility.rst         |  69 ++++++++++
>  5 files changed, 225 insertions(+)
>  create mode 100644
Documentation/internals/contributing/ovs-ovn-compatibility.rst
>  create mode 100644 Documentation/topics/ovs-compatibility.rst
>
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index f7e1d2628..d9bd4be1f 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -56,6 +56,7 @@ DOC_SOURCE = \
>         Documentation/internals/contributing/documentation-style.rst \
>         Documentation/internals/contributing/libopenvswitch-abi.rst \
>         Documentation/internals/contributing/submitting-patches.rst \
> +       Documentation/internals/contributing/ovs-ovn-compatibility.rst \
>         Documentation/requirements.txt \
>         $(addprefix Documentation/ref/,$(RST_MANPAGES)
$(RST_MANPAGES_NOINST))
>  FLAKE8_PYFILES += Documentation/conf.py
> diff --git a/Documentation/internals/contributing/index.rst
b/Documentation/internals/contributing/index.rst
> index a46cb046a..7ef57a1e2 100644
> --- a/Documentation/internals/contributing/index.rst
> +++ b/Documentation/internals/contributing/index.rst
> @@ -36,3 +36,4 @@ The below guides provide information on contributing to
Open vSwitch itself.
>     coding-style-windows
>     documentation-style
>     libopenvswitch-abi
> +   ovs-ovn-compatibility
> diff --git
a/Documentation/internals/contributing/ovs-ovn-compatibility.rst
b/Documentation/internals/contributing/ovs-ovn-compatibility.rst
> new file mode 100644
> index 000000000..0ff4f5ba9
> --- /dev/null
> +++ b/Documentation/internals/contributing/ovs-ovn-compatibility.rst
> @@ -0,0 +1,153 @@
> +..
> +      Copyright (c) 2019 Red Hat, Inc.
> +
> +      Licensed under the Apache License, Version 2.0 (the "License");
you may
> +      not use this file except in compliance with the License. You may
obtain
> +      a copy of the License at
> +
> +          http://www.apache.org/licenses/LICENSE-2.0
> +
> +      Unless required by applicable law or agreed to in writing, software
> +      distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT
> +      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the
> +      License for the specific language governing permissions and
limitations
> +      under the License.
> +
> +      Convention for heading levels in Open vSwitch documentation:
> +
> +      =======  Heading 0 (reserved for the title in a document)
> +      -------  Heading 1
> +      ~~~~~~~  Heading 2
> +      +++++++  Heading 3
> +      '''''''  Heading 4
> +
> +      Avoid deeper levels because they do not render well.
> +
> +===============================
> +Keeping OVN Compatible with OVS
> +===============================
> +
> +This document discusses the general policy of compatibility between OVS
and OVN.
> +If you are looking for a listing of version compatiblity, please see

s/compatiblity/compatibility

> +:doc:`topics/ovs-compatibility`
> +
> +OVN has split from OVS. Prior to this split, there were few issues with
> +compatibility. All code changes happened at the same time and in the
same repo.
> +New releases contained the latest OVS and OVN changes. The most commonon
time

s/commonon/common

> +that  compatibility typically came into question was during an upgrade;
there
> +might be a brief period where mismatched versions of OVS and OVN are
running.
> +That situation was transient.
> +
> +With OVN and OVS being developed and versioned separately, previous
assumptions
> +regarding compatibility are no longer valid. It is valid to permanently
run a
> +version of OVN that is different from the concurrent version of OVS.
> +
> +OVS and OVN versions
> +--------------------
> +
> +Prior to the split, the release schedule for OVN was bound to the release
> +schedule for OVS. OVS releases a new version approximately every 6
months. OVN
> +has not yet determined a release schedule, but it is entirely possible
that it
> +will be different from OVS. Eventually, this will lead to a situation
where it
> +is very important that we publish which versions of OVN are compatible
with
> +which versions of OVS. When incompatibilities are discovered, it is
important to
> +ensure that these are clearly stated.
> +
> +The split of OVS and OVN happened in the run-up to the release of OVS
2.12. As a
> +result, all versions of OVN *must* be compiled against OVS version 2.12
or
> +later. Before going further into compatibility, let's explore the ways
that OVN
> +and OVS can become incompatible.
> +
> +Compile-time Incompatibility
> +----------------------------
> +
> +The first way that the projects can become incompatible is if the C code
for OVN
> +no longer can compile.
> +
> +The most likely case for this would be that an OVN change requires a
parallel
> +change to OVS. Those keeping up to date with OVN but not OVS will find
that OVN
> +will no longer compile since it refers to a nonexistent function or out
of date
> +function in OVS.
> +
> +Most OVN users will consume OVN via package from their distribution of
choice.
> +OVN consumes libopenvswitch statically, so even if the version of OVS
installed
> +on a user's machine is incompatible at compile time, it will not matter.
> +
> +OVN developers are the only ones that would be inconvenienced by a
compile-time
> +incompatibility. OVN developers will be expected to regularly update the
version
> +of OVS they are using. If an OVN developer notices that OVN is not
compiling,
> +then they should update their OVS code to the latest and try again.
> +
> +Developers who are making changes to both OVS and OVN at the same time
*must*
> +contribute the OVS change first and ensure it is merged upstream before
> +submitting the OVN change. This way, OVN should never be in a state
where it
> +will not compile.
> +
> +The other aspect to consider is compiling an older release of OVN
against a
> +newer release of OVS. In practice, this is not typically something that
someone
> +would want to do. However, if it is desired for some reason, then the
ABI and
> +API guarantees for OVS's libraries should allow for OVN to compile
properly. An
> +exception to this may be if OVS changes major versions. When OVS changes
major
> +versions, they reserve the right to make breaking changes to the API and
ABI.
> +
> +Runtime Incompatibility
> +-----------------------
> +
> +The next way that the projects may become incompatible is at runtime.
The most
> +common way this would happen is if new OpenFlow capabilities are added
to OVS as
> +part of an OVN change. In this case, if someone updates OVN but does not
also
> +update OVS, then OVN will not be able to install the OpenFlow rules it
wishes
> +to.
> +
> +Unlike with compile-time incompatibilities, we can't wallpaper over the
fact
> +that the OVS installation is not up to date. The best we can do is make
it very
> +clear at runtime that a certain feature is not present, and if the
feature is
> +desired, OVS must be upgraded.
> +
> +The following is the process that OVN developers should use when making a
> +runtime compatibility change to OVS and OVN.
> +
> +1. Submit the change to OVS first. See the change through until it is
merged.
> +2. Make the necessary changes to OVN.
> +
> +  a. At startup, probe OVS for the existence of the OpenFlow addition.
If it
> +     is not present, then output an informational message to the logs
that
> +     explains which OVN feature(s) cannot be used.
> +  b. If a user attempts to explicitly configure the feature that is not
usable
> +     due to the incompatibility, then output a warning message to the
logs. If
> +     the lack of the feature can be detected from a utility (such as
ovn-nbctl
> +     or ovn-sbctl), then the utility should return an error and print to
the
> +     console why the feature cannot be used.
> +  c. Ensure that the code that installs the OpenFlow will only do so if
the new
> +     feature is present.
> +
> +Compatibility Statement
> +-----------------------
> +
> +Given the above, the OVN team will try its hardest to maintain any
released
> +version of OVN with any released version of OVS after version 2.12.
Versions of
> +OVS prior to 2.12 are not guaranteed to run properly since OVN does not
have
> +appropriate OpenFlow feature probes in place.
> +
> +It may seem prudent to only guarantee compatibility with certain
releases of
> +OVS (e.g. the current and previous versions of OVS). However, dropping
> +compatibility would involve actively removing code that ensures runtime
safety.
> +It seems unwise to do so.
> +
> +This, however, is a "best effort" policy. The OVN project reserves the
right to
> +withdraw compatibility support with a previous OVS version, for reasons
such as:
> +
> +- Security risks.
> +- Earthshatteringly large changes in OVS (e.g. no longer using OpenFlow
or the
> +  OVSDB). This likely would coincide with a change in the OVS major
version
> +  number.
> +- Difficulty in safely maintaining compatibility across versions.
> +
> +In the event that compatibility for a certain version or versions of OVS
is
> +dropped, the OVN project will clearly document it.
> +
> +At some point, the compatibility matrix between OVS and OVN will likely
become
> +too complex to explicitly test every version of OVN against every
version of
> +OVS. Therefore, we will maintain a list of "tested" and "untested"
compabitility
> +options for OVS and OVN. "untested" combinations *should* work, but
since they
> +have not had explicit testing done, they cannot be guaranteed.
> diff --git a/Documentation/topics/index.rst
b/Documentation/topics/index.rst
> index a34925f2e..d3a4eb70a 100644
> --- a/Documentation/topics/index.rst
> +++ b/Documentation/topics/index.rst
> @@ -41,6 +41,7 @@ OVN
>     role-based-access-control
>     ovn-news-2.8
>     testing
> +   ovs-compatibility
>
>  .. list-table::
>
> diff --git a/Documentation/topics/ovs-compatibility.rst
b/Documentation/topics/ovs-compatibility.rst
> new file mode 100644
> index 000000000..c324a24cd
> --- /dev/null
> +++ b/Documentation/topics/ovs-compatibility.rst

As mentioned by 0-day robot, this file should be added to automake.

> @@ -0,0 +1,69 @@
> +..
> +      Copyright (c) 2019 Red Hat, Inc.
> +
> +      Licensed under the Apache License, Version 2.0 (the "License");
you may
> +      not use this file except in compliance with the License. You may
obtain
> +      a copy of the License at
> +
> +          http://www.apache.org/licenses/LICENSE-2.0
> +
> +      Unless required by applicable law or agreed to in writing, software
> +      distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT
> +      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the
> +      License for the specific language governing permissions and
limitations
> +      under the License.
> +
> +      Convention for heading levels in Open vSwitch documentation:
> +
> +      =======  Heading 0 (reserved for the title in a document)
> +      -------  Heading 1
> +      ~~~~~~~  Heading 2
> +      +++++++  Heading 3
> +      '''''''  Heading 4
> +
> +      Avoid deeper levels because they do not render well.
> +
> +=================================
> +Compatibility between OVN and OVS
> +=================================
> +
> +This document lists versions of OVN and details their compatibility
against
> +versions of OVS. This document will be updated as new versions of OVS
and OVN
> +are released.
> +
> +For a more detailed look into OVN and OVS compatibility, see
> +:doc:`internals/contributing/ovs-ovn-compatiblity`.
> +
> +The following is a template for how a version might be documented:
> +
> +::
> +
> +    OVN version X.Y is 100% feature compatible with OVS versions A.B.C
and higher.
> +
> +    - OVN feature "foo" is unavailable in OVS versions A.(B-2).0 until
version
> +      A.B.C.
> +
> +    OVN version X.Y has been explicitly tested against
> +
> +    - OVS version A.(B-3).0 - A.(B-3).4
> +    - OVS version A.(B-2).0 - A.(B-2).2
> +    - OVS version A.(B-1).0 - A.(B-1).2
> +    - OVS version A.B.0 - A.B.C
> +    - OVS master A.B.90
> +
> +    OVN version X.Y has not been tested against OVS versions prior to
A.(B-3).0,
> +    but it is expected to be able to run as far back as OVS version
A.(B-6).0.
> +
> +    OVN version X.Y is not runtime compatible with versions prior to
A.(B-6).0.

Better to be: "... with OVS versions prior to ..."

> +
> +OVN master (2.12.90)
> +--------------------
> +
> +OVN master is 100% feature compatible with OVS versions 2.12.0 and
higher.
> +
> +OVN master (version 2.12.90) has been explicitly tested against
> +
> +- OVS 2.12.0
> +- OVS master (2.12.90)
> +
> +OVN master is not compatible with versions of OVS prior to 2.12.0.
> --
> 2.14.5
>
> _______________________________________________
> dev mailing list
> dev@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev