cgal/Packages/Developers_manual/submission_process.tex

% =============================================================================
% The CGAL Developers' Manual
% Chapter: Submitting Packages
% -----------------------------------------------------------------------------
% file   : submission_process.tex
% authors: Geert-Jan Giezeman <geert@cs.uu.nl> & Susan Hert <hert@mpi-sb.mpg.de>
% -----------------------------------------------------------------------------
% $Revision$
% $Date$
% =============================================================================

\chapter{Submitting Packages}
\label{chap:submission}
\ccChapterRelease{Chapter Version: 1.0} \\
\ccChapterAuthor{Geert-Jan Giezeman ({\tt geert@cs.uu.nl}) 
\& Susan Hert ({\tt hert@mpi-sb.mpg.de})}

\section{Editorial board}
\label{sec:editorial_board}
\ccIndexMainItemBegin{editorial board}

The Editorial Board is in charge of approving the inclusion of new packages
in the library.  This means that they assure that new contributions
\begin{itemize}
   \item are in keeping with the philosophy of \cgal\ (Chapter~\ref{chap:intro});
   \item are generic and fit seamlessly with other parts of
         the library;
   \item satisfy the coding conventions of \cgal\ (Chapter~\ref{chap:code_format});
   \item carefully and efficiently treat robustness issues
         (Chapter~\ref{chap:robustness});
   \item are designed in a flexible, extensible, and easy-to-use fashion;
   \item and are designed to be technically feasible for the platforms
         supported by \cgal.
\end{itemize}

Software specifications should be submitted to the editorial committee
for approval.  This can be done by sending mail to 
\ccAnchor{mailto:cgal-editor@cs.uu.nl}{\texttt{cgal-editor@cs.uu.nl}}.  After
some reasonable amount of time, you should receive feedback from someone
on the committee about the specification and what, if anything, needs to
be changed.

One should write a specification for a new package
(Chapter~\ref{chap:specification}) and submit it to the editorial board for 
approval before submitting the package for inclusion in the internal
releases (and ideally before implementation of the package).  This
assures that time is not wasted in fixing code that may later be changed
due to the recommendations of the board.
However, since it can take some time for the board to process
submissions, packages that are to become part of the library 
(as opposed to being listed as 
\ccAnchor{http://www.mpi-sb.mpg.de/~hert/CGAL/CEP/requirements.html}{\cgal\ Extension Packages}) can be submitted as detailed in 
Section~\ref{sec:electronic_submission} before approval.
Inclusion in an internal release does not ensure inclusion in a public
release.  Only after approval by the board will packages be included in new
public releases.

The current members of the editorial board are:
\begin{itemize}
   \item Stefan Schirra
   \item Remco Veltkamp
   \item Mariette Yvinec.
\end{itemize}
\ccIndexMainItemEnd{editorial board}


\section{Electronic submission}
\label{sec:electronic_submission}
\ccIndexMainItemBegin{submitting}

Whether you produce library code, demos, documentation or something else,
if you want it to become part of \cgal, you'll have to submit it in the form
of a package.  The directory structure required for a package is described in
Chapter~\ref{chap:directory_structure}.
Here we focus on how to submit a package.

\ccIndexSubitem{naming scheme}{package}
A package has a name, which identifies it.  This name should obey the same
rules as for C identifiers: it consists of letters, digits and underscores and
it does not start with a digit.  Choose a name that is descriptive, yet not
too long (under 25 characters).  If a package deals with objects of a
particular dimension, then use the suffixes \_2, \_3, and \_d, especially if
there exists (or may exist in the future) a package with similar
functionality in different dimensions.  Examples of good package names are
\texttt{Triangulation\_2} for a package dealing with triangulations of points 
in the plane and \texttt{Min\_ellipse\_2}, which contains an algorithm that 
finds the minimal enclosing ellipse of a set of points in the plane. The 
package names \texttt{pm} and \texttt{arr} are a bit too terse.
\texttt{Planar\_map} and \texttt{Arrangement} (or
\texttt{Arrangement\_2}) would have been better.

\ccIndexSubitem{submitting}{file for}
A submission consists of a single compressed file.  The name of this file
must be the name of the package followed by \texttt{.tar.gz} or \texttt{.tgz} 
if the file is made with \texttt{tar} and \texttt{gzip} or followed by 
\texttt{.zip} if the file is made with \texttt{zip}.  This file should 
be put on a WWW server, preferably protected with
the \cgal\ password.\footnote{If there is demand, it is possible to extend
this service to submitting via \texttt{ftp}.} 

When the file is in place, it is time to notify Utrecht that the file
should be fetched.  This is done by sending an email to
\ccAnchor{mailto:cgal-submit@cs.uu.nl}{\texttt{cgal-submit@cs.uu.nl}}.  
The subject of this email must be \texttt{autohandle}.  
The body of the message must contain a line \verb+ submission::+ followed by a
line with the URL. The URL must start on a new line, but may itself be
split over several lines. So, the complete mail could look like 
\begin{verbatim}
  From: Geert-Jan Giezeman <geert@cs.uu.nl>
  To: cgal-submit@cs.uu.nl
  Subject: autohandle

  submission::
  http://www.cs.uu.nl/people/geert/CGAL
  /Minkowski_2.zip
\end{verbatim}
If all goes well, the package is installed and the \ccAnchor{http://www.cs.uu.nl/CGAL/Members/Develop/updates/packages.html}{packages page}
\begin{ccTexOnly} 
(\path|http://www.cs.uu.nl/CGAL/Members/Develop/updates/packages.html|) 
\end{ccTexOnly}
is updated. 
The whole process is done without human intervention, so you should follow
the rules described here precisely.


Within 15 minutes you will receive a confirmation of your
submission.\footnote{The confirmation goes also to the person responsible
for the submission procedure.}  If this is not the case, send a mail to
\texttt{cgal-submit} (with a subject other than \texttt{autohandle}) 
and ask what went
wrong.  The first time you submit a package, the confirmation message will
tell you that the package will not go into internal releases. Usually, you
request \texttt{cgal-submit} to add the package to the internal releases. In a
perfectly bureaucratic world, the editorial committe would be asked if it
is OK to add the package. In practice, that is not done.

The submission process checks your package for several things.  It checks
if your source files contain a valid header (Section~\ref{sec:file_header})
and if the lines are not longer
than 80 characters. Moreover, it is picky about the file 
\ccAnchor{example/version}{\texttt{version}},
which must be part of your package. See Chapter~\ref{chap:directory_structure}
for a precise description of the required format for this file.
\ccIndexMainItemEnd{submitting}


\section{When something goes wrong}
\label{sec:submission_problems}
\ccIndexSubitemBegin{submitting}{problems with}

There are several reasons why a submission may not succeed.
In most cases the confirmation message will state that an error occured. In
some cases, you will not get a confirmation message at all.

The following is a list of reasons why a submission might fail.
\begin{itemize}

\item The sender and the URL where the package is retrieved, should both be 
      on a \cgal\ member site. If this is not the case, the submission will 
      be rejected.  This is done as a security measure.

\item The submitted file must obey the naming convention mentioned above, 
      otherwise the submission is rejected. 

\item The package must contain a valid \ccAnchor{example/version}{version file}.
      The version must be bigger than the previous version and a maintainer
      should be mentioned.\index{version file@{\tt version} file}

\item It may be impossible to get the package from the WWW server. 
      This could be due to server failures, wrong permissions, misspellings
      \etc

\item Some resources may be exhausted in Utrecht (quota problems, usually).

\end{itemize}
\ccIndexSubitemEnd{submitting}{problems with}


\section{Requirements and recommendations}
\label{sec:submission_req_and_rec}

\noindent
Requirements:
\begin{itemize}
   \item Submit specifications to the editorial board before submitting
         packages for internal releases.
   \item Obey the directory structure outlined in Chapter~\ref{chap:directory_structure}.
   \item Format your submission-notification email exactly as detailed above.
\end{itemize}

\noindent
Recommendations:
\begin{itemize}
    \item Wait for approval from the editorial board before submitting packages
          for internal releases.
\end{itemize}