% /*@@
%   @file      Procedures.tex
%   @date      Fri May 11 11:18:04 2001
%   @author    Tom Goodale
%   @desc 
%   Various procedures
%   @enddesc 
%   @version $Header$
% @@*/

\begin{cactuspart}{2}{Procedures}{}{$Revision$}
\renewcommand{\thepage}{\Alph{part}\arabic{page}}

Note that this whole Chapter is out-dated and needs a rewrite.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Use of git}

Version control in Cactus is maintained by the use of the git
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 git status}

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.git add.} and {\tt
\verb.git rm.} commands.
\item[{\em Know what has changed}]
The use of the

{\tt git diff}

command or

{\tt git add --patch}

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.git 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 the 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 the Issue Tracker}

Bug tracking in Cactus is maintained by use of the bitbucket platform.
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 the
bitbucket ticket.
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.  In 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 git} hash for the change
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 release cycle, Cactus is maintained in two git
branches - the `stable' \verb.Cactus_XXX. and the development
\verb.master. branches.  The stable version is the last release and
no non-reviewed 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 release.

Making a release consists of creating a new release branch from the
master branch.  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 Check example parameter files}]
The example parameter files in thorn {\em par} directories should be
run and updated for any additional or changed thorns or parameters.
\item[{\em Update ReleaseNotes}]
The release notes should be added to the \verb|doc/ReleaseNotes| file.
\item[{\em Tag the code}]
Tag the code with the latest release tag and update the {\tt LATEST}
and {\tt STABLE} tags.  The easiest way to do this is from a clean
checkout.
\begin{verbatim}
git tag Cactus_4_0_Beta_X_v0
\end{verbatim}

\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.
Most information such as generating documentation takes place automatically 
for the web pages, the only thing which needs to be done manually is to
checkout any new arrangements in the Stable Release in the relevent 
directories in the {\tt CheckOut} directory as {\tt cactus\_web}.
\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}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "MaintGuide"
%%% End: 
