mirror of https://github.com/CGAL/cgal
220 lines
9.5 KiB
TeX
220 lines
9.5 KiB
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$
|
|
% =============================================================================
|
|
|
|
\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 & Susan Hert \\
|
|
Shai Hirsch & Michael Hoffmann \\
|
|
Lutz Kettner & Monique Teillaud \\
|
|
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}
|
|
}
|
|
|
|
|