From Fedora Project Wiki
(Updated for guideline changes)
(Update for current guidelines)
Line 2: Line 2:
  
 
== Core Guidelines ==
 
== Core Guidelines ==
 +
Core guidelines, which apply to every package, incorporate the following:
 +
* [[Packaging:ReviewGuidelines|Review guidelines]]
 +
* [[Packaging:NamingGuidelines|Naming guidelines]]
 +
* [[Packaging:Guidelines|Packaging guidelines]]
 +
 
<pre>
 
<pre>
 
Mandatory review guidelines:
 
Mandatory review guidelines:
Line 67: Line 72:
 
  - Sources contain only redistributable code or content
 
  - Sources contain only redistributable code or content
 
  - Spec format is sane
 
  - Spec format is sane
 +
- noarch package with unported deps has correct ExclusiveArch
 +
- Arch-specific patches are applied, not included, conditionally
 
  - Package obeys FHS, except libexecdir, /run, /usr/target
 
  - Package obeys FHS, except libexecdir, /run, /usr/target
 +
- %{_prefix}/lib only used for multilib-exempt packages
 
  - No files in /bin, /sbin, /lib* on >= F17
 
  - No files in /bin, /sbin, /lib* on >= F17
 
  - Programs run before FS mounting use /run instead of /var/run
 
  - Programs run before FS mounting use /run instead of /var/run
Line 78: Line 86:
 
  - Correct %clean section on < EL6
 
  - Correct %clean section on < EL6
 
  - Requires correct, justified where necessary
 
  - Requires correct, justified where necessary
 +
- BuildRequires lack %{_isa}
 
  - Summary, description do not use trademarks incorrectly
 
  - Summary, description do not use trademarks incorrectly
 
  - All relevant documentation is packaged, appropriately marked with %doc
 
  - All relevant documentation is packaged, appropriately marked with %doc
Line 86: Line 95:
 
  - Useful -debuginfo package or disabled and justified
 
  - Useful -debuginfo package or disabled and justified
 
  - Package with .pc files Requires pkgconfig on < EL6
 
  - Package with .pc files Requires pkgconfig on < EL6
  - No static executables
+
  - No static executables (except OCaml)
 
  - Rpath absent or only used for internal libs
 
  - Rpath absent or only used for internal libs
 
  - Config files marked with %config(noreplace) or justified %config
 
  - Config files marked with %config(noreplace) or justified %config
 
  - No config files under /usr
 
  - No config files under /usr
  - Third party package manager configs acceptable, in %_docdir
+
  - Third party package manager configs acceptable, only in %_docdir
 
  - .desktop files are sane
 
  - .desktop files are sane
 +
- desktop-file-install/validate run on .desktop files, as appropriate
 +
- No desktop-file-install --vendor on >= F19
 
  - Spec uses macros consistently
 
  - Spec uses macros consistently
 
  - Spec uses macros instead of hard-coded names where appropriate
 
  - Spec uses macros instead of hard-coded names where appropriate
