Adding a new Procedures part to the maint guide. Currently this lists

recommendations for CVS and Gnats, and the procedure used for making a
beta release.

Tom


git-svn-id: http://svn.cactuscode.org/flesh/trunk@2172 17b73243-c579-4c4c-a9d2-2d5706c11dac

10 files changed, 186 insertions, 8 deletions

diff --git a/doc/MaintGuide/Appendices.tex b/doc/MaintGuide/Appendices.tex
index c354e7a8..88bb92fe 100644
--- a/doc/MaintGuide/Appendices.tex
+++ b/doc/MaintGuide/Appendices.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{9}{Appendices}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{10}{Appendices}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{XEmacs customisation}
diff --git a/doc/MaintGuide/CST.tex b/doc/MaintGuide/CST.tex
index 29d3fed0..11e992ed 100644
--- a/doc/MaintGuide/CST.tex
+++ b/doc/MaintGuide/CST.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{3}{The CST}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{4}{The CST}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction}
diff --git a/doc/MaintGuide/Comm.tex b/doc/MaintGuide/Comm.tex
index 81bfd84b..b6eae833 100644
--- a/doc/MaintGuide/Comm.tex
+++ b/doc/MaintGuide/Comm.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{5}{The Comm subdirectory}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{6}{The Comm subdirectory}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction}
diff --git a/doc/MaintGuide/IO.tex b/doc/MaintGuide/IO.tex
index 652c0482..b338d1e8 100644
--- a/doc/MaintGuide/IO.tex
+++ b/doc/MaintGuide/IO.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{6}{The IO subdirectory}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{7}{The IO subdirectory}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction}
diff --git a/doc/MaintGuide/Main.tex b/doc/MaintGuide/Main.tex
index 057fa08b..a31918e0 100644
--- a/doc/MaintGuide/Main.tex
+++ b/doc/MaintGuide/Main.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{4}{The Main subdirectory}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{5}{The Main subdirectory}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction}
diff --git a/doc/MaintGuide/MaintGuide.tex b/doc/MaintGuide/MaintGuide.tex
index 23a2482a..64fe1805 100644
--- a/doc/MaintGuide/MaintGuide.tex
+++ b/doc/MaintGuide/MaintGuide.tex
@@ -294,6 +294,8 @@
 
 \include{Style}
 
+\include{Procedures}
+
 \include{Makesystem}
 
 \include{CST}
