\documentclass[pdf]{prosper}
\usepackage[toc,highlight,linbit,notes,hlsections]{HA-prosper}

\title{Distributed Software Development using Subversion and SubMaster}
\subtitle{Infrastructure for the Bazaar}
\author{Clifford Wolf\\
\institution{LINBIT}\\
\institution{\href{http://www.linbit.com}{http://www.linbit.com}}}

\DefaultTransition{Wipe}
\TitleSlideNav{FullScreen}
\NormalSlideNav{ShowBookmarks}
\LeftFoot{\href{http://www.clifford.at}{Clifford Wolf}, \today}
\RightFoot{\href{http://www.rocklinux.org/submaster.html}{SubMaster}}


\begin{document}

\maketitle

% ============================================================================

\tsectionandpart{Introduction}


\begin{slide}{Development Models}
\includegraphics[scale=.42]{../fig/models.eps}
\end{slide}


\overlays{6}{
\begin{slide}{Requirements}
\begin{itemstep}[stype=2]

\item Everyone must have the possibility to send patches

\vspace*{.5cm}
\item There must be no way for patches to be lost or ignored

\vspace*{.5cm}
\item Creating and sending patches must be as easy as possible

\vspace*{.5cm}
\item Keeping local changes and main tree in sync must be easy

\vspace*{.5cm}
\item There must be no restictions due to licences or binary only executables

\vspace*{.5cm}
\item Using the system without a GUI should be possible

\end{itemstep}
\end{slide}
}


\overlays{5}{
\begin{slide}{What is Subversion (1)}
\begin{itemstep}[stype=2]

\item Subversion is a a version control system

\vspace*{.5cm}
\item The entire history of a project including all branches is stored in a
Database called Subversion Repository

\vspace*{.5cm}
\item A Subversion Repository can also be seen as a filesystem with special
capabilities

\vspace*{.5cm}
\item Pleople can check out files or directories from a Subversion Repository,
change them and commit the changes back to the repository

\vspace*{.5cm}
\item Some changes can be done directly on the repository without creating
a working copy

\end{itemstep}
\end{slide}
}


\overlays{4}{
\begin{slide}{What is Subversion (2)}
\begin{itemstep}[stype=2]

\item Subversion Repositories can be accessed thru the filesystem,
using HTTP/WebDAV or by a special SVN:// protocol

\vspace*{.5cm}
\item The tool for creating and maintaining the database behind a Subversion
Repository is called 'svnadmin'

\vspace*{.5cm}
\item The tool for working with the Subversion Repository and Working copies
is called 'svn'

\vspace*{.5cm}
\item The calling convention for 'svn' is simmilar to the calling convention
for 'cvs'

\end{itemstep}
\end{slide}
}


\overlays{5}{
\begin{slide}{Subversion is for the Cathedral}
\begin{itemstep}[stype=2]

\item Subversion on it's own is not good for bazaar-style development

\vspace*{.5cm}
\item There is only one central repository

\vspace*{.5cm}
\item Only a limited number of people has write access to the tree

\vspace*{.5cm}
\item Everyone else has to send patches per email

\vspace*{.5cm}
\item It's hard to keep a local tree with patches in sync with
the official tree

\end{itemstep}
\end{slide}
}


\overlays{5}{
\begin{slide}{What is SubMaster}
\begin{itemstep}[stype=2]

\item SubMaster is a set of scripts based on Subversion targeting
bazaar-style development

\vspace*{.5cm}
\item Everyone has his own local Subversion repository

\vspace*{.5cm}
\item SubMaster keeps the local repository in sync with the
master repository preserving local changes

\vspace*{.5cm}
\item SubMaster provides an infrastructure for sending patches,
collecting feedback and applying patches to the master tree

\vspace*{.5cm}
\item Working with SubMaster almost feels like having write access to
the official tree

\end{itemstep}
\end{slide}
}


\begin{slide}{Components}
\includegraphics[scale=.4]{../fig/components.eps}
\end{slide}


\overlays{3}{
\begin{slide}{Mortal Kombat}
\begin{itemstep}[stype=2]

\item In his keynote about Linux Kenrel development at the german
Linux Kongress, Russty Russel did talk about "Code By Confrontation".

\vspace*{.5cm}
\item He called that
\vspace*{.2cm} \\
\hspace*{3cm}The Mortal Kombat Model \\
\hspace*{3.1cm}of Software Development

\vspace*{.5cm}
\item So the SubMaster tools are nothing else than
\vspace*{.2cm} \\
\hspace*{2.4cm}The Weapons and Battlefield of the \\
\hspace*{2.0cm}Mortal Kombat of Software Development

\end{itemstep}
\end{slide}
}


% ============================================================================

\tsectionandpart{Using Subversion}


\overlays{3}{
\begin{slide}{Creating a repository}
\begin{itemstep}[stype=2]

\item Creating the repository itself is easy: \\
{\tt svnadmin create /home/svn/repos}

\vspace*{.5cm}
\item If the repository should be accessable thru HTTP/WebDAV (http://), you
need to configure your apache to load the Subversion module and set it up.

\vspace*{.5cm}
\item If the repository should be accessable thru the Subversion
protocol (svn://), you need to set up the Subversion server {\tt svnserve}.

\end{itemstep}
\end{slide}
}


\overlays{4}{
\begin{slide}{Creating a working copy}
\begin{itemstep}[stype=2]

\item Using the tool {\tt svn} is very simmilar to using {\tt cvs}.

\vspace*{.5cm}
\item A Working copy can be created with: \\
{\tt svn co file:///home/svn/repos localdir} \\
{\tt cd localdir}

\vspace*{.5cm}
\item Note that no equivalent to \$CVSROOT exists.

\vspace*{.5cm}
\item Within the working copy, every directory has a {\tt .svn} subdirectory
containing the Subversion metadata.

\end{itemstep}
\end{slide}
}


\overlays{3}{
\begin{slide}{Making changes (1)}
\begin{itemstep}[stype=2]

\item Modifying files:
\begin{itemize}
\item Just edit them as usual with your favorite editor
\item Note that Subversion is using binary deltas and has
good support for non-ascii files
\end{itemize}

\vspace*{.5cm}
\item Adding files:
\begin{itemize}
\item First create the new file as usual
\item Then execute {\tt svn add {\it filename}}
\end{itemize}

\vspace*{.5cm}
\item Removing files:
\begin{itemize}
\item Just execute {\tt svn rm {\it filename}}
\item The file will automatically removed by {\tt svn}
\end{itemize}

\end{itemstep}
\end{slide}
}


\overlays{3}{
\begin{slide}{Making changes (2)}
\begin{itemstep}[stype=2]

\item Moving/renaming files:
\begin{itemize}
\item Using {\tt svn mv} instead of {\tt mv}
\end{itemize}

\vspace*{.5cm}
\item Copying files:
\begin{itemize}
\item Using {\tt svn cp} instead of {\tt cp}
\end{itemize}

\vspace*{.5cm}
\item Making changes without a working copy:
\begin{itemize}
\item Most operations can also be performed directly on the repository:
\item {\tt svn copy -m "Commit message" $\backslash$} \\
\hspace*{1.5cm} {\tt file:///home/svn/repos/demo2.txt $\backslash$} \\
\hspace*{1.5cm} {\tt file:///home/svn/repos/demo3.txt}
\end{itemize}

\end{itemstep}
\end{slide}
}


\overlays{3}{
\begin{slide}{Committing changes}
\begin{itemstep}[stype=2]

\item Commiting changes made in the working copy: \\
{\tt svn commit}

\vspace*{.5cm}
\item Listing status (modified, etc) of files in working copy: \\
{\tt svn status}

\vspace*{.5cm}
\item Bringing changes from the repository into the working copy: \\
{\tt svn up}

\end{itemstep}
\end{slide}
}


\overlays{5}{
\begin{slide}{Branches and tags}
\begin{itemstep}[stype=2]

\item Subversion has no explicit support for branching.
\item But it has support for copying directories in O(1).

\vspace*{.4cm}
\item Creating a branch is just the same as creating a copy: \\
{\tt svn copy -m "Creating branch dummy" $\backslash$} \\
\hspace*{1.5cm} {\tt file:///home/svn/repos/trunk $\backslash$} \\
\hspace*{1.5cm} {\tt file:///home/svn/repos/branches/dummy}

\vspace*{.4cm}
\item Merging changes from somewhere else to working copy: \\
\vspace*{.2cm}
{\tt svn merge -r70:86 $\backslash$} \\
\hspace*{1cm} {\tt file:///svn/repos/branch/testing .} \\
\vspace*{.2cm}
{\tt svn merge file:///svn/repos/branch/stable $\backslash$} \\
\hspace*{1cm} {\tt file:///svn/repos/branch/testing .}

\vspace*{.4cm}
\item A ``tagged version'' is also just a copy. It just never gets modified.

\end{itemstep}
\end{slide}
}


\overlays{2}{
\begin{slide}{Getting Help (1)}
\begin{itemstep}[stype=2]

\item The command {\tt svn help} lists all subcommands for {\tt svn}: \\
{\tt 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)}

\vspace*{.5cm}
\item The command {\tt svn help {\it subcommand}} gives a detailed description

\end{itemstep}
\end{slide}
}


\overlays{3}{
\begin{slide}{Getting Help (2)}
\begin{itemstep}[stype=2]

\item The command {\tt svnadmin help} does it for {\tt svnadmin}: \\
{\tt create, deltify, dump, help (?, h), hotcopy, list-dblogs, list-unused-dblogs, load, lstxns, recover, rmtxns, setlog, verify}

\vspace*{.5cm}
\item The command {\tt svnadmin help {\it subcommand}} gives a detailed
description

\vspace*{.5cm}
\item The Subversion Handbook is a great Subversion tutorial: \\
http://svnbook.red-bean.com/

\end{itemstep}
\end{slide}
}


% ============================================================================

\tsectionandpart{The SubMaster Client}


\overlays{3}{
\begin{slide}{Overview}
\begin{itemstep}[stype=2]

\item The SubMaster client {\tt sm} is a simple perl script which automates
the creation and management of local Subversion repositories

\vspace*{.5cm}
\item The SubMaster client also automates the creation of patches and
sending them upstream to the SubMaster server

\vspace*{.5cm}
\item A detailed help message explaining all subcommands to {\tt sm} is
printed out by {\tt sm help}

\end{itemstep}
\end{slide}
}


\overlays{4}{
\begin{slide}{Creating a local tree}
\begin{itemstep}[stype=2]

\item Create a local copy of the master repository: \\
{\tt sm create svn://example.org/demo/trunk demo}

\vspace*{.5cm}
\item This creates two directories:
\begin{itemize}
\item {\tt demo}    \hspace*{.9cm} The local working copy
\item {\tt demo.sm} \hspace*{.3cm} Local repository and other sm data
\end{itemize}

\vspace*{.5cm}
\item Create an account at the SubMaster Server: \\
{\tt w3m https://example.org/demo/submaster}

\vspace*{.5cm}
\item Add your SubMaster Login information to your SM tree: \\
\begin{tt}
vi demo.sm/SM/server.txt \\
\hspace*{0.5cm} https://example.org/demo/submaster \\
\hspace*{0.5cm} <username> \\ \hspace*{0.5cm} <password>
\end{tt}

\end{itemstep}
\end{slide}
}


\overlays{4}{
\begin{slide}{Creating patches (1)}
\begin{itemstep}[stype=2]

\item Make your changes in {\tt demo/} as usual.

\vspace*{.5cm}
\item Use {\tt svn add}, {\tt svn rm} and {\tt svn mv} for adding,
removing and moving files or directories

\vspace*{.5cm}
\item Use {\tt sm commit} instead of {\tt svn commit} to commit your
changes to the local repository

\vspace*{1.0cm}
\item Sometimes an {\tt svn up} is required before {\tt sm commit}
can succeed.

\end{itemstep}
\end{slide}
}


\overlays{3}{
\begin{slide}{Creating patches (2)}
\begin{itemstep}[stype=2]

\item Use {\tt sm queue} to list the pending changes:

\vspace*{.3cm}
\begin{tt}
r44 | root | 2004-01-10 12:10:58 +0100 (Sat,	\\
Added package oprofile.				\\
--------------------------------------------	\\
r51 | root | 2004-01-10 13:34:35 +0100 (Sat,	\\
Oprofile: don't run depmod. 			\\
--------------------------------------------
\end{tt}

\vspace*{.5cm}
\item Use {\tt sm patch} to create a patch from your changes:\\
{\tt sm patch r44 r51}

\vspace*{.5cm}
\item Use {\tt sm send} to send the patch upstream to the SubMaster Server.

\end{itemstep}
\end{slide}
}


\overlays{3}{
\begin{slide}{Syncing with the main tree}
\begin{itemstep}[stype=2]

\item Merging changes from master tree to local tree:
\begin{itemize}
\item {\tt sm sync}
\item manually resolve conflicts, if any
\item patches beeing applied in master do not result in conflicts
\item {\tt svn commit -m "SM Sync 2434:2442"}
\end{itemize}

\vspace*{.5cm}
\item Full-syncing local tree to master:
\begin{itemize}
\item {\tt sm fsync}
\item This will discard all local changes
\end{itemize}

\vspace*{.5cm}
\item Showing differences between local tree and master:
\begin{itemize}
\item {\tt sm diff}
\end{itemize}

\end{itemstep}
\end{slide}
}


\overlays{6}{
\begin{slide}{WIP Archive}
\begin{itemstep}[stype=2]

\item The WIP (work-in-progress) archive can be used to suspend the work
on a changeset and resume it later.

\vspace*{.3cm}
\item Revert in working copy and save as patch in WIP archive: \\
{\tt sm wip push {\it name} r180 r181 r182}

\vspace*{.3cm}
\item Apply patch in working tree and remove from WIP archive: \\
{\tt sm wip pull {\it name}}

\vspace*{.3cm}
\item Move patch from WIP archive to current working directory: \\
{\tt sm wip co {\it name}}

\vspace*{.3cm}
\item Move patch from current working directory to WIP archive: \\
{\tt sm wip ci {\it name}}

\vspace*{.3cm}
\item List patches in WIP archive: {\tt sm wip}

\end{itemstep}
\end{slide}
}


\begin{slide}{Filesystem Layout (1)}
\begin{itemize}

\item {\tt demo/}
\hspace*{2.5cm} The local Subversion working copy

\vspace*{.5cm}
\item {\tt demo.sm/*.patch}
\hspace*{0.4cm} Patches waiting to be send to server

\vspace*{.5cm}
\item {\tt demo.sm/SENT/}
\hspace*{0.8cm} Patches already sent to server

\vspace*{.5cm}
\item {\tt demo.sm/WIP/}
\hspace*{1.0cm} Archive of work-in-progres patches

\vspace*{.5cm}
\item {\tt demo.sm/MASTER/}
\hspace*{0.4cm} Exported up-to-date master tree

\vspace*{.5cm}
\item {\tt demo.sm/SVN/}
\hspace*{1.0cm} Local Subversion Repository (DB)

\end{itemize}
\end{slide}


\begin{slide}{Filesystem Layout (2)}
\begin{itemize}

\item {\tt demo/SM/master.txt}
\hspace*{0.5cm} URL of main SVN repository

\vspace*{.5cm}
\item {\tt demo/SM/mrev.txt}
\hspace*{0.9cm} Revision currently in MASTER/

\vspace*{.5cm}
\item {\tt demo/SM/queue.txt}
\hspace*{0.7cm} Revisions in the change queue

\vspace*{.5cm}
\item {\tt demo/SM/server.txt}
\hspace*{0.5cm} URL, etc. for SM Server

\vspace*{.5cm}
\item {\tt demo/SM/sync.txt}
\hspace*{0.9cm} Last master rev. synced to local

\end{itemize}
\end{slide}

% ============================================================================

\tsectionandpart{The SubMaster Server}


\overlays{7}{
\begin{slide}{Overview}
\begin{itemstep}[stype=2]

\item Basically a cgi-based relay for patches

\vspace*{.5cm}
\item Everyone can register as user
\item Everyone can upload patches
\item Everyone can vote for/agains and comment patches

\vspace*{.5cm}
\item The tree maintainer can pull patches and apply them to
the master Subversion Repository

\vspace*{.5cm}
\item The tools {\tt sm} and {\tt smap} can communicate directly with
the cgi script, no webbrowser is needed

\vspace*{.5cm}
\item E-mail notifications, etc. can be implemented using action scripts

\end{itemstep}
\end{slide}
}


\overlays{8}{
\begin{slide}{Patch Properties}
\begin{itemstep}[stype=2]

\item A Unique Patch ID (such as "{\tt 2004011020364615018}")

\vspace*{.5cm}
\item The login-name of the user who created the patch
\item Current patch status (open, applied, rejected and discarded)

\vspace*{.5cm}
\item The patch file itself
\item The patch description (header of the patch file)

\vspace*{.5cm}
\item Votes pro and contra the patch

\vspace*{.5cm}
\item Other users (single-line) comments on the patch

\vspace*{.5cm}
\item Auto-created additional info from the action scripts

\end{itemstep}
\end{slide}
}


\begin{slide}{Filesystem Layout (1)}
\begin{itemize}

\item {\tt password/<username>.txt} \\
	encrypted password

\item {\tt password/<username>.super} \\
	if this file exists, the matching user is a superuser

\item {\tt user/<username>.email} \\
	the e-mail address of that user

\item {\tt open/<year>\_<month>\_<id>.open} \\
	empy file which marks a patch as open

\end{itemize}
\end{slide}


\begin{slide}{Filesystem Layout (2)}
\begin{itemize}

\item {\tt data/<year>/<month>/<id>.patch} \\
	the patch file as originally sent by the user

\item {\tt data/<year>/<month>/<id>.msg} \\
	messages attached to the patch

\item {\tt data/<year>/<month>/<id>.votes} \\
	votes by different users

\item {\tt data/<year>/<month>/<id>.owner} \\
	this patches owner

\item {\tt data/<year>/<month>/<id>.info} \\
	auto-created additional info

\item {\tt data/<year>/<month>/<id>.done} \\
	eighter "Applied" or "Rejected"
	does not exist for open patches

\end{itemize}
\end{slide}

% ============================================================================

\tsectionandpart{The smap helper script}

\overlays{5}{
\begin{slide}{Overview}
\begin{itemstep}[stype=2]

\item Helps applying patches from the SM Server
\begin{itemize}
\item Download patch from server
\item Check if it applies cleanly
\item Apply the patch to the current directory
\item Run {\tt svn add} and {\tt svn rm} commands
\item Run {\tt svn commit}
\item Mark patch as applied
\end{itemize}

\vspace*{.5cm}
\item E.g. for maintaining the official tree
\item E.g. for testing or extending patches

\vspace*{.5cm}
\item Sometimes called by {\tt sm}

\vspace*{.5cm}
\item Usage: {\tt smap [options] <patch-id>}

\end{itemstep}
\end{slide}
}


\begin{slide}{Options}
\begin{itemize}

\item -pN -l -R  \hspace*{.3cm}  pass this option to the patch program
\item -d         \hspace*{1.3cm} just make a dry-run
\vspace*{.5cm}
\item -S    \hspace*{1.3cm} don't commit to svn (e.g. if this isn't a svn tree)
\item -E    \hspace*{1.3cm} edit commit message before running svn commit
\item -D    \hspace*{1.3cm} don't remove temp files after success
\vspace*{.5cm}
\item -a file  \hspace*{.8cm}   add this smap command to file after success
\item -A       \hspace*{1.3cm}  don't apply anything, just do -a
\vspace*{.5cm}
\item -M       \hspace*{1.30cm}  mark patch as applied on SM Server
\item -C       \hspace*{1.35cm}  do nothing if already marked as applied

\end{itemize}
\end{slide}


\overlays{3}{
\begin{slide}{Configuration}
\begin{itemstep}[stype=2]

\item If this is a SubMaster tree, read config from the SM config.
\vspace*{.7cm}
\item Otherwise read server URL, Username and Password from {\tt ./smap.cfg}.
\vspace*{.7cm}
\item It's also possible modify the parameter list in {\tt ./smap.cfg}:
\vspace*{.5cm}
\begin{tt}
set -- -M -I "\$@"\\
URL="https://www.rocklinux.net/submaster"\\
USER="admin-username"\\
PASS="admin-password"
\end{tt}

\end{itemstep}
\end{slide}
}

\overlays{6}{
\begin{slide}{Fixdiff}
\begin{itemstep}[stype=2]

\item Can be used to create patches for patches (e.g. so they apply cleanly)

\vspace*{.7cm}
\item {\tt smap 2004040509423327913} \hspace*{1cm} (this fails)
\vspace*{.5cm}
\item {\tt fixdiff 2004040509423327913.patch co package/base/linux24/lx{\_}config.sh}
\vspace*{.5cm}
\item Merge {\tt package/base/linux24/lx{\_}config.sh.rej}
\vspace*{.5cm}
\item {\tt fixdiff 2004040509423327913.patch ci package/base/linux24/lx{\_}config.sh}

\vspace*{.7cm}
\item {\tt --> fixdiff{\_}2004040509423327913.patch}

\end{itemstep}
\end{slide}
}

% ============================================================================

\tsectionandpart{SubMaster Action Scripts}


\overlays{6}{
\begin{slide}{Overview}
\begin{itemstep}[stype=2]

\item Action scripts are called whenever the status of a patch changes

\vspace*{.5cm}
\item This can be used to send notify mails
\item .. to check who should review the patch
\item .. to eventually run any regression test on the patch

\vspace*{.5cm}
\item The action scripts can be written in any language

\vspace*{.5cm}
\item The action script for the ROCK SM is written in shell

\end{itemstep}
\end{slide}
}


\begin{slide}{Calling Convention}
\begin{itemize}

\item {\tt ./action.sh {\it id} {\it user} new}
\item {\tt ./action.sh {\it id} {\it user} msg '{\it Message Text}'}
\vspace*{.5cm}
\item {\tt ./action.sh {\it id} {\it user} vote contra}
\item {\tt ./action.sh {\it id} {\it user} vote pro}
\item {\tt ./action.sh {\it id} {\it user} vote delete}
\vspace*{.5cm}
\item {\tt ./action.sh {\it id} {\it user} status rejected}
\item {\tt ./action.sh {\it id} {\it user} status applied}
\item {\tt ./action.sh {\it id} {\it user} status opened}
\item {\tt ./action.sh {\it id} {\it user} status discarded}

\end{itemize}
\end{slide}

% ============================================================================

\tsectionandpart{URLs and References}


\begin{slide}{Subversion and SubMaster}
\begin{itemize}

\item The Subversion Handbook: \\
http://svnbook.red-bean.com/
\vspace*{.5cm}

\item The Subversion Homepage: \\
http://subversion.tigris.org/
\vspace*{.5cm}

\item The SubMaster Homepage: \\
http://www.rocklinux.org/submaster.html
\vspace*{.5cm}

\end{itemize}
\end{slide}


\begin{slide}{Related Projects}
\begin{itemize}

\item SVK: A decentralized system based on Subversion \\
%% http://svk.elixus.org/
\vspace*{.5cm}

\item Transvn: A patch-scripts clone based on Subversion \\
http://alexm.here.ru/transvn/
\vspace*{.5cm}

\item SVM: Mirror Remote Subversion Repository to local \\
http://search.cpan.org/~clkao/SVN-Mirror/
\vspace*{.5cm}

\end{itemize}
\end{slide}


\begin{slide}{Credits}
\begin{itemize}

\item LINBIT Information Technologies GmbH: \\
http://www.linbit.com/
\vspace*{.5cm}

\item The ROCK Linux Project: \\
http://www.rocklinux.org/
\vspace*{.5cm}

\item Clifford Wolf: \\
http://www.clifford.at/
\vspace*{.5cm}

\end{itemize}

\vspace*{1.5cm}\hspace*{2cm}
http://www.rocklinux.org/submaster.html

\end{slide}

% ============================================================================

\end{document}