# HG changeset patch # User Rob Hoes 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 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}