diff --git a/doc/MaintGuide/Makesystem.tex b/doc/MaintGuide/Makesystem.tex
index 57419505..eecd6684 100644
--- a/doc/MaintGuide/Makesystem.tex
+++ b/doc/MaintGuide/Makesystem.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{2}{The Make System}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{3}{The Make System}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction}
diff --git a/doc/MaintGuide/Procedures.tex b/doc/MaintGuide/Procedures.tex
new file mode 100644
index 00000000..7c83ebd2
--- /dev/null
+++ b/doc/MaintGuide/Procedures.tex
@@ -0,0 +1,176 @@
+% /*@@
+%   @file      Procedures.tex
+%   @date      Fri May 11 11:18:04 2001
+%   @author    Tom Goodale
+%   @desc 
+%   Various procedures
+%   @enddesc 
+%   @version $Header$
+% @@*/
+
+\begin{cactuspart}{2}{Procedures}{$RCSfile$}{$Revision$}
+\renewcommand{\thepage}{\Alph{part}\arabic{page}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Use of CVS} 
+
+Version control in Cactus is maintained by the use of the CVS
+software.  This software allows one to trace any change to a file from 
+the creation of a file to the present version, and provides an
+automatic notification system to alert interested parties of changes
+to files.  In order to make effective use of the system, the following 
+commit procedure is recommended as a guideline
+
+\begin{Lentry}
+\item[{\em Only make one change at a time}]
+Don't make a commit which changes several distinct things at once, as
+it is difficult then for people tracing changes back to distinguish
+which bit was changed for which reason.  See the note on commit
+messages below.
+\item[{\em Run the test suite}]
+This makes sure the code compiles, runs, and produces the correct results. 
+\item[{\em Know which files you are going to commit}]
+Always check what you are about to commit by use of the
+
+{\tt cvs -n -q update} 
+
+command.  This ensures that you know which files have been modified,
+which files have been removed and which files have been added, and
+provides a useful reminder to use the {\tt \verb.cvs add.} and {\tt
+\verb.cvs remove.} commands.
+\item[{\em Know what has changed}]
+The use of the
+
+{\tt cvs diff} 
+
+command on each modified file is a good check that you are not just
+committing an accidental keystroke or a debug statement.  Moreover it
+is a good reminder of what has changed and needs to be mentioned in
+the commit message.
+\item[{\em Provide clear and meaningful and relevant commit messages}]
+The commit message should explain what has changed and why, for
+details people can use {\tt \verb.cvs diff.}, however the commit
+message should be clear enough for people to have a good idea of what
+is going on.  This is strongly coupled to item about making only one
+change listed above - if two distinct things have been changed, they
+should be committed separately, with relevant commit messages.
+If the change resulted from a {\tt Problem Report} (PR) the PR number
+should be noted in the commit message.
+\end{Lentry}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Use of GNATS}
+
+Bug tracking in Cactus is maintained by use of the GNATS software.
+This software provides audit trails of the status and all
+correspondence concerning any problem report (PR).  Each problem is
+given a unique number and assigned a responsible person.
+
+\begin{Lentry}
+\item[{\em Correspondence}]
+All correspondence with the author of the PR should be copied to {\tt
+\verb,bugs@cactuscode.org,} with the subject line assigned by Gnats.
+This ensures that the correspondence is entered into the audit trail.
+\item[{\em Responsiblity}]
+When a PR comes in, it is assigned a responsible person.  If another
+person wishes to tackle the problem they should check with the
+responsible person, and then assign themselves as the responsible
+person.
+\item[{\em Initial auditing}]
+The responsible person should review the PR and check that the user
+supplied fields are sensible.  I particular the {\tt Synopsis} should
+be an accurate reflection of the problem, and the {\tt Priority} and
+{\tt Severity} fields should be set to the correct levels.  If the
+{\tt Release} field is badly filled out, attempts should be made to
+determine the relase version used by the PR submitter.  If it is a
+duplicate of a previous PR it should be marked as {\tt Duplicate}.
+\item[{\em Analysing the PR}]
+Once the responsible person has had a chance to review the PR, they
+should either seek further information from the submitter and mark the 
+PR state as {\tt Feedback}, or they should seek to determine the cause 
+of the problem and mark it as {\tt Analysed}.
+\item[{\em Closing a PR}]
+Once a problem is fixed, the PR state should be changed to the current 
+version number of Cactus.  The {\tt Fix} field should be filled out
+with what was done, and {\tt CVS} version numbers for the changed
+files should be noted.  Any miscellaneous comments about the problem
+should be noted in the {\tt Release-Note} field.
+\end{Lentry}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Release procedure}
+
+In the beta release cycle, Cactus is maintained in two CVS
+repositories - the `stable' \verb./cactus. and the development
+\verb./cactusdevcvs..  The stable version is the last beta release and 
+no commits should ever be made to it - it is for people who do not
+want to worry about things breaking from day to day.  The development
+version is the tree used for developing the next beta release.
+
+Making a beta release consists of copying the cvs modules from the
+development repository to the stable repository.  The following
+procedure is used:
+
+\begin{Lentry}
+\item[{\em Notify committers of start of release procedure}]
+This ensures that no commits are made during the following procedure.
+If it is impossible, for some reason, to notify a person of the start
+of the procedure, that person's commit rights should be revoked during 
+the procedure to prevent accidents.
+\item[{\em Check the code on all supported architectures}]
+The code should be checked out (in a fresh place), compiled and the
+test-suites run on all suppported architectures.  Problems found
+should be fixed or noted in the release notes.  This is an iterative
+procedure, as any commits made to fix problems need to be checked on
+all other architectures.
+\item[{\em Log into cvs machine as cactus\_admin}]
+All repository maintanence should be done as the cactus admin user.
+\item[{\em Store old module files}]
+A directory should be made in the stable repository, and all
+releaseable modules should be moved into that directory.  This will
+temporarily break checkouts/updates from that repository.  A suggested 
+command is of the form
+
+\begin{verbatim}
+cd /cactus
+mkdir BetaX
+mv Cactus{,Base,Connect,Einstein,X,X,X} BetaX
+\end{verbatim}
+
+\item[{\em Copy new module files}]
+e.g.
+\begin{verbatim}
+cp -r /cactusdevcvs/Cactus{,Base,Connect,Einstein,X,X,X} .
+\end{verbatim}
+\item[{\em Fix permissions on new module files}]
+\begin{verbatim}
+find Cactus{,Base,Connect,Einstein,X,X,X} -type d -exec chmod 777 \;
+Setperms.pl public Cactus{,Base,Connect,Einstein,X,X,X}
+\end{verbatim}
+\item[{\em Check that checkout/update works}]
+A fresh checkout should be made as a double check that all permissions 
+have been set correctly.
+\item[{\em Update version of development tree}]
+Update the version in {\tt Makefile} and commit it to the development
+tree.
+\item[{\em Re-enable commit access}]
+People whose commit access was removed in the first part of this
+procedure should have access re-enabled.
+\item[{\em Notify people}]
+The relase notes should be sent out to the cactus mailing lists and
+any other relevant places such as linux-announce and Freshmeat.
+\item[{\em Update web page}]
+The release should be noted in the news section of the web page.
+Additionally the html versions of the documentation should be updated.
+\item[{\em Close PRs}]
+Any problem reports which were closed in the beta relase should be
+audited for correct entries in the {\tt Fix} field and then their
+state should be marked as {\tt closed}.
+\end{Lentry}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\end{cactuspart}
diff --git a/doc/MaintGuide/Schedule.tex b/doc/MaintGuide/Schedule.tex
index 076a738a..fa6e3c47 100644
--- a/doc/MaintGuide/Schedule.tex
+++ b/doc/MaintGuide/Schedule.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{8}{The Schedule System}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{9}{The Schedule System}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction}
diff --git a/doc/MaintGuide/Util.tex b/doc/MaintGuide/Util.tex
index 54947757..4908e6d9 100644
--- a/doc/MaintGuide/Util.tex
+++ b/doc/MaintGuide/Util.tex
@@ -8,7 +8,7 @@
 %   @version $Header$
 % @@*/
 
-\begin{cactuspart}{7}{The Util subdirectory}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{8}{The Util subdirectory}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction}