[Fedora-packaging] [Guidelines Change] Changes to the Packaging Guidelines

Sat Mar 8 17:45:09 UTC 2014

We've been very bad at announcing changes to the Packaging Guidelines.
So very bad. Bear with us as we announce all the changes we should have
been announcing in the past, but failed to do. Again, so bad.

---

The Mersenne Twister implementation (mt19937ar) has been granted a
general bundling exception. 
https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries#Packages_granted_exceptions

---

After an unintentional delay, the Haskell Guideline revision approved
four months ago has been officially written into the Guidelines. A
profound apology to everyone who wanted to point people at the new
guidelines and couldn't find them in the meantime. The updated
guidelines can be read here: 
https://fedoraproject.org/wiki/Packaging:Haskell

---

The Naming Guidelines for python modules has been updated to remove the
exception for packages which have a "py" prefix in the upstream name.
This change comes at a time when python2 and python3 modules are
commonly built from the same package and all python3 modules are
required to have a "python3" in their name. This change makes it easier
for users to identify that the python3-foo module is part of the
python-foo package for filing bugs and searching for the python3 version
of a package they use in python2.

Note that packages that are already in Fedora with names allowed under
the old guidelines are considered grandfathered. Renaming makes sense
but the FPC is not requiring that they do. This is up to the individual
package maintainers (or FESCo should someone ask them for permission to
do a mass package rename).

---

The syntax in the guidelines for Source macro naming of github generated
tarballs has been changed from
"%{name}-%{version}-%{shortcommit}.tar.gz" to
"$PROJECT-%{commit}.tar.gz", because that is the default naming from github.

https://fedoraproject.org/wiki/Packaging:SourceURL#Github

---

An exception has been granted for sigrok-firmware-fx2lafw to bundle fx2lib.

https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries#Packages_granted_exceptions

---

A line has been added to the arch specific Octave template to exclude
.oct files from provides. (This will no longer be necessary when Fedora
19 is EOL.)

https://fedoraproject.org/wiki/Packaging:Octave#Arch_specific_Octave_spec_template

---

A bundling exception for JAXP and JAX-WS in openJDK has been granted.

https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries#Packages_granted_exceptions

---

A new section was added to the guidelines covering build time network
access:

Packages in the Fedora buildsystem are built in a mock chroot with no
access to the internet. Packages must not depend or or use any network
resources that they don't themselves create (ie, for tests). In no cases
should source code be downloaded from any external sources, only from
the lookaside cache and/or the Fedora git repository.

https://fedoraproject.org/wiki/Packaging:Guidelines#Build_time_network_access

---

Additional wording was added to the procedures for dealing with bundled
library handling.

https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries#When_a_Bundled_Library_is_Discovered_Post-Review
https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries#Exceptions

---

Added a guideline: "Packages MUST NOT have SourceN or PatchN tags which
are conditionalized on architecture." This makes sure an srpm has all of
the files needed to rebuild itself. Note that this change *is not*
intended to prevent packages from conditionally applying patches or
sources during the build. That remains a valid practice.

---

The trigger scripts that saved information about sysv runlevels when
converting to systemd have been dropped on the basis that everything of
importance has been converted and the system for saving that information
was always kludgy and complex. Packages that are converting now should
not include them. Lennart will submit a Changes Proposal to coordinate
updating packages that presently have these trigger scripts in order to
remove the actual systemd-sysv package.

https://fedoraproject.org/wiki/Packaging:ScriptletSnippets#Packages_migrating_to_a_systemd_unit_file_from_a_SysV_initscript

---

The Node.JS guidelines have been changed in the following ways:

* The %nodejs_fixdep section included in the original version of the
draft has been readded.

* The RPM magic was recently split into it's own "nodejs-packaging"
SRPM, similar to Java. Accordingly, packages can now require
"nodejs-packaging" instead of "nodejs-devel" to reduce the number of
deps dragged in at build-time. 

* The necessary ExclusiveArch? line needed for Node.js packages is now
documented, including the %{nodejs_arches} macro recently added to
redhat-rpm-config for this purpose.

