[Xen-API] [PATCH] Updated API evolution document

[Rob Hoes <rob.hoes@xxxxxxxxxx>]

# 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}

Attachment: api-evolution
Description: Text document

_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api