[PATCH 09/17] docs: Convert 'support' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 docs/meson.build     |   2 +-
 docs/support.html.in | 258 -------------------------------------------
 docs/support.rst     | 207 ++++++++++++++++++++++++++++++++++
 3 files changed, 208 insertions(+), 259 deletions(-)
 delete mode 100644 docs/support.html.in
 create mode 100644 docs/support.rst

diff --git a/docs/meson.build b/docs/meson.build
index d0c1217351..b3432cc6f6 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -63,7 +63,6 @@ docs_html_in_files = [
   'remote',
   'securityprocess',
   'storage',
-  'support',
   'testapi',
   'testsuites',
   'testtck',
@@ -112,6 +111,7 @@ docs_rst_files = [
   'strategy',
   'styleguide',
   'submitting-patches',
+  'support',
 ]

 # list of web targets to build for docs/web rule
diff --git a/docs/support.html.in b/docs/support.html.in
deleted file mode 100644
index 38f2f906e0..0000000000
--- a/docs/support.html.in
+++ /dev/null
@@ -1,258 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml";>
-  <body>
-    <h1>Support guarantees</h1>
-
-    <ul id="toc"></ul>
-
-    <p>
-      This document will outline the support status / guarantees around the
-      very interfaces that libvirt exposes to applications and/or system
-      administrators. The intent is to help users understand what features they
-      can rely upon in particular scenarios, and whether they are likely to
-      suffer disruption during upgrades.
-    </p>
-
-    <h2><a id="publicAPI">Primary public API</a></h2>
-
-    <p>
-      The main public API provided by <code>libvirt.so</code> and described
-      in <code>libvirt/libvirt.h</code> exposes the primary hypervisor
-      agnostic management interface of libvirt. This API has the strongest
-      guarantee of any part of libvirt with a promise to keep backwards
-      compatibility forever. Specific details are as follows:
-    </p>
-
-    <dl>
-      <dt>Functions</dt>
-      <dd>Functions will never be removed from the public API, and will
-        never have parameters added, removed or changed in their signature.
-        IOW they will be ABI compatible forever. The semantics implied by
-        a specific set of parameters passed to the function will remain
-        unchanged. Where a parameter accepts a bitset of feature flags, or
-        an enumerated value, further flags / enum values may be supported
-        in the future. Where a parameter accepts one of a set of related
-        constants, further constants may be supported in the future.
-      </dd>
-      <dt>Struct types</dt>
-      <dd>Once defined in a release, struct definitions will never have any
-        fields add, removed or changed in any way. Their size and layout is
-        fixed forever. If a struct name starts with an underscore, it is
-        considered acceptable to rename it. Applications should thus always
-        use the corresponding typedef in preference to the struct name.
-      </dd>
-      <dt>Union types</dt>
-      <dd>Once defined in a release, union definitions will never have any
-        existing fields removed or changed. New union choices may be added,
-        provided that they don't change the size of the existing union
-        definition. If a struct name starts with an underscore, it is
-        considered acceptable to rename it. Applications should thus always
-        use the corresponding typedef in preference to the struct name.
-      </dd>
-      <dt>Type definitions</dt>
-      <dd>Most custom data types used in the APIs have corresponding typedefs
-        provided for their stable names. The typedefs should always be used
-        in preference to the underlying data type name, as the latter are not
-        guaranteed to be stable.
-      </dd>
-      <dt>Enumerations</dt>
-      <dd>Once defined in a release, existing enumeration values will never
-        be removed or renamed. New enumeration values may be introduced at
-        any time. Every enumeration will have a '_LAST' value which indicates
-        the current highest enumeration value, which may increase with new
-        releases. If an enumeration name starts with an underscore, it is
-        considered acceptable to rename it. Applications should thus always
-        use the corresponding typedef in preference to the enum name.
-      </dd>
-      <dt>Constants</dt>
-      <dd>Once defined in a release, existing constants will never be removed
-        or have their value changed. Most constants are grouped into related
-        sets, and within each set, new constants may be introduced. APIs which
-        use the constants may thus accept or return new constant values over
-        time.
-      </dd>
-      <dt>Symbol versions</dt>
-      <dd>Where the platform library format permits, APIs defined in libvirt.so
-        library will have version information associated. Each API will be
-        tagged with the version in which it was introduced, and this won't
-        be changed thereafter.
-      </dd>
-    </dl>
-
-    <h2><a id="hvAPI">Hypervisor specific APIs</a></h2>
-
-    <p>
-      A number of hypervisor drivers provide additional libraries with hypervisor
-      specific APIs, extending the core libvirt API. These add-on libraries follow
-      the same general principles described above, however, they are <strong>not</strong>
-      guaranteed to be preserved forever. The project reserves the right to remove
-      hypervisor specific APIs in any new release, or to change their semantics.
-      That said the project will endeavour to maintain API compatibility for as long
-      as is practical.
-    </p>
-
-    <p>
-      Use of some hypervisor specific APIs may result in the running guest being
-      marked as "tainted" if the API is at risk of having unexpected interactions
-      with normal libvirt operations. An application which chooses to make use of
-      hypervisor specific APIs should validate their operation with each new release
-      of libvirt and each new release of the underlying hypervisor. The semantics
-      may change in unexpected ways, or have unforeseen interactions with libvirt's
-      operation.
-    </p>
-
-    <h2><a id="apierrors">Error reporting</a></h2>
-
-    <p>
-      Most API calls are subject to failure and so will report error codes and
-      messages. Libvirt defines error codes for a wide variety of scenarios, some
-      represent very specific problems, while others are general purpose for
-      broad classes of problem. Over time the error codes reported are liable
-      to change, usually changing from a generic error to a more specific error.
-      Thus applications should be careful about checking for &amp; taking action
-      upon specific error codes, as their behaviour may change across releases.
-    </p>
-
-    <h2><a id="xmlschema">XML schemas</a></h2>
-
-    <p>
-      The main objects exposed via the primary libvirt public API are usually
-      configured via XML documents following specific schemas. The XML schemas
-      are considered to be stable formats, whose compatibility will be maintained
-      forever. Specific details are as follows:
-    </p>
-
-    <dl>
-      <dt>Attributes</dt>
-      <dd>Attributes defined on an XML element will never be removed or
-        renamed. New attributes may be defined. If the set of valid values
-        for an attribute are determined by an enumeration, the permitted
-        values will never be removed or renamed, only new values defined.
-        None the less, specific hypervisors may reject usage of certain
-        values according to their feature set.
-      </dd>
-      <dt>Elements</dt>
-      <dd>Elements defined will never be removed or renamed. New child
-        elements may be defined at any time. In places where only a
-        single instance of a named XML element is used, future versions
-        may be extended to permit multiple instances of the named XML
-        element to be used. An element which currently has no content
-        may later gain child elements.
-      </dd>
-    </dl>
-
-    <p>
-      Some hypervisor drivers may choose to allow use of hypervisor specific
-      extensions to the XML documents. These extensions will always be
-      contained within a hypervisor specific XML namespace. There is generally
-      no guarantee of long term support for the hypervisor specific extensions
-      across releases, though the project will endeavour to preserve them as
-      long as is possible. Applications choosing to use hypervisor specific
-      extensions should validate their operation against new libvirt or
-      hypervisor releases.
-    </p>
-
-    <h2><a id="configfiles">Configuration files</a></h2>
-
-    <p>
-      A number of programs / daemons provided libvirt rely on host filesystem
-      configuration files. These configuration files are accompanied by augeas
-      lens for easy manipulation by applications. There is in general no
-      guarantee that parameters available in the configuration file will be
-      preserved across releases, though the project will endeavour to preserve
-      them as long as is possible. If a configuration option is dropped from
-      the file, the augeas lens will retain the ability to read that configuration
-      parameter, so that it is able to read &amp; update historically modified
-      files.
-
-      The default configuration files ship with all parameters commented out
-      such that a deployment relies on the built-in defaults of the application
-      in question. There is no guarantee that the defaults will remain the same
-      across releases. A deployment that expects a particular value for a
-      configuration parameter should consider defining it explicitly, instead
-      of relying on the defaults.
-    </p>
-
-    <h2><a id="hvdrivers">Hypervisor drivers</a></h2>
-
-    <p>
-      The libvirt project provides support for a wide variety of hypervisor
-      drivers. These drivers target certain versions of the hypervisor's
-      underlying management APIs. In general libvirt aims to work with any
-      hypervisor version that is still broadly supported by its vendor.
-      When a vendor discontinues support for a particular hypervisor
-      version it will be dropped by libvirt. Libvirt may choose to drop
-      support for a particular hypervisor version prior to the vendor
-      ending support, if it deems that the likely usage is too small to
-      justify the ongoing maintenance cost.
-    </p>
-    <p>
-      Each hypervisor release will implement a distinct subset of features
-      that can be expressed in the libvirt APIs and XML formats. While the
-      XML schema syntax will be stable across releases, libvirt is unable
-      to promise that it will always be able to support usage of the same
-      features across hypervisor releases. Where a hypervisor changes the
-      way a feature is implemented, the project will endeavour to adapt
-      to the new implementation to provide the same semantics. In cases
-      where the feature is discontinued by the hypervisor, libvirt will
-      return an error indicating it is not supported. Likewise libvirt will
-      make reasonable efforts to keep API calls working across hypervisor
-      releases even if the underlying implementation changes. In cases where
-      this is impossible, a suitable error will be reported. The list of
-      APIs which have implementations <a href="hvsupport.html">is detailed separately</a>.
-    </p>
-
-    <h2><a id="rpcproto">RPC protocol</a></h2>
-
-    <p>
-      For some hypervisor drivers, the libvirt.so library communicates with
-      separate libvirt daemons to perform work. This communication takes
-      place over a binary RPC protocol defined by libvirt. The protocol uses
-      the XDR format for data encoding, and the message packet format is
-      defined in libvirt source code.
-    </p>
-    <p>
-      Applications are encouraged to use the primary libvirt.so library which
-      transparently talks to the daemons, so that they are not exposed to the
-      hypervisor driver specific details. None the less, the RPC protocol
-      associated with the libvirtd is considered to be a long term stable ABI.
-      It will only ever have new messages added to it, existing messages will
-      not be removed, nor have their contents changed. Thus if an application
-      does wish to provide its own client side implementation of the RPC
-      protocol this is supported, with the caveat that the application will
-      loose the ability to work with certain hypervisors libvirt supports.
-      The project reserves the right to define new authentication and encryption
-      options for the protocol, and the defaults used in this area may change
-      over time. This is particularly true of the TLS ciphers permitted. Thus
-      applications choosing to implement the RPC protocol must be prepared to
-      track support for new security options. If defaults are changed, however,
-      it will generally be possible to reconfigure the daemon to use the old
-      defaults, albeit with possible implications for system security.
-    </p>
-
-    <p>
-      Other daemons besides, libvirtd, also use the same RPC protocol, but
-      with different message types defined. These RPC protocols are all
-      considered to be private implementations that are liable to change
-      at any time. Applications must not attempt to talk to these other
-      daemons directly.
-    </p>
-
-    <h2><a id="virsh">virsh client</a></h2>
-
-    <p>
-      The virsh program provides a simple client to interact with an arbitrary libvirt
-      hypervisor connection. Since it uses the primary public API of libvirt, it should
-      generally inherit the guarantees associated with that API, and with the hypervisor
-      driver. The commands that virsh exposes, and the arguments they accept are all
-      considered to be long term stable. Existing commands and arguments will not be
-      removed or renamed. New commands and arguments may be added in new releases.
-      The text output format produced by virsh commands is not generally guaranteed to
-      be stable if it contains compound data (eg formatted tables or lists). Commands
-      which output single data items (ie an object name, or an XML document), can be
-      treated as having stable format.
-    </p>
-
-  </body>
-</html>
diff --git a/docs/support.rst b/docs/support.rst
new file mode 100644
index 0000000000..f285f63c55
--- /dev/null
+++ b/docs/support.rst
@@ -0,0 +1,207 @@
+==================
+Support guarantees
+==================
+
+.. contents::
+
+This document will outline the support status / guarantees around the very
+interfaces that libvirt exposes to applications and/or system administrators.
+The intent is to help users understand what features they can rely upon in
+particular scenarios, and whether they are likely to suffer disruption during
+upgrades.
+
+Primary public API
+------------------
+
+The main public API provided by ``libvirt.so`` and described in
+``libvirt/libvirt.h`` exposes the primary hypervisor agnostic management
+interface of libvirt. This API has the strongest guarantee of any part of
+libvirt with a promise to keep backwards compatibility forever. Specific details
+are as follows:
+
+Functions
+   Functions will never be removed from the public API, and will never have
+   parameters added, removed or changed in their signature. IOW they will be ABI
+   compatible forever. The semantics implied by a specific set of parameters
+   passed to the function will remain unchanged. Where a parameter accepts a
+   bitset of feature flags, or an enumerated value, further flags / enum values
+   may be supported in the future. Where a parameter accepts one of a set of
+   related constants, further constants may be supported in the future.
+Struct types
+   Once defined in a release, struct definitions will never have any fields add,
+   removed or changed in any way. Their size and layout is fixed forever. If a
+   struct name starts with an underscore, it is considered acceptable to rename
+   it. Applications should thus always use the corresponding typedef in
+   preference to the struct name.
+Union types
+   Once defined in a release, union definitions will never have any existing
+   fields removed or changed. New union choices may be added, provided that they
+   don't change the size of the existing union definition. If a struct name
+   starts with an underscore, it is considered acceptable to rename it.
+   Applications should thus always use the corresponding typedef in preference
+   to the struct name.
+Type definitions
+   Most custom data types used in the APIs have corresponding typedefs provided
+   for their stable names. The typedefs should always be used in preference to
+   the underlying data type name, as the latter are not guaranteed to be stable.
+Enumerations
+   Once defined in a release, existing enumeration values will never be removed
+   or renamed. New enumeration values may be introduced at any time. Every
+   enumeration will have a '_LAST' value which indicates the current highest
+   enumeration value, which may increase with new releases. If an enumeration
+   name starts with an underscore, it is considered acceptable to rename it.
+   Applications should thus always use the corresponding typedef in preference
+   to the enum name.
+Constants
+   Once defined in a release, existing constants will never be removed or have
+   their value changed. Most constants are grouped into related sets, and within
+   each set, new constants may be introduced. APIs which use the constants may
+   thus accept or return new constant values over time.
+Symbol versions
+   Where the platform library format permits, APIs defined in libvirt.so library
+   will have version information associated. Each API will be tagged with the
+   version in which it was introduced, and this won't be changed thereafter.
+
+Hypervisor specific APIs
+------------------------
+
+A number of hypervisor drivers provide additional libraries with hypervisor
+specific APIs, extending the core libvirt API. These add-on libraries follow the
+same general principles described above, however, they are **not** guaranteed to
+be preserved forever. The project reserves the right to remove hypervisor
+specific APIs in any new release, or to change their semantics. That said the
+project will endeavour to maintain API compatibility for as long as is
+practical.
+
+Use of some hypervisor specific APIs may result in the running guest being
+marked as "tainted" if the API is at risk of having unexpected interactions with
+normal libvirt operations. An application which chooses to make use of
+hypervisor specific APIs should validate their operation with each new release
+of libvirt and each new release of the underlying hypervisor. The semantics may
+change in unexpected ways, or have unforeseen interactions with libvirt's
+operation.
+
+Error reporting
+---------------
+
+Most API calls are subject to failure and so will report error codes and
+messages. Libvirt defines error codes for a wide variety of scenarios, some
+represent very specific problems, while others are general purpose for broad
+classes of problem. Over time the error codes reported are liable to change,
+usually changing from a generic error to a more specific error. Thus
+applications should be careful about checking for & taking action upon specific
+error codes, as their behaviour may change across releases.
+
+XML schemas
+-----------
+
+The main objects exposed via the primary libvirt public API are usually
+configured via XML documents following specific schemas. The XML schemas are
+considered to be stable formats, whose compatibility will be maintained forever.
+Specific details are as follows:
+
+Attributes
+   Attributes defined on an XML element will never be removed or renamed. New
+   attributes may be defined. If the set of valid values for an attribute are
+   determined by an enumeration, the permitted values will never be removed or
+   renamed, only new values defined. None the less, specific hypervisors may
+   reject usage of certain values according to their feature set.
+Elements
+   Elements defined will never be removed or renamed. New child elements may be
+   defined at any time. In places where only a single instance of a named XML
+   element is used, future versions may be extended to permit multiple instances
+   of the named XML element to be used. An element which currently has no
+   content may later gain child elements.
+
+Some hypervisor drivers may choose to allow use of hypervisor specific
+extensions to the XML documents. These extensions will always be contained
+within a hypervisor specific XML namespace. There is generally no guarantee of
+long term support for the hypervisor specific extensions across releases, though
+the project will endeavour to preserve them as long as is possible. Applications
+choosing to use hypervisor specific extensions should validate their operation
+against new libvirt or hypervisor releases.
+
+Configuration files
+-------------------
+
+A number of programs / daemons provided libvirt rely on host filesystem
+configuration files. These configuration files are accompanied by augeas lens
+for easy manipulation by applications. There is in general no guarantee that
+parameters available in the configuration file will be preserved across
+releases, though the project will endeavour to preserve them as long as is
+possible. If a configuration option is dropped from the file, the augeas lens
+will retain the ability to read that configuration parameter, so that it is able
+to read & update historically modified files. The default configuration files
+ship with all parameters commented out such that a deployment relies on the
+built-in defaults of the application in question. There is no guarantee that the
+defaults will remain the same across releases. A deployment that expects a
+particular value for a configuration parameter should consider defining it
+explicitly, instead of relying on the defaults.
+
+Hypervisor drivers
+------------------
+
+The libvirt project provides support for a wide variety of hypervisor drivers.
+These drivers target certain versions of the hypervisor's underlying management
+APIs. In general libvirt aims to work with any hypervisor version that is still
+broadly supported by its vendor. When a vendor discontinues support for a
+particular hypervisor version it will be dropped by libvirt. Libvirt may choose
+to drop support for a particular hypervisor version prior to the vendor ending
+support, if it deems that the likely usage is too small to justify the ongoing
+maintenance cost.
+
+Each hypervisor release will implement a distinct subset of features that can be
+expressed in the libvirt APIs and XML formats. While the XML schema syntax will
+be stable across releases, libvirt is unable to promise that it will always be
+able to support usage of the same features across hypervisor releases. Where a
+hypervisor changes the way a feature is implemented, the project will endeavour
+to adapt to the new implementation to provide the same semantics. In cases where
+the feature is discontinued by the hypervisor, libvirt will return an error
+indicating it is not supported. Likewise libvirt will make reasonable efforts to
+keep API calls working across hypervisor releases even if the underlying
+implementation changes. In cases where this is impossible, a suitable error will
+be reported. The list of APIs which have implementations `is detailed
+separately <hvsupport.html>`__.
+
+RPC protocol
+------------
+
+For some hypervisor drivers, the libvirt.so library communicates with separate
+libvirt daemons to perform work. This communication takes place over a binary
+RPC protocol defined by libvirt. The protocol uses the XDR format for data
+encoding, and the message packet format is defined in libvirt source code.
+
+Applications are encouraged to use the primary libvirt.so library which
+transparently talks to the daemons, so that they are not exposed to the
+hypervisor driver specific details. None the less, the RPC protocol associated
+with the libvirtd is considered to be a long term stable ABI. It will only ever
+have new messages added to it, existing messages will not be removed, nor have
+their contents changed. Thus if an application does wish to provide its own
+client side implementation of the RPC protocol this is supported, with the
+caveat that the application will loose the ability to work with certain
+hypervisors libvirt supports. The project reserves the right to define new
+authentication and encryption options for the protocol, and the defaults used in
+this area may change over time. This is particularly true of the TLS ciphers
+permitted. Thus applications choosing to implement the RPC protocol must be
+prepared to track support for new security options. If defaults are changed,
+however, it will generally be possible to reconfigure the daemon to use the old
+defaults, albeit with possible implications for system security.
+
+Other daemons besides, libvirtd, also use the same RPC protocol, but with
+different message types defined. These RPC protocols are all considered to be
+private implementations that are liable to change at any time. Applications must
+not attempt to talk to these other daemons directly.
+
+virsh client
+------------
+
+The virsh program provides a simple client to interact with an arbitrary libvirt
+hypervisor connection. Since it uses the primary public API of libvirt, it
+should generally inherit the guarantees associated with that API, and with the
+hypervisor driver. The commands that virsh exposes, and the arguments they
+accept are all considered to be long term stable. Existing commands and
+arguments will not be removed or renamed. New commands and arguments may be
+added in new releases. The text output format produced by virsh commands is not
+generally guaranteed to be stable if it contains compound data (eg formatted
+tables or lists). Commands which output single data items (ie an object name, or
+an XML document), can be treated as having stable format.
-- 
2.35.1




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux