DEP-5: point to the policy version, now stable
[packaging-tutorial.git] / packaging-tutorial.tex
index 072cc32..fe32493 100644 (file)
@@ -16,7 +16,7 @@
 %leave \\version unchanged: this will a variable containing the actual version
 %To translate the date, use \\today or a string containing \\year, \\month, \\day
 %(numeric values).
-\date{\footnotesize version 0.5 -- 2011-11-29} % DATE - use debian/rules update-version-date
+\date{\footnotesize version 0.6 -- 2012-04-09} % DATE - use debian/rules update-version-date
 
 \begin{document}
 
@@ -42,7 +42,7 @@
     \item You will need to read more documentation
     \end{itemize}
     \br
-  \item Most of the content also applies to Debian derivatives distributions
+  \item Most of the content also applies to Debian derivative distributions
     \begin{itemize}
       \hbr
     \item That includes Ubuntu
@@ -89,7 +89,7 @@
        \br
 \item A very powerful and convenient way to distribute software to users
        \br
-\item One of the two most common packages format (with RPM)
+\item One of the two most common package formats (with RPM)
        \br
 \item Universal:
        \begin{itemize}
@@ -98,7 +98,7 @@
                        \hbr
                \item For 12 ports (architectures), including 2 non-Linux (Hurd; KFreeBSD)
                        \hbr
-               \item Also used by 120 Debian derivatives distributions
+               \item Also used by 120 Debian derivative distributions
        \end{itemize}
 \end{itemize}
 \end{frame}
@@ -201,7 +201,7 @@ rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
   {\small (This needs you to have \texttt{deb-src} lines in your \texttt{/etc/apt/sources.list})}
   \hbr
 \item Build the package\\
-  {\texttt{cd dash-*\\ debuild -us -uc}}
+  {\texttt{cd dash-*\\ debuild -us -uc}} ~~~(\texttt{-us -uc} disables signing the package with GPG)
 
   \hbr
 \item Check that it worked
@@ -368,7 +368,10 @@ Files:
 
 
          %%
-  \item Edited manually or with \texttt{dch}
+  \item Edited manually or with \textttc{dch}
+  \begin{itemize}
+         \item Create a changelog entry for a new release: \textttc{dch -i}
+  \end{itemize}
   \item Special format to automatically close Debian or Ubuntu bugs\\
     Debian: \texttt{Closes:~\#595268}; Ubuntu: \texttt{LP:~\#616929}
   \item Installed as \texttt{/usr/share/doc/\textit{package}/changelog.Debian.gz}
@@ -455,7 +458,7 @@ Description: retrieves files from the web
   \item Interface used to build Debian packages
     \br
   \item Documented in Debian Policy, chapter 4.8\\
-    {\small \texttt{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
+    {\small \url{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
     \br
   \item Five required targets:
     \begin{itemize}
@@ -668,7 +671,8 @@ override_dh_auto_build:
 \begin{frame}{Building packages}
   \begin{itemize}
   \item \textttc{apt-get build-dep mypackage}\\
-    Installs the \textsl{build-dependencies} (for a package in the archive)
+    Installs the \textsl{build-dependencies} (for a package already in Debian)\\
+    Or \textttc{mk-build-deps -ir} (inside the package source tree)
     
     \br
   \item \textttc{debuild}: build, test with \texttt{lintian}, sign with GPG
@@ -721,6 +725,10 @@ override_dh_auto_build:
   \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
     download version 2.6.3-3 of the package (if you use Ubuntu 11.10 or
     later, or Debian testing or unstable, use version 2.9-1 or 2.9-2 instead)
+    \begin{itemize}
+                  \item If the source package is not unpacked automatically, unpack it with
+                          \texttt{dpkg-source~-x~grep\_*.dsc}
+    \end{itemize}
 
   \item Look at the files in \texttt{debian/}.
     \begin{itemize}
@@ -751,11 +759,12 @@ override_dh_auto_build:
   \begin{itemize}
   \item Copyright and license information for the source and the packaging
   \item Traditionally written as a text file
-  \item New machine-readable format: \url{http://dep.debian.net/deps/dep5/}
+  \item New machine-readable format:
+    {\small\url{http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/}}
   \end{itemize}
   \seprule
-  \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
-Format: <VERSIONED_FORMAT_URL>
+  \begin{lstlisting}[basicstyle=\ttfamily\scriptsize]
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: X Solitaire
 Source: ftp://ftp.example.com/pub/games
 
@@ -915,8 +924,8 @@ http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
   \end{itemize}
 \end{frame}
 
-\subsection{Packaging with a VCS (SVN, Git \& friends)}
-\begin{frame}[fragile]{Packaging with a VCS (SVN, Git, etc.)}
+\subsection{Packaging with a Version Control System (SVN, Git)}
+\begin{frame}[fragile]{Packaging with a Version Control System}
   \begin{itemize}
   \item Several tools to help manage branches and tags for your packaging work:\\
     \texttt{svn-buildpackage}, \texttt{git-buildpackage}
@@ -1045,6 +1054,32 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
   \end{itemize}
 \end{frame}
 
+\begin{frame}[fragile]{Adopting a package: example}
+\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
+From: You <you@yourdomain>
+To: 640454@bugs.debian.org, control@bugs.debian.org
+Cc: Francois Marier <francois@debian.org>
+Subject: ITA: verbiste -- French conjugator
+
+retitle 640454 \textbf{ITA}: verbiste -- French conjugator
+owner 640454 !
+thanks
+
+Hi,
+
+I am using verbiste and I am willing to take care of the package.
+
+Cheers,
+
+You
+\end{lstlisting}
+
+\begin{itemize}
+\item Polite to contact the previous maintainer (especially if the package was RFAed, not orphaned)
+\item Very good idea to contact the upstream project
+\end{itemize}
+\end{frame}
+
 \subsection{Getting your package in Debian}
 \begin{frame}{Getting your package in Debian}
 \begin{itemize}
@@ -1346,7 +1381,7 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
        \item Use dget to download the \texttt{.dsc} file:\\
                {\small \texttt{dget http://cdn.debian.net/debian/pool/main/g/grep/grep\_2.6.3-3.dsc}}
                \hbr
-       \item According to \texttt{http://packages.qa.debian.org/grep}, \texttt{grep} version 2.6.3-3 is currently in \textsl{stable} (\textsl{squeeze}). If you have \texttt{deb-src} lines for \textsl{squeeze} in your \texttt{/etc/apt/sources.list}, you can use:\\
+       \item According to \url{http://packages.qa.debian.org/grep}, \texttt{grep} version 2.6.3-3 is currently in \textsl{stable} (\textsl{squeeze}). If you have \texttt{deb-src} lines for \textsl{squeeze} in your \texttt{/etc/apt/sources.list}, you can use:\\
                \texttt{apt-get source grep=2.6.3-3}\\
                or \texttt{apt-get source grep/stable}\\
                or, if you feel lucky: \texttt{apt-get source grep}
@@ -1606,6 +1641,7 @@ $\rightarrow$ Add \textbf{libsdl1.2-dev} to Build-Depends and install it.
 \end{itemize}
 \end{frame}
 
+\subsection{Practical session 4: packaging a Ruby gem}
 \begin{frame}{Practical session 4: packaging a Ruby gem}
 \begin{enumerate}
        \item Take a quick look at some documentation about Ruby packaging:\\