# HG changeset patch
# User Rob Hoes <rob.hoes@xxxxxxxxxx>
Updated API evolution document
This document is meant to describe how the elements of the XenAPI may evolve
over time, and provide compatibility guidelines. This is only a proposal and is
still incomplete; we need some discussion about it, especially to establish
what sort of compatibility guarantees we can give.
Signed-off-by: Rob Hoes <rob.hoes@xxxxxxxxxx>
diff -r 60efa32ed31d docs/evolution/Makefile
--- a/docs/evolution/Makefile
+++ b/docs/evolution/Makefile
@@ -1,4 +1,11 @@
-default:
+default: figures
pdflatex main.tex
pdflatex main.tex
+# The following depends on graphviz.
+# To install graphviz, download the graphviz-rhel.repo file and save it
+# (as root) in /etc/yum.repos.d/. Then do "yum install graphviz".
+
+figures:
+ dot -Tpdf evolution.dot -o evolution.pdf
+
diff -r 60efa32ed31d docs/evolution/evolution.dot
--- /dev/null
+++ b/docs/evolution/evolution.dot
@@ -0,0 +1,8 @@
+digraph g {
+ graph [rankdir="LR"];
+ Prototype -> Published [label="1"];
+ Published -> Published [label="2, 3"];
+ Published -> Deprecated [label="4"];
+ Deprecated -> Removed [label="5"];
+}
+
diff -r 60efa32ed31d docs/evolution/globals.tex
--- a/docs/evolution/globals.tex
+++ b/docs/evolution/globals.tex
@@ -6,7 +6,7 @@
\newcommand{\doctitle}{Evolving the XenAPI}
%% Document date
-\newcommand{\datestring}{5th April 2010}
+\newcommand{\datestring}{7th May 2010}
\newcommand{\releasestatement}{Comments are welcome!}
@@ -15,7 +15,8 @@
%% Document authors
\newcommand{\docauthors}{
-David Scott: & {\tt dave.scott@xxxxxxxxxxxxx}}
+%David Scott: & {\tt dave.scott@xxxxxxxxxxxxx}
+}
\newcommand{\legalnotice}{Copyright \copyright{} 2010 Citrix, Inc.\\ \\
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.2 or any later
diff -r 60efa32ed31d docs/evolution/main.tex
--- a/docs/evolution/main.tex
+++ b/docs/evolution/main.tex
@@ -1,14 +1,16 @@
%
-\documentclass{article}
+\documentclass[a4paper]{article}
\usepackage{a4wide}
-\usepackage{graphics}
+\usepackage{graphicx}
\usepackage{longtable}
\usepackage{fancyhdr}
\usepackage{url}
+\usepackage{comment}
\newcommand{\eqdef}{\stackrel{def}{=}}
+\newcommand{\Fig}[1]{Figure~\ref{#1}}
\setlength\topskip{0cm}
\setlength\topmargin{0cm}
@@ -30,7 +32,7 @@
The goals of XenAPI evolution are:
\begin{itemize}
-\item to allow bugs to be fixed efficiently\footnote{Some would consider even
a bugfix to be a semantic change which breaks backwards compatability -- what
if someone is relying on the buggy behaviour?};
+\item to allow bugs to be fixed efficiently\footnote{Some would consider even
a bugfix to be a semantic change which breaks backwards compatibility -- what
if someone is relying on the buggy behaviour?};
\item to allow new, innovative features to be added easily;
\item to keep old, unmodified clients working as much as possible; and
\item where backwards-incompatible changes are to be made, publish this
information early to enable affected parties to give timely feedback.
@@ -39,6 +41,7 @@
\section{Background}
In this document, the term ``XenAPI'' refers to the XMLRPC-derived wire
protocol used by xapi. The XenAPI has ``objects'' which each have ``fields''
and ``messages''. The XenAPI is described in detail elsewhere.
+\begin{comment}
\section{Deprecation policy v1}
\begin{enumerate}
@@ -66,6 +69,63 @@
\item Perhaps we should guarantee fields and messages should live for some
period of wallclock time rather than talk about major releases?
\end{itemize}
+\end{comment}
+
+\section{XenAPI Lifecycle}
+
+\begin{figure}[t]
+ \centering
+ \includegraphics[width=.9\linewidth]{evolution}
+ \caption{API lifecycle states.}
+ \label{fig:states}
+\end{figure}
+
+Each element of the XenAPI (objects, messages and fields) follows the
lifecycle shown in \Fig{fig:states} (inspired by~\cite{symbian}). When an
element is newly created and being still in development, it is in the
\textit{Prototype} state. Elements in this state may be stubs: the interface is
there and can be used by clients for prototyping their new features, but the
actual implementation is not yet ready.
+
+When the element subsequently becomes ready for use (the stub is replaced by a
real implementation), it transitions to the \textit{Published} state. This is
the only state in which the object, message or field should be used. From this
point onwards, the element needs to have clearly defined semantics that are
available for reference in the XenAPI documentation.
+
+If the XenAPI element becomes \textit{Deprecated}, it will still function as
it did before, but its use is discouraged. The final stage of the lifecycle is
the \textit{Removed} state, in which the element is not available anymore.\\
+
+The numbered state changes in \Fig{fig:states} have the following meaning:
+\begin{enumerate}
+\item Publish: declare that the XenAPI element is ready for people to use.
+\item Extend: a \emph{backwards-compatible} extension of the XenAPI, for
example an additional parameter in a message with an appropriate default value.
If the API is used as before, it still has the same effect.
+\item Change: a \emph{backwards-incompatible} change. That is, the message now
behaves differently, or the field has different semantics. Such changes are
discouraged and should only be considered in special cases (always consider
whether deprecation is a better solution). The use of a message can for example
be restricted for security or efficiency reasons, or the behaviour can be
changed simply to fix a bug.
+\item Deprecate: declare that the use of this XenAPI element should be avoided
from now on. Reasons for doing this include: the element is redundant (it
duplicates functionality elsewhere), it is inconsistent with other parts of the
XenAPI, it is insecure or inefficient (for examples of deprecation policies of
other projects, see~\cite{symbian,sun,eclipse,oval}).
+\item Remove: the element is taken out of the public API and can no longer be
used.
+\end{enumerate}
+
+Each lifecycle transition must be accompanied by an explanation describing the
change and the reason for the change. This message should be enough to
understand the semantics of the XenAPI element after the change, and in the
case of backwards-incompatible changes or deprecation, it should give
directions about how to modify a client to deal with the change (for example,
how to avoid using the a deprecated field or message).
+
+\section{Releases}
+
+Every release must be accompanied by \emph{release notes} listing all objects,
fields and messages that are newly prototyped, published, extended, changed,
deprecated or removed in the release. Each item should have an explanation as
implied above, documenting the new or changed XenAPI element. The release
notes for every release shall be prominently displayed in the XenAPI HTML
documentation~\cite{apidoc}.\\
+
+{\em
+Discussion needed: What sort of compatibility guarantees can we give? Options:
+\begin{itemize}
+\item No backwards compatible changes are allowed, and deprecated elements
will be supported for at least one more release after the release they were
declared as deprecated. Rather than making a backwards-incompatible change, new
behaviour should be implemented under a new name. The advantage is that it is
clear, and friendly to users. But is does imply more overhead, and probably
less elegant and less efficient code. Especially for really small, minor
changes, the overhead may be too much.
+\item Publish backwards-incompatible changes and deprecated elements, as well
as new prototypes, early, e.g.\ a few months before a release.
Backwards-incompatible changes are allowed, but should be carefully considered
and only done if there is really no other option.
+\item Publish release notes at the time of the release. Before that, all
changes can be found in the (unstable) XCP branch anyway. (VMWare, for example,
seem to just publish release notes~\cite{vmware}.)
+\item ...?
+\end{itemize}
+}
+
+\section{Documentation}
+
+The XenAPI documentation will contain its complete lifecycle history for each
XenAPI element. Only the elements described in the documentation are
``official'' and supported.\\
+
+Each object, message and field in \texttt{datamodel.ml} will have lifecycle
metadata attached to it, which is a list of transitions (transition type *
release * explanation string) as described above. Release notes are
automatically generated from this data.
+
+
+\begin{thebibliography}{}
+\bibitem{symbian}
\url{http://developer.symbian.org/wiki/index.php/Public_API_Change_Control_Process}
+\bibitem{sun}
\url{http://java.sun.com/j2se/1.4.2/docs/guide/misc/deprecation/deprecation.html}
+\bibitem{eclipse}
\url{http://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy}
+\bibitem{oval} \url{http://oval.mitre.org/language/about/deprecation.html}
+\bibitem{vmware}
\url{http://www.vmware.com/support/developer/vc-sdk/vsdk-4_0_20090507-releasenotes.html}
+\bibitem{apidoc} \url{http://www.xen.org/files/XenCloud/ocamldoc/apidoc.html}
+\end{thebibliography}
\include{fdl}
api-evolution
Description: Text document
_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api
|
Home