\documentclass[10pt,a4paper]{article}

 \usepackage[latin1]{inputenc}        % Keybord settings
 \usepackage{fancyhdr}                % Headings
 \usepackage{hyperref}                % Hyperlinks
 \usepackage{longtable}               % tables with page brake
 \usepackage{afterpage}
 
 % Math-Options:
 % -------------
 \usepackage{amsmath}                 % Additional math functionality
 \usepackage{amssymb}                 % Additional math functionality
 \usepackage{amstext}                 % Additional math functionality

 % Algorithms:
 % -----------
 \usepackage{algorithmic}
 \usepackage{algorithm}
 
 % Code formatting
 % -----------
 \usepackage{color}
 \usepackage{listings}
 \lstset{ %
  language=Bash,                % choose the language of the code
  basicstyle=\footnotesize,       % the size of the fonts that are used for the code
  numbers=left,                   % where to put the line-numbers
  numberstyle=\footnotesize,      % the size of the fonts that are used for the line-numbers
  stepnumber=1,                   % the step between two line-numbers. If it is 1 each line will be numbered
  numbersep=5pt,                  % how far the line-numbers are from the code
  backgroundcolor=\color{white},  % choose the background color. You must add \usepackage{color}
  showspaces=false,               % show spaces adding particular underscores
  showstringspaces=false,         % underline spaces within strings
  showtabs=false,                 % show tabs within strings adding particular underscores
  frame=single,                   % adds a frame around the code
  tabsize=2,              % sets default tabsize to 2 spaces
  captionpos=b,                   % sets the caption-position to bottom
  breaklines=true,        % sets automatic line breaking
  breakatwhitespace=false,    % sets if automatic breaks should only happen at whitespace
  escapeinside={\%}{)}          % if you want to add a comment within your code
 }

 \usepackage{url}

 % Figures:
 % --------
 \usepackage{graphicx}                % EPS figures
 \usepackage[dvips]{epsfig}           % EPS figures
 \usepackage{epsfig}                  % EPS figures
 \usepackage{color}                   % Allow color
 \usepackage{float}                   % Placement of floating objects
 \usepackage{subfigure}               % subfigures

 \title{Orxonox PPS HowTo}
 \author{Damian Frick}
 \date{\today}

\begin{document}
\maketitle
\begin{center}
\text{Rev 2: Benjamin de Capitani, June 2012}
\text{Rev 3: Patrick Wintermeyer, March 2017}
\end{center}
\tableofcontents 
\newpage

\section{Introduction}
\paragraph*{}
This is the HowTo to the Orxonox PPS. It (hopefully) contains everything you need to know to successfully organize the Orxonox PPS.
\paragraph*{}
This document is structured in the order that things are best approached, beginning with what to do before the PPS actually starts, with tasks ranging from reserving rooms, to hiring the teaching assistants. After that there are some tips for the PPS itself. Then we deal with the inevitable presentation and finally we wrap things up. 

\section{Preparation before the PPS}
In preparation of the Orxonox PPS there are  several things that need to be done.

\paragraph{Choose a week day to hold the PPS}
In the fall semester PPS this normally is Wednesday (for $2^{\text{nd}}$ year students), in the spring semester it's Monday (for $1^{\text{st}}$ year students) and Thursday (for $2^{\text{nd}}$ year students).
\paragraph{Reserve the rooms}
Rooms will be needed, to hold the introduction and to later hold the PPS. The rooms for the introduction can be reserved through the \href{http://www.vision.ee.ethz.ch/}{BIWI} by contacting \href{http://www.vision.ee.ethz.ch/members/get_member.cgi?lang=en&id=152}{Christina Krueger} (\href{mailto:ckrueger@vision.ee.ethz.ch}{ckrueger@vision.ee.ethz.ch}), commonly we used the ETZ D96.1 room for the introduction. Alternatively, you can reserve a room yourself here: \url{http://www.rektorat.ethz.ch/depts/rooms/raumanfrage/index}; to do so, you must provide the lecture number for PPS in general (227-0080-00L or 227-0085-00L). Reservations can be checked through \url{http://www.rauminfo.ethz.ch}. The computer room (commonly ETZ D96.1 or ETZ D61.2) can be reserved through the following web interface \url{https://roomreservations.ee.ethz.ch/}. Be sure to do this sufficiently early.
\paragraph{Employ new assistants}
After having found a new assistant he (or she) is going to have to get some additional access privileges.
\begin{itemize}
\item{Create a new orxonox mail account. To that end you have to log on to the Orxonox server (see \ref{login}) and do the following:
\begin{lstlisting}
# become root
sudo su
# create the user and create home-dir
useradd -m username
# set the password for the user
passwd username
# now create the maildir directory for the new user
cd /home/username
mkdir .maildir
chown username:users .maildir
chmod 700 .maildir
\end{lstlisting}
Now send an email to this new account so that the postfix server creates and initializes all sub-directories automatically. 
}
\item Moderator privileges in \url{http://forum.orxonox.net}, open the Administration Control Panel (see \ref{forum-admin}) And then add the new assistant to the PPS-Leaders group.
\item Privileges for trac. You have to login to the trac administration interface (see \ref{trac-admin}) and add the new assistant to the "ppsleader" group.
\end{itemize}
\paragraph{Create a new mailing list}
Create a new mailing list for the PPS. The administrations interface can be found here: \url{https://admin.orxonox.net/mailman/admin}. The site-wide password is \texttt{go4orxonox}. Also add the new mailinglist to the Orxonox-pps list, by going into its non-digest options menu and adding your mailinglist to the included lists. The Orxonox-pps list is an umbrella list for all pps lists. If a mail is sent to that list it will go to each subscriber of each pps list.
\paragraph{Create tickets for the students}
Create new tickets and revise old ones in the PPS report (\url{http://www.orxonox.net/report/11}).
\paragraph{Update the PPS website}
Update \url{http://www.orxonox.net/wiki/PPS_main}, move the old timetable and projects to the \href{http://www.orxonox.net/wiki/PPS_archive}{PPS Archive} and make an announcement on the main site.
\paragraph{Plan the Introduction}
The topics and slides of previous PPS semesters can be found in the \href{http://www.orxonox.net/wiki/PPS_archive}{PPS Archive}. Commonly they were:
\begin{itemize}
\item Introduction (History, Overview)
\item Licensing
\item SVN
\item Blender with tutorial
\item Website and Trac
\item Framework and coding tutorial
\item Level design tutorial
\end{itemize}
\paragraph{Procure funding for the pizza sessions}
Make sure we get a budget for the pizza sessions at the AMIV GV. The Orxonox Pizza-Session should be part of the normal budget, but you best check whether it is included and complain beforehand if it isn't. Update 2017: At this point we are no longer supported by the AMIV and do not receive a budget. Maybe this can be changed in the future.

\section{During the PPS}
\paragraph{New students}
\begin{itemize}
\item Add them to the mailing list, send a welcome mail to the mailing list, introducing Orxonox and relaying the rough timetable and rooms.
\item{Create a svn user for each of them, login on to the orxonox server (\ref{login}), changing into \texttt{/var/svn}, and executing as root:
\begin{lstlisting}
cat svnusers | grep username
\end{lstlisting}
To check, whether the username is taken, and then (with superuser privileges):
\begin{lstlisting}
htpasswd -m ./svnusers username
\end{lstlisting}
Upon which the student can enter his desired password.\\
Also each user needs to be added to the orx-pps group in the \texttt{svnaccess} file.
}
\item Add them to the developers group in trac. (Under \texttt{Permissions} in the trac administration interface \ref{trac-admin})
\item Write to \href{mailto:support@ee.ethz.ch}{support@ee.ethz.ch}, to ask for orxonox extra-home access for all students and assistants. Mention who the assistants are (they like to know).
\end{itemize}
\paragraph{Make new Branches for new Projects}
For every project a new branch should be made that will be merged into the trunk at the end of the semester. Usually, the branch should be copied from the trunk:
\begin{lstlisting}
svn copy https://svn.orxonox.net/game/code/trunk https://svn.orxonox.net/game/code/branches/<new-branch-name>
\end{lstlisting}
\paragraph{Trouble with the Server}
Restart it yourself by loging on (\ref{login}) and execute
\begin{lstlisting}
sudo reboot 0
\end{lstlisting}
or if you can't log on, write to \href{mailto:it@vseth.ethz.ch}{it@vseth.ethz.ch} to have it restarted.
\paragraph{Reviews}
Schedule 2-3 reviews during the semester, where each student, very briefly, presents what he has done so far and what he is currently working on, to the other students.
\paragraph{Pizza session}
Towards the end of the semester if the students need some more time to work on their projects a pizza session can be held, where everyone (who wants to) can stay late and in the course of which we all eat some pizza. The AMIV gets its pizzas from \url{http://monterigi.ch/}, you'll get a discount if you mention you're from the AMIV when ordering. $\frac{1}{2}$ to $\frac{2}{3}$ large pizzas per person have proven to be sufficient. Be sure to keep the receipts and give them to the AMIV Qu\"astor to be reimbursed. Update 2017: This has not been done in a couple of years, due to the lack of support from the AMIV. Instead pizza was organized after the presentation and paid by the assistants.

\section{The Presentation}
The presentation is the last instance of the PPS, be sure to make the students aware of it's existence beforehand and schedule a date and reserve rooms sufficiently early.

\subsection{Information}
Send a mail to the announce mailinglist, add a news item on the main page on our website and add a tweet (best via identi.ca) (\ref{identica}).

\paragraph{Massmail}
Send a Massmail to all ITET students inviting them to the presentation. Send a mail with the message both in german and english to the \href{mailto:support@ee.ethz.ch}{support@ee.ethz.ch} to have it distributed.

\paragraph{Invite our benefactors}
Invite Prof. Sz\'{e}kely (\href{mailto:szekely@vision.ee.ethz.ch}{szekely@vision.ee.ethz.ch})  and Jonas Spillmann (\href{mailto:jonas.spillmann@vision.ee.ethz.ch}{jonas.spillmann@vision.ee.ethz.ch}) to the presentation. Update 2017: Jonas Spillmann makes no longer part of the institute and is no longer reachable under the eth-e-mail-address.

\subsection{Slides}
Create new slides or adapt the old ones. The slides of previous conventions can be found in the webdev \url{http://svn.orxonox.net/webdev/conventions/} be sure to add a folder for the new convention and add your slides there.

\subsection{Poster}
Create, print and distribute a poster inviting to come see our presentation. The posters can be printed via the widely known \href{http://idvpp01.ethz.ch/vpppdf.html}{vpn pdf webinterface} on the color printer (X7760) at ETZSPEZ. 20 posters have proven to be sufficient. Locations where the posters can/should be placed are:
\begin{itemize}
	\item Various boards in the ETZ building
	\item Boards at the entrance in the ETF and in front of the lecture halls ETF C1 and ETF E1
	\item In the CAB
	\item Some places in the HG
	\item ML
	\item One at the AMIV
\end{itemize}

\section{Aftermath}
\subsection{Say thanks}
Say thanks to Prof. Sz\'{e}kely and Jonas Spillmann for their support and give them a short progress and status report.
\subsection{Merging}
Merge the students' branches into the trunk, if their project was successful and useful for the game. Check out \ref{merging} for a technical and step-by-step description.
\subsection{Delete extra-homes}
Once the merging is finished and the trunk is up to date, write a mail to \href{mailto:support@ee.ethz.ch}{support@ee.ethz.ch} to tell them that the semester is over and the extra-homes can be deleted. Make sure to thank them for their effort.
\subsection{Passing on the torch}
After a suitable replacement has been found, he (or she) needs to get some additional privileges (and this .pdf).
\paragraph{Access and root privileges on the Orxonox Server}
The successor needs to have admin access via ssh and a RSA private/public key pair. Proceed as follows:\\
Login to the Orxonox server (see \ref{login}). Add the successor with 
\begin{lstlisting}
sudo adduser <username>
\end{lstlisting} Generate the key in the successor's \texttt{/.ssh} folder with 
\begin{lstlisting}
ssh-keygen
\end{lstlisting}Send the public key to the predecessor by mail and save the public key to the \texttt{<username>/.ssh/authorized\_keys} file of the user on the Orxonox-server. Add the user to the \texttt{wheel} group in \texttt{/etc/group} (for sudo privileges) and to the \texttt{sudoers} group.
\paragraph{Privileges on trac}
Also admin access to trac is needed. Which can be done through the trac administration interface (see \ref{trac-admin}), and permissions. The user has to be added to the "ppsleader" group.
\paragraph{Privileges in the forum}
Go to the administration control panel (see \ref{forum-admin}) and add the user to the "Administrators" group.
\paragraph{Mailinglist}
The successor needs to be added to the contact@orxonox.net mailinglist as a list administrator.
\paragraph{Introduce the successor}
Tell Doris D\"{o}beli (\href{mailto:ddoebeli@ee.ethz.ch}{ddoebeli@ee.ethz.ch}), Christina Krueger (\href{mailto:ckrueger@vision.ee.ethz.ch}{ckrueger@vision.ee.ethz.ch}) and Prof. Sz\'{e}kely (\href{mailto:szekely@vision.ee.ethz.ch}{szekely@vision.ee.ethz.ch}) about the new PPS leader.

\section{Orxonox Events}
Normally there are two special Orxonox events per year.

\subsection{Orxonox Fondue}
Somewhere in the fall semester there usually is a Fondue event with PPS students and other Orxonox-enthusiasts.

\subsection{Orxonox Grillparty}
At the end of the spring semester there is the Orxonox Grillparty, be sure to invite both the current pps students as well as the veterans. The Irchel park has proven to be a nice place to host such an event. \\

Update 2017: This has not be done in years.

\section{Appendix}

\subsection{Login on the Orxonox Server} \label{login}
Login on to the orxonox server is fairly straight forward. Open a terminal and type:
\begin{lstlisting}
ssh username@orxonox.net
\end{lstlisting}

\subsection{Merging} \label{merging}
After the semester is over, the new projects have to be merged into the trunk. Please proceed as follows: \\
\textbf{Preparation:} 
\begin{itemize}
\item Go into the \texttt{itet-stor} and choose one of the branches you would like to merge first.
\item Download the trunk into a new folder using
\begin{lstlisting}
svn checkout https://svn.orxonox.net/game/code/trunk
\end{lstlisting}
and create a new build folder. 
\item Proceed as if you were downloading the game normally, i.e. \texttt{cmake}, \texttt{make -j4} etc.
\item Test if the game is actually running.
\end{itemize}
\textbf{Merging:}
\begin{itemize}
\item To merge use (when being in \texttt{trunk} folder): 
\begin{lstlisting}
svn merge https://svn.orxonox.net/game/code/<projectname>
\end{lstlisting}
\item To check, whether the students have only made useful changes (and deleted all their commented sections) use:
\begin{lstlisting}
svn diff <filename>
\end{lstlisting}
\item If you do not want to keep a certain file or a certain change use:
\begin{lstlisting}
svn revert <filename>
\end{lstlisting}
\item Compile and test the most recent changes.
\item If it's working like a charm \texttt{commit} and \texttt{update} and start all over again for all the other branches.
\end{itemize}

\subsection{The Trac Administration Interface} \label{trac-admin}
You have to log in to track and then klick on the rightmost item in the trac navigation, which is called "Admin".

\subsection{The Forum Administration Interface} \label{forum-admin}
The administration interface for the forum can be found via the "Administration Control Panel" link at the bottom of the forum website.

\subsection{Twitter}
Username: \texttt{Orxonox}, password: \texttt{go4orxtweets}

\subsection{Identi.ca} \label{identica}
Username: \texttt{Orxonox}, password: \texttt{go4orxidentica}

\subsection{YouTube}
Username: \texttt{Orxonox}, password: \texttt{go4orxvids}

\bibliographystyle{plain}
\bibliography{references}

\end{document}
