% Copyright (C) 2010  Tim Retout <diocles@debian.org>
%
% Copying and distribution of this file, with or without modification,
% are permitted in any medium without royalty provided the copyright
% notice and this notice are preserved.  This file is offered as-is,
% without any warranty.

\documentclass{beamer}

\usepackage{hyperref}

\newcommand{\email}[1]
{$<$\href{mailto:#1}{\nolinkurl{#1}}$>$}

\title[pkg-perl for users]{Getting Perl modules into Debian}
\subtitle{Debian's Perl team from an end-user perspective}
\author{Tim Retout}
\date{11th September 2010\\HantsLUG @ IBM Hursley}

\pgfdeclareimage[height=2cm]{debian-logo}{debian-swirl}
\logo{\pgfuseimage{debian-logo}}

\usetheme{Warsaw}
%\usecolortheme{crane}

\beamertemplatenavigationsymbolsempty

\begin{document}

\frame{\titlepage}

\frame
{
  \frametitle{What is the Debian Perl team?}

  \begin{itemize}
    \item Maintain about 2000 Perl packages within Debian
    \item Both official Debian Developers and sponsees
    \item Around 70-80 committers,\footnote{\url{http://www.ohloh.net/p/pkg-perl}} but most activity from a small core team
    \item Also indirectly contributes most of the Perl packages in
      Debian's derivatives (e.g. Ubuntu).
  \end{itemize}


}

\frame
{
  \frametitle{Using Perl on Debian}

  How do you install Perl modules?

  \begin{itemize}
    \item {\tt apt-get install libfoo-perl}
    \item Backports for older releases
    \item CPAN for unpackaged modules
  \end{itemize}

  CPAN (the tool) is configured to play nicely with Debian packages,
  but does not install packages when satisfying dependencies.
}

\frame
{
  \frametitle{When a module isn't packaged}

  If the Perl module you need is not available, you have several options:

  \begin{enumerate}
    \item Install it with CPAN, and handle future upgrades yourself.
    \item File an RFP (Request for package) bug in Debian.\footnote{\url{http://pkg-perl.alioth.debian.org/howto/RFP.html}}
    \item Build yourself a private Debian package with dh-make-perl, and handle future upgrades yourself.
    \item Get involved and contribute it back to Debian!
  \end{enumerate}

  Getting involved is easier than you think.
}

\frame
{
  \frametitle{Getting involved - tools}

  The Perl team uses tools to speed up packaging.

  \begin{itemize}
    \item alioth.debian.org for team management
    \item git for most packages
    \item \url{http://bugs.debian.org/}
    \item Package Entropy Tracker (PET)
    \item IRC (\#debian-perl on OFTC)
    \item Two mailing lists - one for discussion, one to receive
      automated messages
  \end{itemize}

  \url{http://pkg-perl.alioth.debian.org/} links to all of these.
}

\frame
{
  \frametitle{Getting involved - joining the team}
  \begin{itemize}
    \item Create an alioth account
    \item Apply to join the pkg-perl group on alioth
    \item Introduce yourself on the debian-perl mailing list
    \item Optionally use IRC for realtime communication
  \end{itemize}

  \url{http://wiki.debian.org/Teams/DebianPerlGroup/Welcome}
}

\frame
{
  \frametitle{Creating a package - dh-make-perl}

  dh-make-perl can jump-start creating a new Perl package.

  \begin{itemize}
    \item {\tt apt-get install dh-make-perl} and read the man page.
    \item Run {\tt dh-make-perl --cpan Module::Name}.
    \item Add {\tt --pkg-perl} if you are packaging for the team.
    \item {\tt dh-make-perl} will create a git repository
    \item Then run {\tt debuild} and hack until it builds.
    \item Use {\tt cme check dpkg} or {\tt cme edit dpkg}
          \footnote{install {\tt libconfig-model-tkui-perl} to get cme}
    \item you can commit locally to keep track of your work
  \end{itemize}

  If you don't want to contribute it to Debian, you could stop here.
}

\frame
{
  \frametitle{Sharing package file - git-buildpackage}
 % FIXME: what about mr and all the git repos ?     
  \begin{itemize}
    \item Use {\tt git-import-dsc --pristine-tar} to inject new packages
    \item {\tt git-buildpackage -us -uc} for building
    \item {\tt git-import-orig --uscan --pristine-tar} for upstream upgrades
    \item {\tt gbp-pull} to retrieve work done by team members
    \item {\tt git-dch -a} to update the changelog from your commits
    \item More info: \url{http://pkg-perl.alioth.debian.org/git.html} 
  \end{itemize}

  Set the suite to `UNRELEASED' in debian/changelog for now.

  Commits are logged to IRC.
}

\frame
{
  \frametitle{Creating a package - cowbuilder}

  One of the more tricky parts of packaging is getting the build
  dependencies correct.  cowbuilder is a tool for building packages in
  a clean chroot:

  \begin{itemize}
    \item {\tt sudo apt-get install cowbuilder}
    \item {\tt sudo cowbuilder --create}
    \item {\tt sudo cowbuilder --build libfoo-perl\_1.0-1.dsc}
    \item Can also integrate it into svn-buildpackage.
  \end{itemize}

  Check the test suite gets run!
}

\frame
{
  \frametitle{Creating a package - lintian}

  We want Debian packages to be of high quality.  lintian is a tool
  that can check for common problems.

  \begin{itemize}
    \item {\tt sudo apt-get install lintian}
    \item {\tt lintian -iI --pedantic --color=auto libfoo-perl\_1.0-1\_amd64.changes}
    \item Can also integrate it with debuild/cowbuilder
  \end{itemize}
}

\frame
{
  \frametitle{Creating a package - getting feedback}

  Once you think your package is ready for review, mark it as such:

  \begin{itemize}
    \item {\tt dch -r}
    \item (or `s/UNRELEASED/unstable/' in debian/changelog)
    \item {\tt git commit -m `dch -r; ready for review'}
    \item {\tt git push --all}
  \end{itemize}

  The package status will be changed automatically in PET.
}

\frame
{
  \frametitle{Creating a package - what next?}

  \begin{itemize}
    \item You are likely to get feedback via IRC or email.
    \item Sometimes TODO lists are left for you in debian/changelog by the
      reviewer, with the suite set back to UNRELEASED.
    \item Once the reviewer is happy, they will upload the package and
      tag the release in git.
  \end{itemize}
}

\frame
{
  \frametitle{Questions?}

  \begin{center}
    \email{diocles@debian.org}
    \email{dod@debian.org}
  \end{center}
}

\end{document}