% =============================================================================
% 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$
% =============================================================================

\InternalOnly{
\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 committee}
\label{sec:editorial_board}
}

\ExternalOnly{
\chapter{Editorial Committee}
}
\ccIndexMainItemBegin{editorial committee}


The editorial committee 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 and implementations should be submitted to the 
editorial committee for approval.  This can be done by sending mail to 
the \ccAnchor{mailto:editor@cgal.org}{committee}
\lcTex{(\texttt{editor@cgal.org})} indicating
where the (PostScript) documentation and code can be found.  After
some reasonable amount of time, you should receive feedback from 
the committee about the specification and what, if anything, needs to
be changed. The usual procedure is that someone from the committee is
assigned to be (or volunteers to be) the primary reviewer and sends 
comments on the submitted package to the committee and to the authors of
the package.  Discussion then proceeds among the committee members and the
authors until a consensus is reached about how the package should be
modified before being accepted.  When the package has been modified,
the authors should again notify the editorial committee to let them
know what has changed so a decision about acceptance of the package
can be taken.  

\InternalOnly{
The discussion of specific packages are logged on the 
\ccAnchor{http://www.cgal.org/Members/Editorial/}{Editorial Committee web page}%
\lcTex{ (\path|http://www.cgal.org/Members/Editorial|)}.  Reading the 
feedback given on other packages can be quite instructive as a means of
learning what the editorial committee is looking for.
}

One should write a specification for a new package
\InternalOnly{(Chapter~\ref{chap:specification})}
and submit it to the editorial committee 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 committee.
However, since it can take some time for the committee to process
submissions, packages that are to become part of the library 
(as opposed to being listed as 
\ccAnchor{http://www.cgal.org/CEP/requirements.html}{\cgal\ Extension Packages})
can be submitted 
\InternalOnly{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 committee will packages be included in new
public releases and then only if they pass the test suite, of course.

The current members of the editorial committee are:
\begin{center}
\begin{tabular}{p{5cm}p{5cm}}
Andreas Fabri (chair)  & Bernd G\"artner  \\
Susan Hert             & Shai Hirsch  \\
Michael Hoffmann       & Lutz Kettner  \\
Dmitrii Pasechnik      & Sylvain Pion  \\
Remco Veltkamp         & Mariette Yvinec 
\end{tabular}
\end{center}
\ccIndexMainItemEnd{editorial committee}

\InternalOnly{
\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}.   

With the advent of the CVS server, the submission of packages has become
quite simple.  One need only 
\begin{itemize}
   \item[(a)] put your package on the CVS server (Chapter~\ref{chap:cvs})
   \item[(b)] go to the working directory of the package and run the script 
              \texttt{cgal\_submit} (Section~\ref{sec:cgal_submit}).
\end{itemize}
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. 

Within 15 minutes the maintainers of the package (those listed in the file
\texttt{maintainer}) will receive a confirmation of the
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@cs.uu.nl} (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@cs.uu.nl} to add the package to the internal 
releases. In a perfectly bureaucratic world, the editorial committee 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. It checks if any files
in the package have the same case-insensitive name as a file in some other
package.  Moreover, it is picky about the files
\ccAnchor{example/version}{\texttt{version}} and \ccAnchor{example/maintainer}{\texttt{maintainer}},
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 submitted file must obey the naming convention mentioned above, 
      otherwise the submission is rejected. 

\item The submitted package must not contain any file whose name is the same
      as a file in some other submitted package, 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.

\item The package must contain a valid \ccAnchor{example/maintainer}{maintainer
      file}.\index{maintainer file@{\tt maintainer} file}

\item It may be impossible to get the package from the CVS 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 committee before submitting
         packages for internal releases.
   \item Obey the directory structure outlined in Chapter~\ref{chap:directory_structure}.
\end{itemize}

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


