\chapter{GNU arch}

A control version system is a tool that keeps track of changes made
in the code, when a change was made, by whom. It helps multiple
developers to work on the same project, to merge the different
changes they made in the same code base.

{\em GNU arch}\footnote{\tt http://www.gnu.org/software/gnu-arch/}
(also known as {\em tla}) is a modern and advanced control version
system. It is the one we use to manage the {\tt itools} source code.

There are many ways to work with {\em tla}, this appendix explains
the one we use for {\tt itools}.

The exposition is organized in three sections that detail:

\begin{enumerate}
  \item How to keep track of the development of {\tt itools}.

  \item How to maintain private changes.

  \item How to contribute your changes back to the main development tree.
\end{enumerate}


\section{Keeping track of {\tt itools}}

You may want to have the last bleeding edge features from {\tt itools} in
your system as soon as they are written, or to track how the development
is going on. Then this section is for you.

\subsection{Browsing the sources}

To browse the {\tt itools} archive tree through the web, just go the url
below:

\begin{code}
    http://in-girum.net/cgi-bin/archzoom.cgi/jdavid@itaapy.com--public
\end{code}

\subsection{Check out}

To check out {\tt itools} from the archive you need to install {\em tla}.
Most distributions include it, for example, if you use
Gentoo\footnote{http://www.gentoo.org} just type:

\begin{code}
    $ sudo emerge tla
\end{code}

Once {\em tla} is installed, follow the steps described below.


\subsubsection{Set your id}

\begin{code}
    $ tla my-id "Toto Bonaparte <toto@example.com>"
    $ tla my-id
    Toto Bonaparte <toto@example.com>
\end{code}


\subsubsection{Register the official {\tt itools} archive}

\begin{code}
    $ tla register-archive jdavid@itaapy.com--public \
          http://in-girum.net/~jdavid/archives/public
    $ tla archives
    jdavid@itaapy.com--public
        http://in-girum.net/~jdavid/archives/public
\end{code}


\subsubsection{Check out {\tt itools}}

\begin{code}
    $ cd ~/sandboxes
    $ tla get jdavid@itaapy.com--public/itools--main--0.6 itools-0.6
    $ cd itools-0.6
    $ tla tree-version
    jdavid@itaapy.com--public/itools--main--0.6
\end{code}

\subsection{A session with {\em tla} and {\tt itools}}

Now, whenever you want to see if something has changed in {\tt itools},
just type:

\begin{code}
    $ cd ~/sandboxes/itools-0.6
    $ tla missing --summary
    patch-80
        use Python's documentation to profile the catalog
    patch-81
        fix XML error handling (hence better STL message errors)
\end{code}

The output shows the new patches available (if your code is up-to-date
the output will be empty). Say you want to apply the patches, type:

\begin{code}
    $ tla update
    [...]
\end{code}

\subsection{Help}

The Table~\ref{Table: tla commands 1} summarizes the {\em tla} commands seen
in this section. To learn about other commands use {\tt tla help}, and
for details about a command type:

\begin{code}
    $ tla <command> --help
\end{code}

\begin{table}
  \begin{api}
    {\tt tla my-id}\\
    - Print or change your id.

    {\tt tla register-archive}\\
    - Change an archive location registration.

    {\tt tla archives}\\
    - Report registered archives and their locations.

    {\tt tla get}\\
    - Construct a project tree for a revision.

    {\tt tla tree-version}\\
    - Print the default version for a project tree.

    {\tt tla missing}\\
    - Print patches missing from a project tree.

    {\tt tla update}\\
    - Update a project tree to reflect recent archived changes.

    {\tt tla help}\\
    - Provide help with arch.
  \end{api}
  \caption{Basic {\em tla} commands}
  \label{Table: tla commands 1}
\end{table}


\section{Maintaining private changes}

Now maybe you want to make some changes to {\tt itools}. The wisest to do
in this situation is to create a branch of {\tt itools}, this will let you
to easily update to the last version while keeping your changes.

The first step is to setup an archive (if you have already one you can
skip to the next subsection).

\subsection{Create an archive}

\begin{code}
    $ mkdir ~/{archives}
    $ mkdir ~/{archives}/public
    $ tla make-archive toto@example.com--public ~/{archives}/public
    $ tla archives
    jdavid@itaapy.com--public
        http://in-girum.net/~jdavid/archives/public
    toto@example.com--public
        /home/toto/{archives}/public
\end{code}

Make it your default archive:

\begin{code}
    $ tla my-default-archive toto@example.com--public
    $ tla my-default-archive
    toto@example.com--public
\end{code}

\subsection{Create a branch}

With your own archive, it is time to create a branch of {\tt itools}:

\begin{code}
    $ tla tag -S jdavid@itaapy.com--public/itools--main--0.6 itools--toto--0.6
      * creating category toto@example.com--public/itools
      * creating branch toto@example.com--public/itools--toto
      * creating version toto@example.com--public/itools--toto--0.6
      * Archive caching revision
\end{code}

So now you can replace the check-out from the main tree with a one from
your own branch:

\begin{code}
    $ cd ~/sandboxes
    $ rm -rf itools-0.6
    $ tla get toto@example.com--public/itools--toto--0.6 itools-0.6
    $ cd itools-0.6
    $ tla tree-version
    toto@example.com--public/itools--toto--0.6
\end{code}


\subsection{Working with your branch}

So, now you modify {\tt itools} to add a new feature. Every change made
to a file will be automatically detected by {\em tla}, but if your work
includes new files or directories, or you have removed, renamed or moved
a file or a directory, then you must tell {\em tla} about these changes,
to do so use the commands below:

\begin{code}
    $ tla add <filename>
    [...]
    $ tla delete <filename>
    [...]
    $ tla move <old filename> <new filename>
    [...]
\end{code}

Maybe you forgot to add a file, before committing is a very good idea
to verify it with the command {\tt tree-lint}:

\begin{code}
    $ tla tree-lint
    [...]
\end{code}

This command looks at your project tree and tells you about files suspected
to be source code that have non been added yet.

Ok, so you have finished working on this new cool feature and are willing
to check it in your branch of {\tt itools}. First, verify what you have
changed:

\begin{code}
    $ tla changes
    [...]
\end{code}

This command shows which files (and folders) have been modified, removed,
added or moved. For a more detailed description, try:

\begin{code}
    $ tla changes --diffs | less
\end{code}

Take your time to examine the changes, maybe you forgot to remove a print
statement? a close look at the output of {\tt tla changes --diffs} will
tell you.

Once you are sure everything is alright, it came the time to commit.
First you have to write a log message:

\begin{code}
    $ vi `tla make-log`
\end{code}

Within the editor, you should introduce a title that describes the changes
you have done, and optionally a longer description. Once you are done,
left the editor and type:

\begin{code}
    $ tla commit
    $ tla revisions
    [...]
    patch-1
        add feature XXX
\end{code}


\subsection{Merging from the main branch}

Ok, so now the upstream version of {\tt itools} is modified, how to merge
the changes in your tree? easy:

\begin{code}
    $ cd ~/sandboxes/itools-0.6
    $ tla star-merge -t jdavid@itaapy.com--public/itools--main--0.6
    [...]
\end{code}

Beware, there may be conflicts that you must resolve.

Now, your project tree contains the changes from the upstream archive,
you must commit them in your own archive. The log is written automatically
by typing:

\begin{code}
    $ tla log-for-merge >> `tla make-log`
    $ vi `tla make-log`
\end{code}

Within the editor there will be a description detailing the patchs that
have been applied. So you just have to add the subject, something like
``merging from the main tree''. Once this is done just commit as usual:

\begin{code}
    $ tla commit
\end{code}


\subsubsection{Summary}

See the Table~\ref{Table: tla commands 2} for a summary of the {\em tla}
commands seen in this section.

\begin{table}
  \begin{api}
    {\tt tla make-archive}\\
    - Create a new archive directory.

    {\tt tla my-default-archive}\\
    - Print or change your default archive.

    {\tt tla tag}\\
    - Create a continuation revision (aka tag or branch).

    {\tt tla add}\\
    - Add an explicit inventory id.

    {\tt tla delete}\\
    - Remove an explicit inventory id.

    {\tt tla move}\\
    - Move an explicit inventory id.

    {\tt tla tree-lint}\\
    - Audit a source tree.

    {\tt tla changes}\\
    - Report about local changes in a project tree.

    {\tt tla make-log}\\
    - Initialize a new log file entry.

    {\tt tla commit}\\
    - Archive a changeset-based revision.

    {\tt tla revisions}\\
    - List the revisions in an archive version.

    {\tt tla star-merge}\\
    - Merge mutually merged branches.

    {\tt tla log-for-merge}\\
    - Generate a log entry body for a merge.
  \end{api}
  \caption{Maintaining private changes: summary}
  \label{Table: tla commands 2}
\end{table}



\section{Contributing your work to the main tree}

To contribute your changes back to the main development branch you must
make your branch available through internet. We assume the archive you
have set-up is your local computer, so you have to create a mirror of
your archive from your local computer to an internet server:

\begin{code}
    $ tla make-archive --listing --mirror toto@example.com--public \
          sftp://example.com/home/toto/{archives}/public
\end{code}

You must be sure your mirror can be accessed through an internet protocol,
like HTTP or FTP. So other developers will be able to merge from your branch.

Now, whenever you make and commit a change, to share that change with the
community, you have to synchronize your mirror:

\begin{code}
    $ tla archive-mirror
    [...]
\end{code}

See the Table~\ref{Table: tla commands 3} for a summary of the commands seen
in this section.

\begin{table}
  \begin{api}
    {\tt tla archive-mirror}\\
    - Update an archive mirror.
  \end{api}
  \caption{Maintaining private changes: summary}
  \label{Table: tla commands 3}
\end{table}
