Often, there are several options to be taken for solving various recurring packaging issues.
This document tries to make a list of those common issues and will serve as a base do define common policies on how to solve them.

======  Issues  ======
Make a list of known problems here and propose workarounds and conventions to apply, whenever possible.
Those will be promoted to the Policies document when acknowledged by the Packman members.

=====  Beta Versions  =====
Packages versioned as e.g. "2.0_rc20" or "1.9beta4" or "0.9.4rc1" are problematic as rpm/apt/yast won't update when the final version is out → define a convention for defining the RPM version tag for such packages (e.g. "2.0_0.20" / "2.0_1.0", "1.9_0.4" / "1.9_1.0", etc...)

=====  Biarch/AMD64  =====
Various issues related to building on biarch/amd64 architecture:
  *  must use <tt>%suse_update_config -f</tt> and <tt>%suse_update_libdir</tt> before configure with every package - note that it might break the build of some packages, so it must be tested (only remove it if it breaks), like this:
<code>
 ...
 %{?suse_update_config:BuildRequires:autoconf automake libtool}}
 ...
 %prep
 %setup -q .....
 %{?suse_update_libdir:%{suse_update_libdir}}
 %{?suse_update_config:%{suse_update_config -f}}</code>
  *  QT libraries (applies to KDE applications/libraries as well)
    *  the QT libraries on SUSE are located in <tt>/usr/lib/qt3</tt>, **not** <tt>/usr/%{_lib}/qt3</tt>, so always pass <tt>--with-qt-dir=/usr/lib/qt3</tt>, even on IA64
    *  must pass <tt>--libsuffix=64</tt> (when on biarch **only**) to have configure use <tt>/usr/lib/qt3/lib64</tt>, can be done with
<code>
 %configure \
 %if %{_lib} == lib64
    --enable-libsuffix=64 \
 %endif</code>

======  General Policies  ======
=====  Release Tag  =====
Every Packman package has to comply with the following release tag naming scheme:
<code>
 -0.pm.<release>.</code>
The reason for starting the release tag with "<tt>0.</tt>" is simple: when SUSE provides a newer package (e.g. as part of a security update), it will have a higher priority than ours, which is good: we give priority to packages made by SUSE.

=====  Source Files  =====
Source files (<tt>Source:</tt>, <tt>Source1:</tt>, <tt>Source2:</tt>, ...) should always be mentioned with the complete URL, not just the filename.
<u>e.g.:</u>
  *  **not** like this:
<code>
 Source: doxygen-%{_version}.src.tar.gz</code>
  *  **but** like this:
<code>
 Source: <nowiki>ftp://ftp.stack.nl/pub/users/dimitri/doxygen-%{_version}.src.tar.gz</nowiki></code>

Obviously, this does not apply to <tt>Patch:</tt> or <tt>Source:</tt> files contributed by the packager (e.g. init script, etc...)

=====  Patch Files  =====
  *  filenames: use the "<tt>.diff</tt>" filename extension for the patch filenames
  *  use "unified" format: create patch files using <tt>diff</tt> with the "<tt>-u</tt>" option
  *  try to create diff files that can be applied with the "<tt>-p0</tt>" option, thus created in the base directory of the unpacked source tarball
  *  the filename of the patch must start with the name of the package, e.g. <tt>mplayer-fix-biarch.diff</tt> instead of <tt>fix-biarch.diff</tt>

=====  Use macros  =====
  *  use macros whenever possible, both for
    *  tools: %__make, %__install, %__cp, %__rm, ...
    *  paths: %_prefix, %_libdir, %_sysconfdir, %_mandir, %_datadir, ...
  *  special note: //**ALWAYS//** use "<tt>%_lib</tt>" and "<tt>%_libdir</tt>" instead of "<tt>lib</tt>" and "<tt>/usr/lib</tt>", otherwise the package won't build properly on biarch/amd64 !!!

=====  Optimization flags  =====
Always try to pass build optimization flags using the <tt>%{optflags}</tt> variable.
Most often, it is sufficient to set them before calling <tt>./configure</tt>, like this:<code>
CFLAGS="%{optflags}" \
CXXFLAGS="%{optflags}" \
./configure ...
</code>

On the other hand, it is advisable to use the <tt>%configure</tt> macro instead, that already sets every generic autoconf parameter.
When you use <tt>%configure</tt>, you don't need to pass <tt>%{optflags}</tt>, it does it automatically:
<code>
%configure \
<code>
   --with-included-sqlite \
   --with-alsa \
   ...</code>
</code>

When <tt>autoconf</tt> is not used, it is necessary to look at the <tt>Makefile</tt> and see whether the flags can be passed by overriding an existing <tt>Makefile</tt> variable (e.g. <tt>CFLAGS</tt>, <tt>DEBUG</tt>, <tt>OPTFLAGS</tt>, ...).
If it is not possible, make a patch for the <tt>Makefile</tt> to be able to pass those flags from the <tt>spec</tt> file.
This is often the case when <tt>CFLAGS</tt> is already used in the <tt>Makefile</tt> to pass required options, like <tt>-I...</tt> paths or <tt>-D...</tt> defines.
Example:
<code>
   CFLAGS=-DLOCALE_PATH=\"/usr/locale\" -DLINUX -I$(pkgconfig gtk-2.0 --cflags) -g -O2</code>
In this case, make a patch to the <tt>Makefile</tt> and add an additional variable:
  *  <tt>cp Makefile Makefile.orig</tt>
  *  edit <tt>Makefile</tt> and change as below:
<code>
   OPTFLAGS=-g -O2
   CFLAGS=-DLOCALE_PATH=\"/usr/locale\" -DLINUX -I$(pkgconfig gtk-2.0 --cflags) $(OPTFLAGS)</code>
  *  make a patch: <tt>diff -u Makefile{.orig,} > ../foobar-makefile-optflags.diff</tt>
  *  add the patch in the spec file:
<code>
   Source: ....
   Patch1: foobar-makefile-optflags.diff
   ...
   %prep
   %setup -q ...
   %patch1
   %{?suse_update_libdir:%{suse_update_libdir}}
   %{?suse_update_config:%{suse_update_config -f}}</code>
  *  and pass <tt>%{optflags}</tt> through the added variable:
<code>
   %build
   %__make OPTFLAGS="%{optflags}"</code>

======  Packman Metadata  ======
To be able to upload packages automagically using <tt>packmanrobot</tt>, you must add the following Packman-specific tags in every <tt>spec</tt> file.
All those Packman tags start with a comment (<tt>#</tt>) and thus, don't break <tt>rpmbuild</tt>.
=====  Packager  =====
Using the <tt>Packman</tt> tag, you can identify yourself as a Packman team member.