Line 99: Line 110:
 
  - Spec uses %{SOURCE#} instead of $RPM_SOURCE_DIR and %sourcedir
 
  - Spec uses %{SOURCE#} instead of $RPM_SOURCE_DIR and %sourcedir
 
  - No software collections (scl)
 
  - No software collections (scl)
  - Macro files named /etc/rpm/macros.%name
+
  - Macro files named /etc/rpm/macros.%name or /usr/lib/rpm/macros.%name
 +
- Macro files not marked with %config
 
  - Build uses only python/perl/shell+coreutils/lua/BuildRequired langs
 
  - Build uses only python/perl/shell+coreutils/lua/BuildRequired langs
 
  - %global, not %define
 
  - %global, not %define
Line 115: Line 127:
 
  - Available test suites executed in %check
 
  - Available test suites executed in %check
 
  - tmpfiles.d used for /run, /run/lock on >= F15
 
  - tmpfiles.d used for /run, /run/lock on >= F15
 +
- Package renames/replacements handle Provides, Obsoletes sanely
 +
- IPv6 enabled if supported and IPv4 remains functional
 +
</pre>
 +
 +
== [[Packaging:CronFiles|Cron File Guidelines]] ==
 +
<pre>
 +
- Custom crontabs in /etc/cron.d have 0640 permissions
 +
- Custom crontabs in /etc/cron.d refer to executables in normal places
 +
- Cron jobs marked with %config(noreplace)
 +
- Cron job file names match package name, lack + and .
 +
- Package with cron job Requires: crontabs
 
</pre>
 
</pre>
  
== SysV Init Script Guidelines ==
+
== [[Packaging:SysVInitScript|SysV Init Script Guidelines]] ==
 
<pre>
 
<pre>
 
  - Init scripts go in /etc/rc.d/init.d
 
  - Init scripts go in /etc/rc.d/init.d
Line 133: Line 156:
 
</pre>
 
</pre>
  
== Systemd Guidelines ==
+
== [[Packaging:Systemd|Systemd Guidelines]] ==
 
<pre>
 
<pre>
 
  - Traditional service uses a unit file
 
  - Traditional service uses a unit file
Line 140: Line 163:
 
  - Description= lines do not exceed 80 characters
 
  - Description= lines do not exceed 80 characters
 
  - Documentation field has correct URI format
 
  - Documentation field has correct URI format
  - Service Types= are correct
+
  - Service Type= declarations are correct
 +
- Service has sane [Service], [Install] sections
 
  - Requires=, Wants= used only when necessary
 
  - Requires=, Wants= used only when necessary
 
  - Units to not refer to runlevel*.target
 
  - Units to not refer to runlevel*.target
 
  - Symlinks used instead of Name=
 
  - Symlinks used instead of Name=
 
  - StandardOutput=, StandardError= used only when necessary
 
  - StandardOutput=, StandardError= used only when necessary
 +
- Hardware-activated service not activated by package
 
  - Socket-activated service has FESCo approval, correct unit files
 
  - Socket-activated service has FESCo approval, correct unit files
 
  - Unit files go in %_unitdir
 
  - Unit files go in %_unitdir
  - BuildRequires: systemd-units for %_unitdir macro
+
  - BuildRequires: systemd for %_unitdir macro
 
  - Packaged unit files are not %config files
 
  - Packaged unit files are not %config files
 
  - Unit file scriptlets are correct
 
  - Unit file scriptlets are correct
Line 153: Line 178:
 
</pre>
 
</pre>
  
== Java Guidelines ==
+
== [[Packaging:Java|Java Guidelines]] ==
 
<pre>
 
<pre>
 
  - Javadocs go in javadoc subpackage
 
  - Javadocs go in javadoc subpackage
Line 159: Line 184:
 
  - JAR file names correct
 
  - JAR file names correct
 
  - JAR files go in %{_javadir} or %{_javadir}-$version
 
  - JAR files go in %{_javadir} or %{_javadir}-$version
  - Multiple JAR files go in a %{name} subdirectory
+
  - Compat package jar, pom files are versioned
 
  - Javadocs go in unversioned %{_javadocdir}/%{name}
 
  - Javadocs go in unversioned %{_javadocdir}/%{name}
 
  - javadoc subpackage is noarch on > EL5
 
  - javadoc subpackage is noarch on > EL5
Line 165: Line 190:
 
  - Requires java, jpackage-utils
 
  - Requires java, jpackage-utils
 
  - Dependencies on java/java-devel >= 1.6.0 add epoch 1
 
  - Dependencies on java/java-devel >= 1.6.0 add epoch 1
  - Package requiring maven2 Requires jpackage-utils for post and postun
+
  - pom.xml files, if available, are installed along with their depmaps
  - Package requiring maven contains correct maven-specific code in spec
+
  - Spec contains correct maven code
 +
- pom.xml files, if patched, are patched sanely
 
  - Wrapper script in %{_bindir}
 
  - Wrapper script in %{_bindir}
 
  - GCJ AOT bits follow GCJ guidelines
 
  - GCJ AOT bits follow GCJ guidelines
 
  - No devel package
 
  - No devel package
  - pom.xml files, if any, installed with %add_maven_depmap
+
  - EE API-providing packages have correct Provides
  - JNI shared objects, JARs that require them go in %{_libdir}/%{name}
+
- EE API-using packages mage appropriate Requires, build-classpath
 +
- JNI-using JARs go in %_jnidir
 +
  - JNI shared objects go in %{_libdir}/%{name}
 
  - Calls to System.loadLibrary replaced w/ System.load w/ full .so path
 
  - Calls to System.loadLibrary replaced w/ System.load w/ full .so path
 
  - Bundled JAR files not included or used for build
 
  - Bundled JAR files not included or used for build
Line 178: Line 206:
 
</pre>
 
</pre>
  
== Perl Guidelines ==
+
== [[Packaging:Perl|Perl Guidelines]] ==
 
<pre>
 
<pre>
 +
- "GPL+ or Artistic", not "Artistic or GPL+"
 
  - Module requirements use virtual perl(modname) syntax
 
  - Module requirements use virtual perl(modname) syntax
 
  - Spec BuildRequires correct core modules, not perl-devel
 
  - Spec BuildRequires correct core modules, not perl-devel
  - Spec contains correct MODULE_COMPAT Requires
+
  - Spec contains correct MODULE_COMPAT_ Requires
 
  - Requires/Provides are sane
 
  - Requires/Provides are sane
 
  - CPAN URL tag is not versioned
 
  - CPAN URL tag is not versioned
Line 190: Line 219:
 
</pre>
 
</pre>
  
== Python Guidelines ==
+
== [[Packaging:Python|Python Guidelines]] ==
 
<pre>
 
<pre>
 
  - Runtime Requires correct
 
  - Runtime Requires correct
 +
- BuildRequires: python2-devel and/or python3-devel
 
  - Python macros declared on < EL6
 
  - Python macros declared on < EL6
 +
- Spec uses versioned macros where appropriate
 
  - All .py files packaged with .pyc, .pyo counterparts
 
  - All .py files packaged with .pyc, .pyo counterparts
 +
- INSTALLED_FILES not used for %files list
 
  - Includes .egg-info files/directories when generated
 
  - Includes .egg-info files/directories when generated
 +
- .py not under site-libs byte-compiled against correct runtimes
 +
- Python 3 built as upstream instructs, if at all
 +
- Patches are not specific to python 2 or 3 when sources are combined
 +
- Non-parallel-installable scripts only installed for default runtime
 +
- Eggs built from source
 +
- Eggs do not download deps during build
 +
- Compat packages use easy_install -m to avoid conflicts
 +
- At least one version of each module must be importable w/o version
 
  - Provides/Requires properly filtered
 
  - Provides/Requires properly filtered
 
  - Code that invokes gtk.gdk.get_pixels_array() Requires numpy
 
  - Code that invokes gtk.gdk.get_pixels_array() Requires numpy

Revision as of 03:32, 21 January 2014

This page contains copypasteable templates for package reviews. The Core Guidelines section contains the rules that apply to every package. The rest contain rules that apply to specific types of packages. Those can be appended to the core guidelines.

Core Guidelines

Core guidelines, which apply to every package, incorporate the following:

Mandatory review guidelines:
 - rpmlint output:
   ...
 - License is acceptable (...)
 - License field in spec is correct
 - License files included in package %docs if included in source package
 - License files installed when any subpackage combination is installed
 - Spec written in American English
 - Spec is legible
 - Sources match upstream unless altered to fix permissibility issues
   Upstream SHA256: ...
   Your SHA256:     ...
 - Build succeeds on at least one primary arch
 - Build succeeds on all primary arches or has ExcludeArch + bugs filed
 - BuildRequires correct, justified where necessary
 - Locales handled with %find_lang, not %_datadir/locale/*
 - %post, %postun call ldconfig if package contains shared .so files
 - No bundled libs
 - Relocatability is justified
 - Package owns all directories it creates
 - Package requires others for directories it uses but does not own
 - No duplication in %files unless necessary for license files
 - File permissions are sane
 - Package contains permissible code or content
 - Large docs go in -doc subpackage
 - %doc files not required at runtime
 - Static libs go in -static package/virtual Provides
 - Development files go in -devel package
 - -devel packages Require base with fully-versioned dependency, %_isa
 - No .la files
 - GUI app uses .desktop file, installs it with desktop-file-install
 - File list does not conflict with other packages' without justification
 - File names are valid UTF-8

Optional review guidelines:
 - Query upstream about including license files
 - Translations of description, summary
 - Builds in mock
 - Builds on all arches
 - Functions as described (e.g. no crashes)
 - Scriptlets are sane
 - Subpackages require base with fully-versioned dependency if sensible
 - .pc file subpackage placement is sensible
 - No file deps outside of /etc, /bin, /sbin, /usr/bin, /usr/sbin
 - Include man pages if available

Naming guidelines:
 - Package names use only a-zA-Z0-9-._+ subject to restrictions on -._+
 - Package names are sane
 - No naming conflicts
 - Spec file name matches base package name
 - Version is sane
 - Version does not contain ~
 - Release is sane
 - %dist tag
 - Case used only when necessary
 - Renaming handled correctly

Packaging guidelines:
 - Useful without external bits
 - No kmods
 - Pre-built binaries, libs removed in %prep
 - Sources contain only redistributable code or content
 - Spec format is sane
 - noarch package with unported deps has correct ExclusiveArch
 - Arch-specific patches are applied, not included, conditionally
 - Package obeys FHS, except libexecdir, /run, /usr/target
 - %{_prefix}/lib only used for multilib-exempt packages
 - No files in /bin, /sbin, /lib* on >= F17
 - Programs run before FS mounting use /run instead of /var/run
 - Binaries in /bin, /sbin do not depend on files in /usr on < F17
 - No files under /srv, /opt, /usr/local
 - Changelog in prescribed format
 - No Packager, Vendor, Copyright, PreReq tags
 - Summary does not end in a period
 - Correct BuildRoot tag on < EL6
 - Correct %clean section on < EL6
 - Requires correct, justified where necessary
 - BuildRequires lack %{_isa}
 - Summary, description do not use trademarks incorrectly
 - All relevant documentation is packaged, appropriately marked with %doc
 - Doc files do not drag in extra dependencies (e.g. due to +x)
 - Code compilable with gcc is compiled with gcc
 - Build honors applicable compiler flags or justifies otherwise
 - PIE used for long-running/root daemons, setuid/filecap programs
 - Useful -debuginfo package or disabled and justified
 - Package with .pc files Requires pkgconfig on < EL6
 - No static executables (except OCaml)
 - Rpath absent or only used for internal libs
 - Config files marked with %config(noreplace) or justified %config
 - No config files under /usr
 - Third party package manager configs acceptable, only in %_docdir
 - .desktop files are sane
 - desktop-file-install/validate run on .desktop files, as appropriate
 - No desktop-file-install --vendor on >= F19
 - Spec uses macros consistently
 - Spec uses macros instead of hard-coded names where appropriate
 - Spec uses macros for executables only when configurability is needed
 - %makeinstall used only when alternatives don't work
 - Macros in Summary, description are expandable at srpm build time
 - Spec uses %{SOURCE#} instead of $RPM_SOURCE_DIR and %sourcedir
 - No software collections (scl)
 - Macro files named /etc/rpm/macros.%name or /usr/lib/rpm/macros.%name
 - Macro files not marked with %config
 - Build uses only python/perl/shell+coreutils/lua/BuildRequired langs
 - %global, not %define
 - Package translating with gettext BuildRequires it
 - Package translating with Linguist BuildRequires qt-devel
 - File ops preserve timestamps
 - Parallel make
 - No Requires(pre,post) notation
 - User, group creation handled correctly (See Packaging:UsersAndGroups)
 - Web apps go in /usr/share/%name, not /var/www
 - Conflicts are justified
 - One project per package
 - No bundled fonts
 - Patches have appropriate commentary
 - Available test suites executed in %check
 - tmpfiles.d used for /run, /run/lock on >= F15
 - Package renames/replacements handle Provides, Obsoletes sanely
 - IPv6 enabled if supported and IPv4 remains functional

Cron File Guidelines

 - Custom crontabs in /etc/cron.d have 0640 permissions
 - Custom crontabs in /etc/cron.d refer to executables in normal places
 - Cron jobs marked with %config(noreplace)
 - Cron job file names match package name, lack + and .
 - Package with cron job Requires: crontabs

SysV Init Script Guidelines

 - Init scripts go in /etc/rc.d/init.d
 - Init scripts not marked with %config
 - Init script configuration in /etc/sysconfig
 - Init scripts have 0755 permissions
 - Packages with unit files put init scripts in -sysvinit subpackage
 - chkconfig, initscripts Requires, init scripts correct
 - Daemon-spawning init scripts manage /var/lock/subsys/%name
 - Init scripts have chkconfig headers
 - Init script environment variables have reasonable defaults
 - Init scripts implement all required actions
 - Init script behavior is sensible
 - Init script return codes are correct

Systemd Guidelines

 - Traditional service uses a unit file
 - Non-standard service commands converted to standalone scripts
 - Unit names are sane
 - Description= lines do not exceed 80 characters
 - Documentation field has correct URI format
 - Service Type= declarations are correct
 - Service has sane [Service], [Install] sections
 - Requires=, Wants= used only when necessary
 - Units to not refer to runlevel*.target
 - Symlinks used instead of Name=
 - StandardOutput=, StandardError= used only when necessary
 - Hardware-activated service not activated by package
 - Socket-activated service has FESCo approval, correct unit files
 - Unit files go in %_unitdir
 - BuildRequires: systemd for %_unitdir macro
 - Packaged unit files are not %config files
 - Unit file scriptlets are correct
 - tmpfiles.d used where needed

Java Guidelines

 - Javadocs go in javadoc subpackage
 - Prefer split JARs over monolithic
 - JAR file names correct
 - JAR files go in %{_javadir} or %{_javadir}-$version
 - Compat package jar, pom files are versioned
 - Javadocs go in unversioned %{_javadocdir}/%{name}
 - javadoc subpackage is noarch on > EL5
 - BuildRequires java-devel, jpackage-utils
 - Requires java, jpackage-utils
 - Dependencies on java/java-devel >= 1.6.0 add epoch 1
 - pom.xml files, if available, are installed along with their depmaps
 - Spec contains correct maven code
 - pom.xml files, if patched, are patched sanely
 - Wrapper script in %{_bindir}
 - GCJ AOT bits follow GCJ guidelines
 - No devel package
 - EE API-providing packages have correct Provides
 - EE API-using packages mage appropriate Requires, build-classpath
 - JNI-using JARs go in %_jnidir
 - JNI shared objects go in %{_libdir}/%{name}
 - Calls to System.loadLibrary replaced w/ System.load w/ full .so path
 - Bundled JAR files not included or used for build
 - No Javadoc %post/%ghost
 - No class-path elements in JAR manifests

Perl Guidelines

 - "GPL+ or Artistic", not "Artistic or GPL+"
 - Module requirements use virtual perl(modname) syntax
 - Spec BuildRequires correct core modules, not perl-devel
 - Spec contains correct MODULE_COMPAT_ Requires
 - Requires/Provides are sane
 - CPAN URL tag is not versioned
 - All tests enabled where possible
 - Use Build.PL if present unless justified otherwise
 - .h files not split into -devel package

Python Guidelines

 - Runtime Requires correct
 - BuildRequires: python2-devel and/or python3-devel
 - Python macros declared on < EL6
 - Spec uses versioned macros where appropriate
 - All .py files packaged with .pyc, .pyo counterparts
 - INSTALLED_FILES not used for %files list
 - Includes .egg-info files/directories when generated
 - .py not under site-libs byte-compiled against correct runtimes
 - Python 3 built as upstream instructs, if at all
 - Patches are not specific to python 2 or 3 when sources are combined
 - Non-parallel-installable scripts only installed for default runtime
 - Eggs built from source
 - Eggs do not download deps during build
 - Compat packages use easy_install -m to avoid conflicts
 - At least one version of each module must be importable w/o version
 - Provides/Requires properly filtered
 - Code that invokes gtk.gdk.get_pixels_array() Requires numpy