mirror of https://github.com/CGAL/cgal
271 lines
11 KiB
TeX
271 lines
11 KiB
TeX
% =============================================================================
|
|
% The CGAL Developers' Manual
|
|
% Chapter: CVS Server
|
|
% -----------------------------------------------------------------------------
|
|
% file : cvs.tex
|
|
% authors: Mariette Yvinec <yvinec@sophica.inria.fr>
|
|
% -----------------------------------------------------------------------------
|
|
% $Revision$
|
|
% $Date$
|
|
% =============================================================================
|
|
|
|
\chapter{CVS Server}
|
|
\label{chap:cvs}
|
|
\ccChapterRelease{Chapter Version: 1.0} \\
|
|
\ccChapterAuthor{Mariette Yvinec ({\tt yvinec@sophia.inria.fr})}
|
|
\ccIndexMainItemBegin{CVS server}
|
|
|
|
CVS (Concurrent Versions System) is a very efficient 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. To know more about CVS, look at
|
|
\path|http://www.sourcegear.com/CVS/support|
|
|
where you can find an
|
|
\ccAnchor{http://www.sourcegear.com/CVS/Docs/overview}{introduction to CVS},
|
|
a \ccAnchor{http://www.sourcegear.com/CVS/Docs/ref}{quick reference list}
|
|
of CVS commands and
|
|
\ccAnchor{http://www.sourcegear.com/CVS/Docs/infopages}{the full reference manual}.
|
|
|
|
The machine \texttt{cgal.inria.fr} hosts a CVS server
|
|
(and also the Java demo server) for \cgal.
|
|
|
|
\section{Why use a CVS server?}
|
|
\label{sec:why_cvs}
|
|
|
|
The original motivation for the CVS server was the need by
|
|
developers separated by some distance to work on a single package.
|
|
A CVS server is a very convenient way to do that.
|
|
Currently, the server is used to handle the maintainance of orphaned packages
|
|
that don't have a precise maintainer but in which we sometimes need to
|
|
make trivial modifications, but it could also be used to handle, for
|
|
example:
|
|
\begin{itemize}
|
|
\item the web pages of the main \cgal\ web site(s);
|
|
\item the Java Demo files (in this way, you could more easily add a
|
|
demo for your algorithms);
|
|
\item the packages contributed by external people.
|
|
\end{itemize}
|
|
|
|
|
|
\section{Structure of the repository}
|
|
\label{sec:cvs_structure}
|
|
\ccIndexSubitem{CVS server}{directory structure}
|
|
\ccIndexSubitem{directory structure}{for CVS server}
|
|
|
|
The CGAL repository, which is backed up daily,
|
|
\ccIndexSubitem{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}),
|
|
except that it may include the full source code for the documentation
|
|
as well as the implementation. This means that source files from
|
|
literate programming tools (Chapter~\ref{sec:code_format}) used for
|
|
implementation and specification documentation are included as well
|
|
as a means to create the target files from the source files (\eg,
|
|
a makefile). Other files can be included too as long as there's an
|
|
automatic way to create the \cgal\ packages from the CVS files. We
|
|
may define a common interface for that, let say \ccc{make package}.
|
|
\item The CVS module should not include files that take a lot of disk space and
|
|
can be easily remade from the sources (\ie, no \texttt{.ps}, \texttt{.o},
|
|
\texttt{.tar.gz}, \etc).
|
|
\item A \ccc{Skeleton} CVS module will be provided to ease the creation
|
|
of new modules/packages that look like the others (thus more easily
|
|
handled by other people). For example we could require files like
|
|
\texttt{MAINTAINERS}, \texttt{TODO}, a main \texttt{Makefile}
|
|
with targets \texttt{clean}, \texttt{doc}, \texttt{package},
|
|
\texttt{submit}, \texttt{test}, \texttt{code}... (if there
|
|
should be a common structure, we shall decide it)
|
|
\end{itemize}
|
|
|
|
The repository tree will have the following structure:
|
|
|
|
\begin{verbatim}
|
|
$CVSROOT/CGAL
|
|
+---- Packages/
|
|
| +--- C2/
|
|
| | |-- TODO
|
|
| | |
|
|
| | |-- Makefile
|
|
| | |
|
|
| | |-- MAINTAINERS
|
|
| | |
|
|
| | +-- include/CGAL/
|
|
| | |
|
|
| | +-- src/
|
|
| | |
|
|
| | |-- changes.txt
|
|
| | |
|
|
| | |-- ...
|
|
| | |
|
|
| +--- CLN/
|
|
| |
|
|
| +--- Interval\_arithmetic/
|
|
| |
|
|
| +--- ...
|
|
| |
|
|
+---- Infrastructure/
|
|
|
|
|
+--- Skeleton/
|
|
|
|
|
+--- Manual_Tools/
|
|
|
|
|
+--- Web_Files/
|
|
|
|
|
+--- Scripts/
|
|
|
|
|
+--- ...
|
|
\end{verbatim}
|
|
|
|
|
|
\section{Access to the repository}
|
|
\label{sec:cvs_access}
|
|
\ccIndexSubitemBegin{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.
|
|
\item A set of people will have write access to the repository, primarily the
|
|
package maintainers.
|
|
\item Write access is determined on a per-directory basis under CVS.
|
|
There is a Unix group for each module (\cgal\ Package),
|
|
and anyone who has write access for a package is included
|
|
in the corresponding group. (The set of people who have write access
|
|
to a package should be decided by the maintainer of the package).
|
|
\item CVS allows several methods to access the repository. We chose the
|
|
so-called \textit{pserver} approach since it is compulsory for read-only
|
|
access. So there will be a Unix account on the machine
|
|
\texttt{cgal.inria.fr} for everyone who
|
|
should have write-access, plus one anonymous account
|
|
for \cgal\ members.
|
|
\item You won't be able to login on this machine except via CVS.
|
|
\end{itemize}
|
|
\ccIndexSubitemEnd{CVS server}{access}
|
|
|
|
|
|
\section{Check-in policy}
|
|
\label{sec:cvs_check_in}
|
|
\ccIndexSubitemBegin{CVS server}{check-in policy}
|
|
|
|
Here are the proposed check-in policies. (These are inspired from those of GCC,
|
|
so there is a proof that it can actually work.):
|
|
|
|
\begin{itemize}
|
|
\item Nobody is forced to use the CVS server to handle the maintainance of
|
|
packages.
|
|
\item Orphaned packages go there automatically so that they can be more easily
|
|
maintained by various people who will be given write-access.
|
|
\item Each package maintainer can put packages there if desired.
|
|
\item How check-ins are done for each package is decided by the maintainer.
|
|
We propose the following:
|
|
\begin{itemize}
|
|
\item You are the package {\bf maintainer}: you check-in what you want,
|
|
you decide who will be {\bf co-maintainer} of your package, and
|
|
who will have {\bf write permission after approval}.
|
|
\item You are a {\bf co-maintainer}: you have write access to the
|
|
package, you discuss the policy with the other co-maintainers
|
|
by e-mail, and tell them when you commit something.
|
|
\item You have {\bf write permission after approval} by the maintainer(s):
|
|
You have write-access, but you need the permission
|
|
of the maintainer to commit a patch.
|
|
This is useful if you want to contribute to a package frequently,
|
|
but the main maintainers want to review everything that you
|
|
check in before. After approval, you can check in the patch
|
|
yourself, and the maintainer(s) use \texttt{cvs update} to retrieve
|
|
your submitted patches.
|
|
\item You have only {\bf read-only} access to a package:
|
|
You can easily check out a copy of the current code,
|
|
make your modifications, test them, produce a patch (preferably
|
|
with \texttt{cvs diff -u} ) and send it by e-mail to the
|
|
maintainers of the package, who will be able to approve and check
|
|
it in, or disapprove.
|
|
\end{itemize}
|
|
\end{itemize}
|
|
\ccIndexSubitemEnd{CVS server}{check-in policy}
|
|
|
|
|
|
\section{How to use it}
|
|
\label{sec:cvs_how_to}
|
|
|
|
Note: this concerns the temporary current setup on \texttt{cgal.inria.fr}.
|
|
|
|
\begin{itemize}
|
|
\item
|
|
First, you have to login (this basically stores the password in your
|
|
\texttt{.cvspass} file). For read-only access, type: \\
|
|
\texttt{cvs -d :pserver:member1@cgal.inria.fr:/CVSROOT login} \\
|
|
and enter the corresponding password.
|
|
\item
|
|
To get the list of existing modules:
|
|
\texttt{cvs -d :pserver:member1@cgal.inria.fr:/CVSROOT co -c} \\
|
|
\item
|
|
To check out a module, say \ccc{C2}:
|
|
\texttt{cvs -d :pserver:member1@cgal.inria.fr:/CVSROOT co C2} \\
|
|
\item
|
|
Once you have checked out a module, you don't need to specify
|
|
\texttt{-d ...} anymore.
|
|
\item
|
|
If you need write access (you want to put your package there, or be
|
|
allowed to modify someone else's package), you need a
|
|
login name and password. To get one contact
|
|
\ccAnchor{mailto:yvinec@sophia.inria.fr}{\texttt{yvinec@sophia.inria.fr}}
|
|
and supply your login name, an encrypted password and the list of
|
|
the modules you want write access to.
|
|
\end{itemize}
|
|
|
|
You can use the following program to compute an encrypted password:
|
|
|
|
\begin{verbatim}
|
|
#define _XOPEN_SOURCE
|
|
#include <unistd.h>
|
|
#include <stdio.h>
|
|
|
|
int main()
|
|
{
|
|
// salt is a two-character string chosen from the set
|
|
// [a-zA-Z0-9./]. This string is used to perturb the algo-
|
|
// rithm in one of 4096 different ways.
|
|
const char *salt = "gc";
|
|
|
|
// Your password in clear text (8 characters max)
|
|
const char *key = "mypasswd";
|
|
printf("%s\n", crypt(key,salt));
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
|
|
|
|
\section{Remarks}
|
|
\label{sec:cvs_remarks}
|
|
|
|
\begin{itemize}
|
|
\item
|
|
This CVS server is still in an experimental stage. If you think
|
|
that small modifications should be done so that you could happily use
|
|
this stuff, then send mail to
|
|
\ccAnchor{mailto:cgal-develop@cs.uu.nl}{\texttt{cgal-develop@cs.uu.nl}}
|
|
or \ccAnchor{mailto:yvinec@sophia.inria.fr}{\texttt{yvinec@sophia.inria.fr}}
|
|
and let's discuss it.
|
|
\item
|
|
There are possibilities to run a script after each \texttt{cvs
|
|
commit} command to, for example, send mail to a list who would track
|
|
these modifications (and archive them), or the maintainers might receive
|
|
a mail for each modification done to their packages, \etc...
|
|
\item
|
|
We are open to technical suggestions from people who know about CVS.
|
|
\item
|
|
Currently the machine \texttt{cgal.inria.fr} is not very powerful,
|
|
but if the need arises, we might be able to upgrade it.
|
|
\item
|
|
If the scheme is successful and generalized, we might think about
|
|
extending it to the way we submit packages (Internal releases
|
|
can be created using the command \texttt{cvs update -rlast\_submit},
|
|
with an appropriate tag that the
|
|
maintainer just sets to a particular version, instead of submitting).
|
|
That's for the longer term.
|
|
\end{itemize}
|
|
|
|
\ccIndexMainItemEnd{CVS server}
|