\documentclass[11pt,a4paper,dvips]{article}
\usepackage{fancyvrb,graphicx,latexsym,inputenc}
\usepackage[ngerman]{babel}

\DefineVerbatimEnvironment
        {bbox}{Verbatim}{frame=single,xleftmargin = .8cm,commandchars=+\^\&} 
    
\newcommand{\codesnip}[1]{\begin{Verbatim}[frame=single,formatcom=\footnotesize,
tabsize=2,framesep=1em,#1,commandchars=+\(\)]}
\newcommand{\codesnipper}[1]{\begin{Verbatim}[frame=single,formatcom=\footnotesi
ze,tabsize=2,framesep=1em,#1,commandchars=+\{\}]}
% Header
\date{June 3. 2004}
\author{Benjamin Grauer}
\title{Subversion usage at open.datacore.ch}

% Beginning of the Documentation
\begin{document}
\maketitle
\tableofcontents
\newpage

% Kapitel 1
%%%%%%%%%%%%%%%%%%%%%%
\section{Subversion}
\subsection{Introduction}
Subversion is an easy to use, good to have tool for source code control, especially, if working in a team on a big project. It helps every team member to be up to date with the latest code, and that nothing will get lost. Not even things you have deleted will ever be lost (maybe there was some good stuff in it after all). 
Subversion lets you see all the changes that have been made to your programs, and even lets you go back to older versions of it, to check what you have done for the last few days (Subversion can be your calendar).
But the best thing is that it helps you to structure your programming process. With Subversion you are always asked to give a topic, to the changes you've just made, and so a certain flow evolves in the engineering of your growing software.

Subversion is like CVS a subversion control tool. It is meant to help us all in developing good software, without the inconveniences of user backups and mailings of new code. 
\\\\
For one person this means:
\begin{itemize}
  \item{Whenever you make a new change that works you check it in.}
  \item{Now you can play around with the code, and if you fail, you can always look at all the differences you have made since any release. This way you avoid many errors.}
  \item{If you really f***ed it up, you can revert all of your code back to a state, where it worked, and start over again.}
  \item{Now after your new change woked again, you can check them in again, and you can begin a new task.}
  \item{You don't have to worry about silly backup-files. Subversion is an automated backup system.}
  \item{You can code wherever you want. On the Laptop, on a Solaris, even on Mac OS X and Windows. The one doesn't interfere with the other.}
\end{itemize}

For more than one person it means:
\begin{itemize}
  \item{Everything that's ok for single developers.}
  \item{You are always up to date with the newest changes of your colleagues.}
\end{itemize}
Try it, and you will never ever code in another way again.

\subsection{How it works.}
Subversion is quite easy to use. From the view of the user it consists of two parts: The repository and the working copy.
\subsubsection{Repository}
The server on the net is a Subversion server, which holds the repository. The server handles all incoming requests regarding changes of the source code. Those changes are then appended to the repository. And as a user the story ends here.
\subsubsection{Working Copy}
This is the interesting part for you. This is where you actually change your code.
The working copy is in its basics nothing else, than a copy of the repository. At first you copy the repository to your local computer (checkout), hack around, and if you are at ease with your changes, you submit the changes (and only the changes) back to the repository. So now your working copy is the same as the repository once again.

\subsection{Subversion in practical use}
 Subversion comes with many different commands: svn, svnadmin, svnversion...
But from the user's point of view, only svn itself is important. It does everything, but creating and managing a repository. That's what svnadmin is for, but this will not be discussed here.

\subsubsection{Getting Subversion}
Subversion is a product of tigris.org and can be found at http://subversion.tigris.org
Under Linux there are many ways to get Subversion.
Gentoo: emerge subversion :)\\
Debian: apt-get install subversion (should work)\\
Other Distributions: get it from http://subversion.tigris.org/project\_packages.html\\
I hope it's clear how to install it from there on. \\

On Windows I strongly recommend use the fully integrated graphical tortoiseSVN, that can be downloaded from 
http://tortoisesvn.tigris.org/download.html
There is also a non-graphical version, that can be more convenient for advanced Windows users (why are you still pretending you use a easier system than Linux, if you are that advanced?)\\

Mac users: You say plug and play, so do it... I never tried it.

\subsubsection{svn Commands}
First of all I give you the advice of looking up the help of svn. Do this either by either reading the manual via ``man svn'' or by using the embedded help, using the following commands
\codesnip{gobble=0}
   svn help             or              svn help [command]
\end{Verbatim}
By typing in the first one, you will receive a list of all the available subcommands:
\codesnip{label=subcommands of svn, gobble=0}
   add
   blame (praise, annotate, ann)
   cat
   checkout (co)
   cleanup
   commit (ci)
   copy (cp)
   delete (del, remove, rm)
   diff (di)
   export
   help (?, h)
   import
   info
   list (ls)
   log
   merge
   mkdir
   move (mv, rename, ren)
   propdel (pdel, pd)
   propedit (pedit, pe)
   propget (pget, pg)
   proplist (plist, pl)
   propset (pset, ps)
   resolved
   revert
   status (stat, st)
   switch (sw)
   update (up)
\end{Verbatim}
On this list you can see all subcommands and their aliases.

I will now introduce to you all the really important commands and their most used flags, so you can start working the code (the list won't be complete, but in most cases you won't need more, than what I tell you here):

\begin{enumerate}
\item{checkout, co}\\
With this option you can get the source out of a repository. This is a command you should only use once.
The default syntax is as follows:
\codesnip{label=svn checkout, gobble=0}
svn checkout [URL] [Path]
\end{Verbatim}

\item{commit, ci}\\
So now you have worked with the code and made some changes to it, added new features, updated obsolete code, and all works better now. You are at a state, where you can commit all the good new changes to the repository.\\
This is done as follows:
\codesnip{label=svn commit, gobble=0}
svn commit -m ''message''
\end{Verbatim}
Notice, that here you dont have to pass an URL. This is because svn knows, in which repository the files reside. You can also tell svn, that it should only commit certain files,. That's done by just adding a filename to the parameter list of ``svn ci''.
Also be aware to give a good topic to the changes you have just made. You can pass a message with your changes in ``message''. You can also leave -m ``message'' away. Like this svn will use your default editor to write the message. This can be very handy, if you want to write a long message about what you have done.

\item{update, up}\\
With this command, you fetch all the changes others have done to the repository, since you last updated (or checked out) the changes.
\codesnip{label=svn update, gobble=0}
svn update [-R [revision]]
\end{Verbatim}
 It is necessary to do this before you start coding on a big project. Sometimes, if someone has commited a change to a file, where you have made a recent change too, you have to update before you can commit yourself, so that the repository never has to decide, which version to accept (actually this is a long story and if you want to know more about it, look at the manual.)\\
With the flag ``-R [revision]'' you can also downgrade your workling copy to an older revision. Like this you can check, when an error has occured, and see if it did not happen in older revisions.

\item{revert}\\
This command comes in handy, if you absolutely failed to do any good. It changes everything back to the state where you last updated your working Copy.
\codesnip{label=svn revert, gobble=0}
svn revert [-R] [filename]
\end{Verbatim}
if you want to revert everything, -R=(recursive) and [filename]=* will be a good choice.

\item{add}\\
This command adds a new file to the repository:
\codesnip{label=svn add, gobble=0}
svn add [file]
\end{Verbatim}
If you just add a new file in one directory of your working copy, the file will not be added to the repository. You have to add it via svn, so subversion knows, it belongs to the directory. You understand the meaning of this if you work with emacs, which creates backups of files in the same directory.\\
It's important, that you have to commit the added files, so other people see the changes.

\item{delete, del, remove, rm}\\
The opposite of add
\codesnip{label=svn delete, gobble=0}
svn delete [file]
\end{Verbatim}
It's good to know, that if you accidentally delete a file with ``rm [file]'' you can call it back with ``svn update'' and then delete it with ``svn delete [file]''

\item{status, st}\\
Shows all the files, that have been changed or added, or that are just loosely swimming around in the working copy.

\item{diff}\\
shows you the differences you have done since the last update.
\codesnip{label=svn diff, gobble=0}
svn diff [file]
\end{Verbatim}
Leave [file] away to see all changes.\\
If you want to see all changes since a certain revision, you can add the parameter -r [revisionnumber].

\item{copy, cp}\\
As the name implies, it copies some part of the working copy somewhere else.
\codesnip{label=svn cp, gobble=0}
svn cp [source] [destination]
\end{Verbatim}
What can come in handy, is that source may also be a path. You do not have to include a -R to recursively add its contents.

\item{move, mv}\\
Same as copy, but moves things around.

\item{all other things}\\
Everything else is too advanced to be mentioned here, and as such will only be for complex svn transactions, between different structures.
\codesnip{label=manual, gobble=0}
http://subversion.tigris.org/servlets/ProjectDocumentList
\end{Verbatim}
This site has a great manual about all those actions. Visit it and read the manual, if you like.
\end{enumerate}

\subsubsection{Conclusion}
Now you have a little overview of the most important commands of svn. They pretty much describe, what a beginner should know, before workling with subversion. With time you will know all these subcommands by heart, and you will begin to love them all.\\
What remains to be said, is that tortoiseSVN for Windows does not need all the flags, but there too, you have to know what all the commands are about.\\
I hope you have some fun exploring all the advantages of subversion, and that you manage to create better and more complex programs with it.

\section{Subversion in DataCore-style}
First of all I have to point out, that this is not a unique way of doing subversion control, and if you use this method, you will understand, why it is a fantastic approach to coding in a big team.

\subsection{Structure}
DataCore splits the programming into 4 pieces: 
\begin{enumerate}
\item{trunk}\\
In the trunk, only the chief programmer has a say. He controls it, and only he can code into it. The official releases are created from the trunk.
\item{branches}\\
Here all the developers create their stuff. Usually, everyone gets his own branch, either one, that is named after the programmer, or one that is named after the modules in it.\\
For example, when I am joining a project, and I just want to try some things with the code, I call my branch: branches/myname. Over time I understand the code, and I am ready to do my part. I decided to do the part of the program, that manages the display, so I name the branch: branches/display.\\
I think you get the point.
\item{tags}\\
This is nothing else, than a copy of the trunk. The only difference here, is that this won't evolve over time. You can say, that a tag is a copy of the trunk at a certain time.\\
They are usually called tags/[versionnumber]
\item{releases}\\
This is the same thing as a tag, with the slight difference, that it is a real release. It's a tag, which has been released.
\end{enumerate}

\subsection{Example}
An example of this structure is the Linux kernel (although it is held in CVS; another version control tool).\\
There are thousands of people working on it in branches, but only one person is capable of adding new features into its trunk (Linus Torvalds, the inventor of Linux). Tags are created between releases of new Kernels (example: the mm-sources). And releases are always named with ``2.6.4'',``2.5.5'' and so on.\\
So you see, Linus Torvards is the Lord of the trunk and he is the only one, who can make a release. All the others can only work in branches, and can only make tags.\\
Pretty cool, ey?

\subsection{Working with the Code at DataCore}
The infrastructure of DataCore is given to us, so we have to contribute to it. And we have to make this in a nice, polite and serious way. So here are the things, you have to do and respect:
\subsubsection{Checking out the Code}
As I have already told you, the first thing you do, is to check out the source code.\\
You can do this either as an anonymous user in read-only mode via:
\codesnip{label=cheching out anonymously, gobble=0}
svn checkout https://open.datacore.ch/read-only/orxonox+footnotemark orxonox
\end{Verbatim}
\footnotetext{This implies, that you will check out project orxonox.}

Or if you have a registered username and a password:
\codesnip{label=user checkout, gobble=0}
svn checkout https://open.datacore.ch/pw/orxonox orxonox
\end{Verbatim}
Be sure to accept the certificate and if you like, to save the authentication information.

\subsubsection{Coding}
Hold on to the coding conventions of the GNU Public License. If you don't know, what this means, just code in a structured way and ask someone, what you should look out for.\\
Always consider, that others might work with your code, and that they have to understand it too.

\subsubsection{Checking in}
Checking in is quite easy, the only thing, that you have to do is:
\codesnip{label=svn commit, gobble=0}
svn commit -message "message"
\end{Verbatim}
It's Important, that the message is structured the right way, so anyone can see at first sight, what you commited. A message should look like this
\codesnip{label=message, gobble=0}
[Projectname]/[where]: [Topic]
\end{Verbatim}
An example would be:\\
\codesnip{label=example, gobble=0}
svn ci -m "orxonox/branches/opengl: Made the reflections look perfect." 
\end{Verbatim}
Respect these rules, because this way the world will know what you are doing...

\section{Afterword}
I hope this guide will helped you to learn the principles of Subversion. If not, please mail us at orxonox-dev@mail.datacore.ch. All comments, constructive, positive or negative are welcome there.
I know that my english is not the best by nature, so I hope you send me all errors and suggestions about changes, that you might find. 

\end{document}