* A strategy for handling multiple/compatibility versions of packages
that is transparent to dependent packagers has been implemented.

* The %{nodejs_default_filter} default automatic virtual provides
filtering macro (similar to Perl's) is now documented.

* A --check argument was added to %nodejs_symlink_deps simplify running
test suites in specs.

* A brief mention that additional virtual provides are added for native
modules to track ABI compatibility was added.

* Some minor edits were made to the installing native modules section to
reflect reality; my initial draft contained errors.

* A brief note about an additional macro required to enable dependency
generation on EPEL was added.

https://fedoraproject.org/wiki/Packaging:Node.js

---

The prohibition against packages installing files into /bin, /sbin,
/lib, and /lib4 has been removed and a section explaining how Fedora's
UsrMove? feature interacts with the rpm %files section has been added.
Packagers who maintain software that installs into /bin, /sbin, /lib,
and /lib64 historically or in upstream are encouraged to read that
section to understand what's best for their package: 

https://fedoraproject.org/wiki/Packaging:Guidelines#Effect_of_the_UsrMove_Fedora_Feature

---

The Conflicts guidelines have been clarified to state that the goal is
for users to be able to install the latest packages from Fedora's repos
regardless of what other Fedora packages are installed.

https://fedoraproject.org/wiki/Packaging:Conflicts

---

Added an additional allowed use of Conflicts to the packaging guidelines
on Conflicts. This usage is for a package which is split into multiple
packages with files that may conflict with files in the older version of
the base package. See the Conflicts Guidelines if you think you may be
able to make use of this:

https://fedoraproject.org/wiki/Packaging:Conflicts#Splitting_Packages

---

Due to changes in which packages are in the minimal set pulled into the
buildsystem, BuildRequires?: systemd has become necessary for packages
which install systemd unit files. The Guidelines have been updated to
show this: 

http://fedoraproject.org/wiki/Packaging:ScriptletSnippets#Macroized_scriptlets_.28Fedora_18.2B.29

---

Fedora packages which use pkg-config to build against a library (e.g.
'foo') on which they depend, '''SHOULD''' express their build dependency
correctly as <pkgconfig(foo). For more information, see

https://fedoraproject.org/wiki/Packaging:PkgConfigBuildRequires

---

Guidelines for shared web assets including browser-side javascript have
been added. These finally add rules for unbundling javascript libraries
from web applications as well as shared css libraries, icons, and other
files. Two related areas were clarified as part of this: pre-compiled
shockwave flash files count as pre-compiled binaries and are not allowed
(compile flash resources from source with an open source flash toolchain
or patch them out of the package). Font files need to have proper
licensing informaiton in their metadata. The following pages contain the
updated guidelines:

* https://fedoraproject.org/wiki/Packaging:Web_Assets
* https://fedoraproject.org/wiki/Packaging:JavaScript
* 
https://fedoraproject.org/wiki/Packaging:FontsPolicy#Licensing_Information_in_Metadata

---

The naming guidelines have been changed to emphasize that package names
should generally use lowercase and turn underscores into dashes unless
there's a compelling reason to follow a different upstream convention.

---

The FPC changed its recommendation on dealing with library conflicts.
The new recommendation makes clear that using a subdirectory is useful
in very few cases, makes use of environment-modules instead of an
ld.so.conf.d file to switch between them, and asks that for the cases
where subdirectories don't work maintainers press upstreams hard to
change their library names. If someone would care to submit a draft for
dealing with library conflicts that fall outside of this area FPC would
be happy to look at whether it makes sense to add those instructions. 

https://fedoraproject.org/wiki/Packaging:Conflicts#Library_Name_Conflicts

---

The autodep filter guidelines were updated to reflect changes to RPM in
Fedora 20.

https://fedoraproject.org/wiki/Packaging:AutoProvidesAndRequiresFiltering#Perl

---

A method of handling noarch packages which have dependencies that are
not present on some architectures was made official. 
https://fedoraproject.org/wiki/Packaging:Guidelines#Noarch_with_unported_dependencies

These methods are a change from the common practice in, for instance,
node.js packaging. Packagers should think about updating their packages
to the new guidelines as they make other updates.

Please see https://fedorahosted.org/fpc/ticket/355#comment:8 or the
meeting log for that date if you want more information than is in the
Guidelines. The possibility of enhancing rpm or koji to deal with this
in a better manner is being looked into by the packaging-team and
rel-eng. When those features eventually are available to Fedora, we'll
update the Guidelines to take advantage of them.

---

The guidelines for including both sysvinit scripts and systemd unit
files were changed. New packages must not include both even if the
sysvinit scripts are in a separate subpackage. As in many cases of
guideline changes, old packages are grandfathered but packagers are
encouraged to look into dropping the sysvinit subpackages as they update
in rawhide. 

https://fedoraproject.org/wiki/Packaging:SysVInitScript#Initscripts_in_addition_to_systemd_unit_files

---

A new bundling exception has been made for the java time-api package to
reverse bundle the javax.time api present in openjdk8 for code which
uses prior versions of the jdk.

---

The kernel provides a library for monitoring events which is used by
perf, powertop, rasdaemon and possibly other programs. As the library is
not currently built and installed for general use but the plan is to
enable that in kernel-3.14 a temporary bundling exception has been
granted through Fedora 22.

---

Two changes have been made to the Ada Guidelines:

* instructions on using comfignat to build ada packages has been added
to the Ada Guidelines:
* instructions on how to allow rpaths for testsuites and binaries that
are only used at buildtime. The instructions also include a requirement
to explicitly run %{_rpmconfigdir}/check-rpaths in %check if rpaths are
turned on for the build.

https://fedoraproject.org/wiki/Packaging:Ada

---

As part of the ongoing effort to update the guidelines for an eventual
change from python2 to python3 as the default python we're promoting use
of %{python2}, %{python2_sitelib}, and %{python2_sitearch} instead of
the unversioned %{python}, %{python_sitelib}, and %{python_sitearch}
macros. These macros are not available for EPEL5 and EPEL6. We've
updated the Python Guidelines to mention conditionally defining those
macros for EPEL5 and EPEL6 builds.

---

Changes to python-setuptools in F20 cause easy_install to install egg
files instead of egg directories by default. This sometimes causes
problems for rpms of multi-version python modules as the egg filenames
are the same if the version of the package hasn't been increased and rpm
is unable to replace the directory with a file. To fix this, the 
https://fedoraproject.org/wiki/Packaging:Python_Eggs#Multiple_Versions
guideline has been updated to pass the "-Z" switch to easy_install which
restores the former behaviour of installing eggs as a directory.

If you package a backwards or forwards compat python module that makes
use of the Multiple_Versions guideline (or easy_install in some other
way), please update your spec file to include the -Z switch.

---

The java guidelines have seen a large update that simplifies the
language and removes instructions for EOL-Fedora releases. One
particularly important change is the addition of the java-headless
virtual dependency. Please see the Java Guidelines for complete
information:

https://fedoraproject.org/wiki/Packaging:Java

---

New guidelines have been added that address modifying the /etc/shells
file when a package adds a new login shell:

https://fedoraproject.org/wiki/Packaging:ScriptletSnippets#Shells

---

Packaging Guidelines for building modules and themes for Drupal7 have
been approved: https://fedoraproject.org/wiki/Packaging:Drupal7

---

The Guidelines contained a section stating not to use
"Requires(post,pre):" type syntax due to rpm bugs. Since those bugs only
apply to the rpm shipped in RHEL5, the prohibition has been removed from
the guidelines.

---

These guideline changes were approved by the Fedora Packaging
Committee (FPC).

Many thanks to the uncountable number of people in the Fedora community
for raising and resolving these issues, and all of the members of the
FPC, for assisting in drafting, refining, and passing these guidelines.

As a reminder: The Fedora Packaging Guidelines are living documents! If
you find something missing, incorrect, or in need of revision, you can
suggest a draft change. The procedure for this is documented here:
https://fedoraproject.org/wiki/Packaging/Committee#GuidelineChangeProcedure

Thanks,

~tom