[ovs-dev] [RFC ovn] Document process for compatibility between OVS and OVN.
Mark Michelson
mmichels at redhat.com
Tue Aug 6 18:41:21 UTC 2019
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.
Note that the document currently makes reference to some non-existent
items. For instance, it refers to an ovs-compat directory in the OVN
project. Also, it refers to some macros for testing the OVS version.
These will be added in a future commit if the process documented here is
approved.
I'm submitting this as an RFC, since I imagine there are some details I
have not thought about, and there will also be some great suggestions
from others on this matter.
Signed-off-by: Mark Michelson <mmichels at redhat.com>
---
Documentation/automake.mk | 1 +
Documentation/internals/contributing/index.rst | 1 +
.../contributing/ovs-ovn-compatibility.rst | 165 +++++++++++++++++++++
3 files changed, 167 insertions(+)
create mode 100644 Documentation/internals/contributing/ovs-ovn-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..4f8ea754a
--- /dev/null
+++ b/Documentation/internals/contributing/ovs-ovn-compatibility.rst
@@ -0,0 +1,165 @@
+..
+ Copyright (c) 2019 Nicira, 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
+===============================
+
+OVN has split from OVS. Prior to this split, there was no issue with
+compatibility. All code changes happened at the same time and in the same repo.
+New releases contained the latest OVS and OVN changes. But now these assumptions
+are no longer valid, and so care must be taken to maintain compatibility.
+
+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.
+
+Mitigation
+~~~~~~~~~~
+
+We combat the incompatibility problem by maintaining an ovs-compat directory in
+OVN. Within that ovs-compat directory are subdirectories representing releases
+of OVS. Within these subdirectories are files with functions that have been
+added to OVS that OVN relies upon.
+
+::
+
+ ovs-compat/
+ ovs-2.13/
+ ovs-2.14/
+
+For instance, ``ovs-compat/ovs-2.13`` contains functions that OVN relies on that
+were added during the development cycle for OVS 2.13. ``ovs-compat/ovs-2.14``
+contains functions that OVN reles on that were added during the development
+cycle of OVS 2.14.
+
+At configure time, OVN determines the version of OVS that is installed on the
+system. It then adds subdirectories in ovs-compat for all OVS versions later
+than the version installed, going in reverse chronological order. So if OVS 2.12
+were installed on the system, then ``ovs-compat/ovs-2.14`` and
+``ovs-compat/ovs-2.13`` would be prepended to the include path in that order.
+
+The header files are structured to mimic that of OVS. So if OVS has
+``include/openvswitch/foo.h``, then if we need to make a compatability update
+for this header for OVS 2.14, then OVN would have an
+``ovs-compat/ovs-2.14/include/openvswitch/foo.h`` file. The top of the file
+would look like the following:
+
+::
+
+ // Include previous compatibility fixes.
+ #if OVS_INSTALLED_VERSION() < OVS_VERSION(2, 13)
+ #include ovs-compat/ovs-2.13/include/openvswitch/foo.h
+ #endif
+ // Include the openvswitch header file
+ #include <openvswitch/foo.h>
+
+
+From there, the header file will contain prototypes for functions that OVS has
+added for version 2.14 that OVN relies on. OVN will provide definitions of these
+functions in a separate source file in ``ovs-compat/ovs-2.14``.
+
+Developer Instructions
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following is the process that OVN developers should use when making a change
+to both OVS and OVN.
+
+1. Determine if the change absolutely needs to be made to OVS. If the change to
+OVS can be avoided, please attempt that instead.
+2. If the change to OVS is necessary, then submit the change to upstream OVS.
+See the change through until it is merged.
+3. Add the function to the release subdirectory representing the OVS version
+currently under development. Submit this patch as the first in your patchset to
+OVN.
+4. Apply the rest of your OVN changes as you see fit.
+
+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
+updage 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 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.
+ 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. 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 with older versions of OVS
+- Earthshatteringly large changes in OVS (e.g. no longer using OpenFlow or the
+ OVSDB).
+- 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 document it. Attempting to compile OVN against an
+unsupported version of OVS will result in an error at configure time.
--
2.14.5
More information about the dev
mailing list