% Bazaar Quick Reference
% Copyright (C) 2008-2009 ABINIT Group (Yann Pouillon).
% Originally written by Yann Pouillon.
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
%
\documentclass[tumble,foldmark,a4paper]{leaflet}
\usepackage[utf8]{inputenc}
\usepackage{pstricks,pstcol}
\usepackage{url}
\usepackage{palatino}

\definecolor{infobg}{rgb}{0.8,0.8,1.0}
\definecolor{infofg}{rgb}{0.0,0.0,0.3}
\definecolor{warnbg}{rgb}{1.0,0.8,0.8}
\definecolor{warnfg}{rgb}{0.3,0.0,0.0}

\renewcommand*\foldmarkrule{.3mm}
\renewcommand*\foldmarklength{190mm}

\begin{document}

\begin{center}
{\Large {\bf ABINIT FORGE}}

\vspace{32mm}

\includegraphics{bzr-logo}

\vspace{24mm}

{\Huge Quick reference for \\[0.5em] committers}

\vspace{40mm}

Copyright \textcopyright\ 2008-2009 ABINIT Group. \\
Originally written by Yann Pouillon.
\end{center}

\newpage

\section*{Read this first}

On \url{http://abinit.org/developers/}, in the \textit{Bazaar} section:
\begin{itemize}
 \item Introduction, part I
 \item Introduction, part II
 \item Introduction, part III
 \item Non-standard install
\end{itemize}
and documents cited therein.

\section*{Structure of the ABINIT Forge}

Full URL of a branch (one line, no space):
\begin{center}
 \url{bzr+ssh://archives.abinit.org/} \\
 $\hookrightarrow$ \url{abinit/x.y/<repository>/<branch>/}
\end{center}

\texttt{x}: major version number \\
\texttt{y}: minor version number \\

\texttt{repository}: \textit{trunk}, or committer login \\

Public branches (created automatically):
\begin{center}
\begin{itemize}
 \item \texttt{devel-public}
 \item \texttt{x.y.1-public}
 \item \texttt{x.y.2-public}
 \item \texttt{x.y.3-public}
 \item \texttt{x.y.4-public}
 \item \texttt{x.y.5-public}
\end{itemize}
\end{center}

Private branches: automatically created replacing "public" by "private"
in the names above; additional branches free-form, upon request to the
Forge maintainers. \\

\newpage

\section*{Useful commands}

\begin{center}
 \begin{tabular}{l l}
  \textbf{bzr ...} & \textbf{Result} \\
  \hline
  \texttt{help} & Get help \\
  \texttt{info} & Get source tree info \\
  \texttt{status} & Get status report \\
 \end{tabular}
\end{center}

\begin{center}
\psframebox[fillstyle=solid,fillcolor=infobg,linecolor=infofg]{%
 \parbox{7.8cm}{%
  \color{infofg}
  \begin{center}
   \textbf{BEFORE ACCESSING THE FORGE} \\
   \vspace{0.5em}
   {\small
    \texttt{export EDITOR="/path/to/my/editor"} (BASH) \\
    or \\
    \texttt{setenv EDITOR "/path/to/my/editor"} (CSH)
   }
  \end{center}
 }
}
\end{center}


\section*{Working with branches}

A \textit{branch} is an autonomous copy of the source code. All history
is kept locally, except when explicitely \textit{published} by the
committer.

\vspace{-0.5em}

\begin{center}
 \begin{tabular}{l l}
  \textbf{Action} & \textbf{Command} \\
  \hline
  Get & \texttt{bzr branch url $[$local\_dir$]$} \\
  Sync & \texttt{bzr pull $[$url$]$} \\
  Publish & \texttt{bzr push $[$url$]$} \\
  Off-line & \texttt{bzr commit} \\
 \end{tabular}
\end{center}

Typical use: decentralised development. \\

If the working tree is empty, run \texttt{bzr checkout} from within.

\section*{Working with checkouts}

A \textit{checkout} is a branch the history is kept on the Forge. It can
however be made autonomous temporarily.

\vspace{-0.5em}

\begin{center}
 \begin{tabular}{l l}
  \textbf{Action} & \textbf{Command} \\
  \hline
  Get & \texttt{bzr checkout url $[$local\_dir$]$} \\
  Sync & \texttt{bzr update} \\
  Publish & \texttt{bzr commit} \\
  Off-line & \texttt{bzr commit --local} \\
 \end{tabular}
\end{center}

Typical use: one developer working on two computers.

\newpage

\section*{Writing changelogs}

Template:

\vspace{-0.5em}

\begin{verbatim}
One short summary line (no trailing dot)

* dir1/sub1/file1: Some changes. Make
full sentences.

* dir2/sub2/file2,dir3/sub3/file3: Some
other changes.
* dir4/sub4/file4: Related changes (no
blank line before).

* Additional notes and issues.
\end{verbatim}

GNU changelog format: please make sure that all lines are $<$ 80
characters and start at the first column. For a complete reference
(one-line URL, no space):
\begin{center}
 \url{http://www.gnu.org/prep/standards/} \\
 $\hookrightarrow$ \url{html_node/Change-Logs.html}
\end{center}

\section*{Committing}

Check-list:
{\tt
\begin{enumerate}
 \item bzr status
 \item Process files marked as unknown. \\
       Go back to 1 until no file is marked as unknown.
 \item Write changelog.
 \item bzr commit --strict $[$-F logfile$]$ \\
       Use -F option if your changelog is in a file.
\end{enumerate}
}

\vspace{0.5em}

\begin{center}
\psframebox[fillstyle=solid,fillcolor=infobg,linecolor=infofg]{%
 \parbox{7cm}{%
  \color{infofg}
  \centerline{\textbf{NOTE}}
  \vspace{0.5em}
  Committing to a public branch will soon trigger a nightly build followed by
  a run of the test suite, informing the gatekeeper afterwards.
 }
}
\end{center}

\newpage

\section*{Merging branches and solving conflicts}

Merge check-list:
{\tt
\begin{enumerate}
 \item Commit.
 \item bzr merge \ldots
 \item Solve conflicts (if any).
 \item Write merge changelog.
 \item Commit.
\end{enumerate}
}

\begin{center}
\psframebox[fillstyle=solid,fillcolor=warnbg,linecolor=warnfg]{%
 \parbox{6cm}{%
  \color{warnfg}
  \centerline{\textbf{IMPORTANT}}
  \vspace{0.5em}
  \centerline{\textbf{\textit{\underline{ALWAYS}}} commit}
  \centerline{just before \textit{\underline{and}} after merging!}
 }
}
\end{center}

\vspace{0.5em}

Conflict check-list:
{\tt
\begin{enumerate}
 \item File myfile has a conflict \\
  $\Longrightarrow$ myfile.BASE: before divergence \\
  $\Longrightarrow$ myfile.THIS: local version \\
  $\Longrightarrow$ myfile.OTHER: from other tree
 \item kdiff3 myfile.BASE myfile.OTHER \\
  $\hookrightarrow$ myfile.THIS \# One line
 \item Save result as myfile.
 \item bzr resolved myfile \\
 $\longrightarrow$ removes files created at step 1!
\end{enumerate}
}

\begin{center}
\psframebox[fillstyle=solid,fillcolor=warnbg,linecolor=warnfg]{%
 \parbox{6cm}{%
  \color{warnfg}
  \centerline{\textbf{IMPORTANT}}
  \vspace{0.5em}
  If \textit{myfile} does not exist when typing \texttt{bzr~resolved},
  it will automatically be marked as \textit{removed} by bzr.
 }
}
\end{center}

\newpage

\section*{Useful addresses}

\begin{center}
\textbf{ABINIT Forge} \\
\url{bzr+ssh://archives.abinit.org/} \\
$\hookrightarrow$ \url{abinit/<version>/<developer>/<branch>/} \\
\textit{Development branches of ABINIT 5.5 and later. All of the URL
should be typed at once (one line only, no space).}
\end{center}

\begin{center}
\textbf{ABINIT Website - Developer's Corner} \\
\url{http://abinit.org/developers/} \\
\textit{Reference information for developers.}
\end{center}

\begin{center}
\textbf{Bazaar Website} \\
\url{http://bazaar-vcs.org/} \\
\textit{Home page of the Bazaar Version Control System.}
\end{center}

\section*{Mailing lists}

\begin{center}
\textbf{Announcements} \\
\url{announce@abinit.org} \\
\textit{Low-traffic list for important announcements about ABINIT.}
\end{center}

\begin{center}
\textbf{User Forum List} \\
\url{forum@abinit.org} \\
\textit{Discussions about the use of ABINIT.}
\end{center}

\begin{center}
\textbf{Developer Forum List} \\
\url{developer@abinit.org} \\
\textit{Discussions about the development of ABINIT.}
\end{center}

\begin{center}
\textbf{Committer List} \\
\url{gnuarch@abinit.org} \\
\textit{For developers having an access to the ABINIT Forge (restricted).}
\end{center}

\section*{Need help?}

To get help on all Bazaar commands, just remember \texttt{bzr~help}.

\end{document}
