% =============================================================================
% The CGAL Developers' Manual
% Chapter: CVS Server
% -----------------------------------------------------------------------------
% file   : cvs.tex
% authors: Mariette Yvinec, Sylvain Pion <Sylvain.Pion@sophia.inria.fr>
% -----------------------------------------------------------------------------
% $Revision$
% $Date$
% =============================================================================

\chapter{CVS Server}
\label{chap:cvs}
\ccChapterRelease{Chapter Version: 2.0} \\
\ccChapterAuthor{Sylvain Pion ({\tt Sylvain.Pion@sophia.inria.fr})}
\index{CVS server|(}

CVS (Concurrent Versions System) is a popular version control
system that keeps track of the complete history of changes for a set of
source files.  CVS is of great help when several people work on the
same project.

You can find the CVS manual at \path|http://www.cvshome.org/docs/manual/|.
Lots of documentation, including tutorials, can easily be found on the net.

The machine \texttt{cgal.inria.fr} hosts a CVS server for \cgal.
There is read-only access via the web at
\path|http://cgal.inria.fr/cgi-bin/viewcvs.cgi/|.

\section{Structure of the repository}
\label{sec:cvs_structure}
\index{CVS server!directory structure}
\ccIndexSubitem{directory structure}{for CVS server}

The \cgal\ repository, which is backed up daily,
\index{CVS server!backup} 
is organized in the following way:
\begin{itemize}
\item There is one CVS module per \cgal\ package.
\item A CVS module has the same structure as the current \cgal\ packages
      (Chapter~\ref{chap:directory_structure}). 

      As a general rule, try to not put under CVS control any files
      that are automatically generated.
      Note that you can put some files under CVS control that you don't
      want to be included in releases (\textit{e.g.}, literate programming 
      web files).
      You can do that by adding their names in a \texttt{dont\_submit} file
      \index{CVS server!dont_submit file@\texttt{dont\_submit} file}
      (at the top of the module), using the syntax explained in the
      \texttt{tar} manual (see the \texttt{--exclude-from}
      option in the doc at \path|http://www.gnu.org/manual/tar/|).
      By default, the files \texttt{TODO} and \texttt{wrapper.tex} are 
      excluded from submissions.
\end{itemize}

The repository tree has the following structure:

\begin{verbatim}
$CVSROOT/CGAL
           |
           +---- Packages/ 
           |         |
           |         +--- Convex_hull_2/  
           |         |     |
           |         |     |-- maintainer 
           |         |     |
           |         |     |-- changes.txt 
           |         |     |
           |         |     |-- TODO 
           |         |     |
           |         |     +-- include/CGAL/ 
           |         |     |
           |         |     +-- src/ 
           |         |     |
           |         |     +-- doc_tex/ 
           |         |     |
           |         |     +-- test/ 
           |         |     |
           |         |     +--  ... 
           |         |
           |         +--- Number_types/  
           |         |     
           |         +--- Cartesian_kernel/
           |         |     
           |         +--- ...  
           |
           +---- Old_Packages/
                     |     
                     +--- Bops/ 
                     |     
                     +--- ...  
\end{verbatim}


\section{Access to the repository}
\label{sec:cvs_access}
\index{CVS server!access|(}

Here are the access rules:
\begin{itemize}
\item Everybody who has the login and password for \cgal\ members 
      has read access to the \cgal\ repository and there is also
      read-only access for members via the web at 
      \path|http://cgal.inria.fr/cgi-bin/viewcvs.cgi/|.
\item Each package has a set (which can be only one person) of people having
      write access to the corresponding module.  It's up to the maintainer of
      the package to decide who is given write access, and how you should
      coordinate (we may decide something else for the freeze periods).
      The file
      \path|http://cgal.inria.fr/cgi-bin/viewcvs.cgi/Admin/write_access_rights|
      contains the write access lists.
\item Currently, there is no SSH access method, only the less secure pserver
      is working.
\end{itemize}
\index{CVS server!access|)}


\section{How to use it}
\label{sec:cvs_how_to}

\begin{itemize}
\item
    First, you have to login (this basically stores the password in your
    \texttt{.cvspass} file). Type: \\
    \texttt{cvs -d :pserver:login\_name@cgal.inria.fr:/CVSROOT login} \\
    and enter the password corresponding to your \texttt{login\_name} \\
    (\texttt{member1} if you don't have any).
\item
    To get the list of existing modules:
    \texttt{cvs -d :pserver:login\_name@cgal.inria.fr:/CVSROOT co -c}
\item
    To check out a module, say \ccc{Convex\_hull\_2}: \\
    \texttt{cvs -d :pserver:login\_name@cgal.inria.fr:/CVSROOT co
    Convex\_hull\_2}
\item
    Once you have checked out a module, you don't need to specify
    \texttt{-d ...} anymore for the usual commands like \texttt{cvs commit}...
\item
    To obtain write access to a package, you first need a personal login
    name and password.  Send your login name to 
    \ccAnchor{mailto:Sylvain.Pion@sophia.inria.fr}
    {\texttt{Sylvain.Pion@sophia.inria.fr}}, as well as your password,
    encrypted by the Perl script~:
\begin{verbatim}
#!/usr/local/bin/perl
#
# Perl script that computes an encrypted password.
# Taken from the book "Open Source development with CVS" by Karl Fogel.
# Sylvain Pion, 2000.

srand (time());
my $randletter = "(int (rand(26)) + (int (rand(1) + .5) % 2 ? 65 : 97))";
my $salt = sprintf ("%c%c", eval $randletter, eval $randletter);
my $plaintext = shift;
my $crypttext = crypt ($plaintext, $salt);

print "${crypttext}\n";
\end{verbatim}

    and indicate for which packages you need write permission.
\end{itemize}

After each commit, an automatic mail is sent to the
\texttt{cgal-cvs-l@postino.mpi-sb.mpg.de} mailing-list which records
the log message as well as URL to the corresponding diffs within
the ViewCVS interface.  Maintainers and developpers can subscribe
to it in order to check what gets commited to their packages.

\index{CVS server|)}