From 70e7ea5d7cdc5d3138093e477b7d8487b4683407 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Jun 21 2019 15:11:16 +0000 Subject: Fix several typos. --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 99b98dc..397deaa 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -61,7 +61,7 @@ ** xref:Rust.adoc[Rust] ** xref:Tcl.adoc[Tcl/Tk extensions] -* Other Domain-specific Guideliens +* Other Domain-specific Guidelines ** xref:CronFiles.adoc[CronFiles] ** xref:DevAssistant.adoc[DevAssistant] ** xref:Drupal7.adoc[Drupal7] diff --git a/guidelines/modules/ROOT/pages/Directory_Replacement.adoc b/guidelines/modules/ROOT/pages/Directory_Replacement.adoc index 766a6dc..dc309fe 100644 --- a/guidelines/modules/ROOT/pages/Directory_Replacement.adoc +++ b/guidelines/modules/ROOT/pages/Directory_Replacement.adoc @@ -13,7 +13,7 @@ and https://bugzilla.redhat.com/show_bug.cgi?id=646523[bug 646523]. == Try to avoid the problem in the first place -While its obviously not possible to foresee all the cases +While it's obviously not possible to foresee all the cases where the need might arise, when the need *_is_* foreseeable, such as with bundled libraries, diff --git a/guidelines/modules/ROOT/pages/Drupal7.adoc b/guidelines/modules/ROOT/pages/Drupal7.adoc index 86ac65e..5233592 100644 --- a/guidelines/modules/ROOT/pages/Drupal7.adoc +++ b/guidelines/modules/ROOT/pages/Drupal7.adoc @@ -5,7 +5,7 @@ == Naming Scheme -Every package *MUST* be named `+drupal7-+`__`++`. Drupal itself enforces unique machine names for each of its' projects and there is a single namespace for all modules, themes, and distributions/profiles. The __`++` *MUST* match the drupal.org project name (i.e. drupal.org/project/__`++`). +Every package *MUST* be named `+drupal7-+`__`++`. Drupal itself enforces unique machine names for each of its projects and there is a single namespace for all modules, themes, and distributions/profiles. The __`++` *MUST* match the drupal.org project name (i.e. drupal.org/project/__`++`). == Macros and Scriptlets @@ -98,14 +98,14 @@ find . -type f -executable -print0 | xargs -0 chmod -x == Additional Hints -* Every module package *SHOULD* list the Drupal modules it provides in its' description: +* Every module package *SHOULD* list the Drupal modules it provides in its description: + .... This package provides the following Drupal module(s): * %{module} .... + -For example, the `+drupal7-domain+` package contains the following in its' description: +For example, the `+drupal7-domain+` package contains the following in its description: + .... This package provides the following Drupal modules: diff --git a/guidelines/modules/ROOT/pages/Emacs.adoc b/guidelines/modules/ROOT/pages/Emacs.adoc index aeda5e9..c502cbd 100644 --- a/guidelines/modules/ROOT/pages/Emacs.adoc +++ b/guidelines/modules/ROOT/pages/Emacs.adoc @@ -44,7 +44,7 @@ The compiled elisp source and the elisp source files should be packaged as part * If the package requires a startup file this should be called foo-init.el and be placed in `+%{_emacs_sitestartdir}+`. 2. File locations for XEmacs add-on (sub-)packages: * All elisp files for package should be installed in the directory `+%{_xemacs_sitelispdir}/foo+` (`+%{_xemacs_sitelispdir}+` translates to `+/usr/share/xemacs/site-packages/lisp/+`) -* All other files for the add-on package should be installed under the relevant sub-directories in `+%{_xemacs_sitepkgdir}+` eg. `+%{_xemacs_sitepkgdir}/etc/foo+` (`+%{_xemacs_sitepkgdir}+` translates to `+/usr/share/xemacs/site-packages+`). +* All other files for the add-on package should be installed under the relevant sub-directories in `+%{_xemacs_sitepkgdir}+` e.g., `+%{_xemacs_sitepkgdir}/etc/foo+` (`+%{_xemacs_sitepkgdir}+` translates to `+/usr/share/xemacs/site-packages+`). * If the package requires a startup file this should be called `+foo-init.el+` and be placed in `+%{_xemacs_sitestartdir}+`. == Package Requires @@ -226,7 +226,7 @@ Requires: emacs(bin) >= %{_emacs_version} %changelog .... -=== Template for a package which contains auxilliary GNU Emacs and XEmacs files (Case II) +=== Template for a package which contains auxiliary GNU Emacs and XEmacs files (Case II) This is a skeleton of a package which also includes support files for both GNU Emacs and XEmacs @@ -249,7 +249,7 @@ Requires: xemacs-filesystem >= %{_xemacs_version} %description -Foo is a package wghich contains auxilliary Emacs and XEmacs support files +Foo is a package which contains auxiliary Emacs and XEmacs support files %prep @@ -288,11 +288,11 @@ The packaging naming guidelines state that: _Packages of emacs add-on components (code that adds additional functionality to emacs compatible editors) have their own naming scheme. It is often the case that a component will add functionality to several different compatible editors, such as GNU Emacs and XEmacs (and possibly development versions of these editors). The package name should take into account the upstream name of the emacs component._ -_Where a component adds functionality to more than one emacs compatible editor, the package name should be of the form emacs-common-$NAME. In this case, the main package should contain only files common to all emacs compatible editors, and the code specific to each should be placed in a subpackage reflecting the specific editor $EDITOR-$NAME eg. xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An example of this scheme can be found in the package emacs-common-muse._ +_Where a component adds functionality to more than one emacs compatible editor, the package name should be of the form emacs-common-$NAME. In this case, the main package should contain only files common to all emacs compatible editors, and the code specific to each should be placed in a subpackage reflecting the specific editor $EDITOR-$NAME e.g., xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An example of this scheme can be found in the package emacs-common-muse._ _Where a component is designed to add functionality to only a single emacs compatible editor, the main package name should reflect this by being called $EDITOR-$NAME. An example of this situation can be found in the package emacs-auctex, which is built only for GNU Emacs._ -Wherever possible, we encourage making an add-on package available for both GNU Emacs and XEmacs. One common case where that is not desireable is when an add-on package is already available for XEmacs in either xemacs-packages-base or xemacs-packages-extra. For example VM (a mail reader for Emacs) is provided for XEmacs in the xemacs-packages-extra package, but is not included in the emacs or emacs-common packages. Therefore it is sensible to create a package called emacs-vm which is the VM package for GNU Emacs only. Another such example is AUCTeX. +Wherever possible, we encourage making an add-on package available for both GNU Emacs and XEmacs. One common case where that is not desirable is when an add-on package is already available for XEmacs in either xemacs-packages-base or xemacs-packages-extra. For example VM (a mail reader for Emacs) is provided for XEmacs in the xemacs-packages-extra package, but is not included in the emacs or emacs-common packages. Therefore it is sensible to create a package called emacs-vm which is the VM package for GNU Emacs only. Another such example is AUCTeX. === Location of installed files @@ -308,7 +308,7 @@ XEmacs expects add-on packages to be installed under %\{_xemacs_sitepkgdir} whic Lisp files for add-on package foo should be placed in %\{_xemacs_sitelispdir}/foo which evaluates to %\{_xemacs_sitepkgdir}/lisp/foo. -Other files for the add-on which are not elisp files should be placed in package specific sub-directories under %\{_xemacs_sitepkgdir} eg. %\{_xemacs_sitepkgdir}/etc/foo. +Other files for the add-on which are not elisp files should be placed in package specific sub-directories under %\{_xemacs_sitepkgdir} e.g., %\{_xemacs_sitepkgdir}/etc/foo. Usually an add-on package will require a startup file, and this should be called foo-init.el and be placed in %\{_xemacs_sitestartdir} which evaluates to /usr/share/xemacs/site-packages/lisp/site-start.d/. @@ -359,4 +359,4 @@ It is recommended to derive greater-than-or-equal-to valued versioned dependenci === Other packages containing Emacsen add-ons (Case II) -It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for (X)Emacs. For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs. In this case, we want to enable the (X)Emacs support IF (X)Emacs is installed, but we don't want to mandate the installation of (X)Emacs on installation of this package since (X)Emacs is not required for providing the core functionality of the package. To enable this, the emacs-filesystem and xemacs-filesystem sub-packages were created which own the /usr/share/emacs/site-lisp and /usr/share/xmeacs/site-packages directories respectively. A package can then Require these (x)emacsfilesystem packages in order to install their Elisp files without pulling in (X)Emacs and their dependency chain. +It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for (X)Emacs. For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs. In this case, we want to enable the (X)Emacs support IF (X)Emacs is installed, but we don't want to mandate the installation of (X)Emacs on installation of this package since (X)Emacs is not required for providing the core functionality of the package. To enable this, the emacs-filesystem and xemacs-filesystem sub-packages were created which own the /usr/share/emacs/site-lisp and /usr/share/xemacs/site-packages directories respectively. A package can then Require these (x)emacsfilesystem packages in order to install their Elisp files without pulling in (X)Emacs and their dependency chain. diff --git a/guidelines/modules/ROOT/pages/EnvironmentModules.adoc b/guidelines/modules/ROOT/pages/EnvironmentModules.adoc index b3e408e..1948338 100644 --- a/guidelines/modules/ROOT/pages/EnvironmentModules.adoc +++ b/guidelines/modules/ROOT/pages/EnvironmentModules.adoc @@ -2,7 +2,7 @@ When one has multiple programs serving the same purpose (for instance SMTP servers such as sendmail, exim and postfix; or print servers such as lprng and cups), it is usual to wrap these using alternatives. Alternatives provides a clean way to have many types of software serving the same purpose installed at the same time and have the commands such as `+mail+` and `+lpr+` point to the wanted versions. -However, when there are multiple variants that each serve the needs of some user and thus must be available simultaneously by users, the alternatives system simply isn't enough since it is system-wide. This has been reality on supercomputers and clusters for eons, and multiple implementations of a solution has been developed: http://modules.sourceforge.net/[environment modules] and https://www.tacc.utexas.edu/tacc-projects/lmod[Lmod]. Fedora currently makes use of this primarily for handling switching between differen MPI implementations. +However, when there are multiple variants that each serve the needs of some user and thus must be available simultaneously by users, the alternatives system simply isn't enough since it is system-wide. This has been reality on supercomputers and clusters for eons, and multiple implementations of a solution has been developed: http://modules.sourceforge.net/[environment modules] and https://www.tacc.utexas.edu/tacc-projects/lmod[Lmod]. Fedora currently makes use of this primarily for handling switching between different MPI implementations. Environment modules are also useful in situations where a package wants to install binaries that use common names and might conflict file in or otherwise pollute /usr/bin. Use must then load an environment module before being able to make use of those programs. diff --git a/guidelines/modules/ROOT/pages/Haskell.adoc b/guidelines/modules/ROOT/pages/Haskell.adoc index d81629d..912029c 100644 --- a/guidelines/modules/ROOT/pages/Haskell.adoc +++ b/guidelines/modules/ROOT/pages/Haskell.adoc @@ -197,7 +197,7 @@ This package provides the Haskell %{pkg_name} library development files. == Package Naming -Haskell Bin and BinLib packages should follow the usual Fedora Package Naming Guidelines for base package naming: ie follow the upstream name. Examples include projects like `+darcs+` and `+xmonad+`. +Haskell Bin and BinLib packages should follow the usual Fedora Package Naming Guidelines for base package naming: i.e., follow the upstream name. Examples include projects like `+darcs+` and `+xmonad+`. However there may be cases where a Haskell BinLib package is really a Lib package with a minor or unimportant executable: in this case it is better to treat the package a Lib package, optionally with a executable subpackage if appropriate. The names of Haskell Lib packages, packaged for `+ghc+`, are prefixed by "ghc-". For example the Haskell X11 library package is named `+ghc-X11+`, and the Haskell mmap library package is named `+ghc-mmap+`, etc. @@ -247,7 +247,7 @@ Because GHC still assumes static versions of libraries are installed they need t Executables in Bin and BinLib packages should be dynamically linked to shared libraries. -Note that executables in most BinLib packages are currently staticly linked against the library in their own package (unless the .cabal file explicitly lists it as a dependency), but dynamically linked against other dependent libraries. BinLib executables that do link dynamically against their own library should use `+%ghc_fix_dynamic_rpath+` to fix its RPATH. +Note that executables in most BinLib packages are currently statically linked against the library in their own package (unless the .cabal file explicitly lists it as a dependency), but dynamically linked against other dependent libraries. BinLib executables that do link dynamically against their own library should use `+%ghc_fix_dynamic_rpath+` to fix its RPATH. Some particular packages may do user compilation during runtime in which case they will need Requires as well as BuildRequires for their dependencies: examples include xmonad and yi which require their devel package to be present to allow users to relink their configuration or customization. @@ -365,7 +365,7 @@ It generates the filelists `+ghc-%{pkg_name}.files+` and `+ghc-%{pkg_name}-devel == Compiling non-Cabal packages -Packages compiling Haskell code without Cabal, ie directly with `+ghc+` or `+ghc --make+`, should use `+-O1+` optimization, like Cabal does by default. +Packages compiling Haskell code without Cabal, i.e., directly with `+ghc+` or `+ghc --make+`, should use `+-O1+` optimization, like Cabal does by default. == References diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc index e76a3b6..c1ac828 100644 --- a/guidelines/modules/ROOT/pages/Java.adoc +++ b/guidelines/modules/ROOT/pages/Java.adoc @@ -23,7 +23,7 @@ In particular `+*.class+` and `+*.jar+` files from upstream releases MUST NOT be == JAR file installation -The following applies to all JAR files except <> and application-specific JAR files (ie. JAR files that can only reasonably be used as part of an application and therefore constitute application-private data). +The following applies to all JAR files except <> and application-specific JAR files (i.e., JAR files that can only reasonably be used as part of an application and therefore constitute application-private data). === Split JAR files diff --git a/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc b/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc index 646f8a1..d320ff5 100644 --- a/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc +++ b/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc @@ -1,10 +1,10 @@ == LibreOffice extension rpm guidelines 1. Extensions *Must* be installed unpacked under %\{_libdir}/libreoffice/share/extensions. These are termed bundled extensions. Extensions should not be installed as shared extensions i.e. via unopkg --shared + -2. An extension should normally just be able to Require: an appropriate LibreOffice component e.g. libreoffice-core, without a specific n-v-r as extensions use the stable UNO abi which rarely changes, and then only to add extra apis. So unless you require a specific feature of a LibreOffice release there is no need to require a specific n-v-r and force a rebuild on every n-v-r of libreoffice. + -3. extensions *Must* be named libreoffice-FOO. + -4. extensions are similar to e.g. xorg video drivers in that there exist proprietary or binary only extensions, but of course normal Fedora rules apply to what extensions can be packaged, i.e. see normal packaging licensing etc. rules. The license *Must* be acceptable, and the package *Must* be built from source. + -5. extensions can be written in any language that has an uno binding, e.g. C++, python, java or StarBasic. Consider the additional packaging guidelines of the language that the extension is written in if such guidelines exists. + +2. An extension should normally just be able to Require: an appropriate LibreOffice component e.g. libreoffice-core, without a specific n-v-r as extensions use the stable UNO ABI which rarely changes, and then only to add extra APIs. So unless you require a specific feature of a LibreOffice release there is no need to require a specific n-v-r and force a rebuild on every n-v-r of libreoffice. + +3. Extensions *Must* be named libreoffice-FOO. + +4. Extensions are similar to e.g. xorg video drivers in that there exist proprietary or binary only extensions, but of course normal Fedora rules apply to what extensions can be packaged, i.e. see normal packaging licensing etc. rules. The license *Must* be acceptable, and the package *Must* be built from source. + +5. Extensions can be written in any language that has an uno binding, e.g. C++, python, java or StarBasic. Consider the additional packaging guidelines of the language that the extension is written in if such guidelines exists. + 6. Many extensions are actually architecture independent, but cannot be noarch packages due to libreoffice limitations. Such packages will generate empty debuginfo sub-packages. If this is the case, add '%global debug_package %\{nil}' to the package. .. + diff --git a/guidelines/modules/ROOT/pages/Meson.adoc b/guidelines/modules/ROOT/pages/Meson.adoc index f4bd8d7..343d3a2 100644 --- a/guidelines/modules/ROOT/pages/Meson.adoc +++ b/guidelines/modules/ROOT/pages/Meson.adoc @@ -27,9 +27,9 @@ You will generally make use of these in your specs: It is rarely necessary (but permissible) to use or alter these: `+%_vpath_srcdir+`:: - Path (relative to the build directory) where the sources to be built are located (default: `+.+`) + Path (relative to the RPM build directory) where the sources to be built are located (default: `+.+`) `+%_vpath_builddir+`:: - Path (relative to the build directory) where the The build directory (default: `+%{_target_platform}+`) + Path (relative to the RPM build directory) where the built objects are located (default: `+%{_target_platform}+`) `+%__meson+`:: The path to the meson executable diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index efe8f82..7eb0f4e 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -15,7 +15,7 @@ The MinGW SIG have written an RPM comparison tool which makes it possible to com == Follow Fedora policy -Cross compiled MinGW packages must follow Fedora policy, except where noted in this document. Cross compiled packages go through the same review process, GIT admin process etc as other Fedora packages. +Cross compiled MinGW packages must follow Fedora policy, except where noted in this document. Cross compiled packages go through the same review process, GIT admin process etc. as other Fedora packages. == Package naming @@ -147,7 +147,7 @@ These file lists can be included in the %files section for the targets: == Filenames of the cross-compilers and binutils -The MinGW cross-compilers and binutils are Fedora binaries and are therefore placed in `+%{_bindir}+` (ie. `+/usr/bin+`) according to the FHS and Fedora guidelines. +The MinGW cross-compilers and binutils are Fedora binaries and are therefore placed in `+%{_bindir}+` (i.e., `+/usr/bin+`) according to the FHS and Fedora guidelines. The MinGW cross-compilers and binutils which generate i686 binaries for Windows are named: @@ -162,7 +162,7 @@ The MinGW cross-compilers and binutils which generate i686 binaries for Windows The same binaries are present in `+%{_prefix}/i686-w64-mingw32/bin+` without any prefix in the -name, ie: +name, i.e., .... %{_prefix}/i686-w64-mingw32/bin/gcc @@ -403,7 +403,7 @@ the `+%{mingw32_libdir}+` directory. For example, for a library called `+foo+` t %{mingw32_libdir}/foo.dll.a .... -The `+foo.dll+` file is the main library, `+foo.dll.a+` is a stub linked to applications so they can find the library at runtime. All of these files are required in those locations in order to link successfully. The `+.dll+` may contain a version number although not always (eg. `+foo-0.dll+`). +The `+foo.dll+` file is the main library, `+foo.dll.a+` is a stub linked to applications so they can find the library at runtime. All of these files are required in those locations in order to link successfully. The `+.dll+` may contain a version number although not always (e.g., `+foo-0.dll+`). === Do not use %\{mingw32_bindir}/* or %\{mingw32_libdir}/* in %files section diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc index d263563..f0f63fb 100644 --- a/guidelines/modules/ROOT/pages/Naming.adoc +++ b/guidelines/modules/ROOT/pages/Naming.adoc @@ -287,7 +287,7 @@ the main package SHOULD contain only files common to all emacs compatible editors, and the code specific to each SHOULD be placed in a subpackage reflecting the specific editor $EDITOR-$NAME -eg. xemacs-$NAME, emacs-$NAME +e.g., xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An example of this scheme can be found in the package emacs-common-muse. @@ -332,7 +332,7 @@ See the xref:GAP.adoc#_naming[GAP guidelines] for the proper naming of GAP addon Packages that extend gnome shell SHOULD begin with the prefix `+gnome-shell-extension-+`. In particular, this prefix SHOULD NOT be pluralized -(ie: it SHOULD NOT be `+gnome-shell-extensions+`). +(i.e., it SHOULD NOT be `+gnome-shell-extensions+`). === LibreOffice extensions @@ -398,7 +398,7 @@ where CPANDIST is the name of the packaged CPAN module distribution (which is almost always also the unit of perl module packaging). In the rare cases when a CPAN module distribution needs to be split into smaller subpackages -eg. due to dependencies, +e.g., due to dependencies, the extra subpackages SHOULD be named perl-CPANDIST-Something. '''Examples: ''' diff --git a/guidelines/modules/ROOT/pages/Octave.adoc b/guidelines/modules/ROOT/pages/Octave.adoc index ae4ee7c..86c60bd 100644 --- a/guidelines/modules/ROOT/pages/Octave.adoc +++ b/guidelines/modules/ROOT/pages/Octave.adoc @@ -61,7 +61,7 @@ Limitations in the pkg function of octave (pkg.m) means that versioning of octav Octave maintains a list of installed packages in /usr/share/octave/octave_packages that needs to be updated on package install and removal. This file is in an octave plain-text format. -The contents of the /usr/share/octave/packages/ directory are scanned for the follwing files when performing a pkg('rebuild') from within octave. +The contents of the /usr/share/octave/packages/ directory are scanned for the following files when performing a pkg('rebuild') from within octave. * /usr/share/octave/packages/_NAMEOFPACKAGE_/packinfo/COPYING * /usr/share/octave/packages/_NAMEOFPACKAGE_/packinfo/DESCRIPTION @@ -202,7 +202,7 @@ Actuarial functions for Casualty and Property lines. === Summary of differences between arch-specific and noarch octave packages * Noarch packages set `+BuildArch: noarch+` -* Don't require a specific api version +* Don't require a specific API version * Noarch packages don't install anything into %\{octpkglibdir} === Obsoletes notes diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index d726f09..c811b7f 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -54,7 +54,7 @@ PEAR documentation provided by upstream are installed in %\{pear_docdir}, should PECL documentation provided by upstream are installed in %\{pecl_docdir}, should stay there, and must be marked as %doc. -The composer.json file is not used, and should be installed as %doc as it provides usefull information about the package and its dependencies. +The composer.json file is not used, and should be installed as %doc as it provides useful information about the package and its dependencies. == Requires and Provides diff --git a/guidelines/modules/ROOT/pages/Perl.adoc b/guidelines/modules/ROOT/pages/Perl.adoc index 50c4eb0..d60bbcf 100644 --- a/guidelines/modules/ROOT/pages/Perl.adoc +++ b/guidelines/modules/ROOT/pages/Perl.adoc @@ -74,7 +74,7 @@ Some packages link to `+libperl.so+`, usually to provide embedded Perl functiona === Filtering Requires and Provides -RPM's dependency generator can often throw in additional dependencies and will often think packages provide functionality contrary to reality. To fix this, the dependency generator needs to be overriden so that the additional dependencies can be filtered out. Please see https://fedoraproject.org/wiki/Packaging:AutoProvidesAndRequiresFiltering#Perl for information. +RPM's dependency generator can often throw in additional dependencies and will often think packages provide functionality contrary to reality. To fix this, the dependency generator needs to be overridden so that the additional dependencies can be filtered out. Please see https://fedoraproject.org/wiki/Packaging:AutoProvidesAndRequiresFiltering#Perl for information. === Manual Requires and Provides @@ -131,9 +131,9 @@ URL: https://metacpan.org/release/Net-XMPP == Testing and Test Suites -Perl packages typically have a large, healthy test suite. It is policy to run as much of the test suite as possible, subject to the technical limitations of the buildsystem. This means, at the least: +Perl packages typically have a large, healthy test suite. It is policy to run as much of the test suite as possible, subject to the technical limitations of the build system. This means, at the least: -* All modules required for tests should be listed as a buildrequires +* All modules required for tests should be listed as a BuildRequires * Any "optional" tests should be enabled * Any modules needed for the tests but not yet in Fedora that could be included in Fedora should also be submitted for review @@ -142,7 +142,7 @@ Perl packages typically have a large, healthy test suite. It is policy to run as There are a couple caveats here: * Optional tests do not need to be enabled if they will cause circular build deps -* Tests which require network or display access should be disabled for the buildsystem, but with a method provided for local builds +* Tests which require network or display access should be disabled for the build system, but with a method provided for local builds * Tests which do not test package functionality should still be invoked, but their exclusion not be considered a blocker (e.g. `+Test::Pod::Coverage+`, `+Test::Kwalitee+` and the like) * Author, "release candidate", or smoke tests do not need to be enabled e.g. tests using `+Perl::Critic+`. @@ -150,7 +150,7 @@ Additionally, for "meta" packages that provide a common interface to a number of == Conditionally enabling/disabling tests -One common way to disable a test for mock but enable it locally is to use a `+_with_foo+` macro test. e.g.: +One common way to disable a test for mock but enable it locally is to use a `+_with_foo+` macro test, e.g., .... %check @@ -158,11 +158,11 @@ One common way to disable a test for mock but enable it locally is to use a `+_w ./Build test .... -With this construct, an offending test will be removed and not executed, unless `+--with network_tests+` is passed to `+rpmbuild+` or %_with_network_tests is defined somewhere, e.g. in a user's `+$HOME/.rpmmacros+`. This approach preserves the test suite for local builds while working within the technical limitations of the buildsystem. +With this construct, an offending test will be removed and not executed, unless `+--with network_tests+` is passed to `+rpmbuild+` or %_with_network_tests is defined somewhere, e.g. in a user's `+$HOME/.rpmmacros+`. This approach preserves the test suite for local builds while working within the technical limitations of the build system. == Makefile.PL vs Build.PL -Perl modules typically utilize one of two different buildsystems: +Perl modules typically utilize one of two different build systems: * `+ExtUtils::MakeMaker+` * `+Module::Build+` diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc index 7b24bd4..15ee40d 100644 --- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc +++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc @@ -406,7 +406,7 @@ The script interpreter defined in `+%{__python}+` is used to compile the modules %global __python %{__python3} .... -Doing this is useful when you have a python3 application that's installing a private module into its own directory. For instance, if the foobar application installs a module for use only by the command line application in `+%{_datadir}/foobar+`. Since these files are not in one of the python3 library paths (ie. `+/usr/lib/python3.1+`) you have to override `+%{__python}+` to tell `+brp-python-bytecompile+` to use the python3 interpreter for byte compiling. +Doing this is useful when you have a python3 application that's installing a private module into its own directory. For instance, if the foobar application installs a module for use only by the command line application in `+%{_datadir}/foobar+`. Since these files are not in one of the python3 library paths (i.e., `+/usr/lib/python3.1+`) you have to override `+%{__python}+` to tell `+brp-python-bytecompile+` to use the python3 interpreter for byte compiling. These settings are enough to properly byte compile any package that builds python modules in `+%{python?_sitelib}+` or `+%{python?_sitearch}+` or builds for only a single python interpreter. However, if the application you're packaging needs to build with both python2 and python3 and install into a private module directory (perhaps because it provides one utility written in python2 and a second utility written in python3) then you need to do this manually. Here's a sample spec file snippet that shows what to do: diff --git a/guidelines/modules/ROOT/pages/Ruby.adoc b/guidelines/modules/ROOT/pages/Ruby.adoc index d8cb1e3..a5c1ea3 100644 --- a/guidelines/modules/ROOT/pages/Ruby.adoc +++ b/guidelines/modules/ROOT/pages/Ruby.adoc @@ -238,9 +238,9 @@ package names, dependencies, etc. for both. To keep confusion to a minimum, -terms relating to Gem concepts will be explicitly refereed to +terms relating to Gem concepts will be explicitly referred to with the word "Gem" prefixed, -eg "Gem specification" (.gemspec). +e.g., "Gem specification" (.gemspec). An unqualified "package" in the following always means an RPM. * Spec files MUST contain a definition of `+%{gem_name}+` diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 088fb07..519f531 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -29,7 +29,7 @@ of the rpm spec file. The scripts support a special flag, -p which allows the scriptlet to invoke a single program directly rather than having to spawn a shell to invoke the programs. -(ie: %post -p /sbin/ldconfig) +(i.e., %post -p /sbin/ldconfig) When scriptlets are called, they will be supplied with an argument. diff --git a/guidelines/modules/ROOT/pages/Systemd.adoc b/guidelines/modules/ROOT/pages/Systemd.adoc index 7f11e35..1d90c2f 100644 --- a/guidelines/modules/ROOT/pages/Systemd.adoc +++ b/guidelines/modules/ROOT/pages/Systemd.adoc @@ -50,7 +50,7 @@ The `+Description=+` line must not exceed 80 characters, and must describe the s ====== Documentation field -Systemd in Fedora 17+ has support for defining documentation in unit files via the Documentation= field (it is ignored in older releases, so it is safe to keep one systemd unit file across all branches). System administrators will be looking at the contents of the Documentation= field to determine what the service is, how to configure it, and where to locate additional documentation relating to the service. Accordingly, packagers are strongly encouraged to include any available sources in the Documentation= field which provide this information. If a man page or info page is present in the package, refer to it using "man:manpage" or "info:infofile" respectively. If the documentation is in plaintext, use "​file://path/to/file". Lastly, if no local documentation exists in the package, but it exists at a url, use the URL (with ​http://) in this field. Multiple URIs can be added to the Documentation= field, as a space separated list. For details on URI definitions and formatting, please refer to the uri(7) manpage (man uri). +Systemd in Fedora 17+ has support for defining documentation in unit files via the Documentation= field (it is ignored in older releases, so it is safe to keep one systemd unit file across all branches). System administrators will be looking at the contents of the Documentation= field to determine what the service is, how to configure it, and where to locate additional documentation relating to the service. Accordingly, packagers are strongly encouraged to include any available sources in the Documentation= field which provide this information. If a man page or info page is present in the package, refer to it using "man:manpage" or "info:infofile" respectively. If the documentation is in plaintext, use "file://path/to/file". Lastly, if no local documentation exists in the package, but it exists at a URL, use the URL (with http://) in this field. Multiple URIs can be added to the Documentation= field, as a space separated list. For details on URI definitions and formatting, please refer to the uri(7) manpage (man uri). ===== [Service] diff --git a/guidelines/modules/ROOT/pages/Tcl.adoc b/guidelines/modules/ROOT/pages/Tcl.adoc index 478d9ce..680b9f4 100644 --- a/guidelines/modules/ROOT/pages/Tcl.adoc +++ b/guidelines/modules/ROOT/pages/Tcl.adoc @@ -52,7 +52,7 @@ Both arch-specific and `+noarch+` Tcl extensions *must* use Requires: tcl(abi) = 8.6 .... -to indicate which Tcl version (8.5 in F19 and F20, 8.6 in F21+) they were built against. This is necessary because the guidelines below require extensions to be installed into tcl-versioned directories, which are only used by a single verison of Tcl. This does impose an inconvenience that all arch-specific and noarch extensions will need to be rebuilt for a new minor version of Tcl, but since new Tcl minor versions only appear once every few years, this should not be such a problematic inconvenience. +to indicate which Tcl version (8.5 in F19 and F20, 8.6 in F21+) they were built against. This is necessary because the guidelines below require extensions to be installed into tcl-versioned directories, which are only used by a single version of Tcl. This does impose an inconvenience that all arch-specific and noarch extensions will need to be rebuilt for a new minor version of Tcl, but since new Tcl minor versions only appear once every few years, this should not be such a problematic inconvenience. === noarch packages @@ -81,7 +81,7 @@ install -d $RPM_BUILD_ROOT%{tcl_sitelib} mv $RPM_BUILD_ROOT%{_datadir}/foobar%{version} $RPM_BUILD_ROOT%{tcl_sitelib}/foobar%{version} .... -It may also be acceptible to patch upstream's `+configure+` script and `+Makefile+` to add additional flexibility for the install directory, but the packager is not required to do this. +It may also be acceptable to patch upstream's `+configure+` script and `+Makefile+` to add additional flexibility for the install directory, but the packager is not required to do this. === arch-specific packages @@ -112,7 +112,7 @@ install -d $RPM_BUILD_ROOT%{tcl_sitearch} mv $RPM_BUILD_ROOT%{_libdir}/foobar%{version} $RPM_BUILD_ROOT%{tcl_sitearch}/foobar%{version} .... -arch-specific packages can be generally grouped into three categories: those that provide a shell, those that provide a fooConfig.sh file and a shared library for linking, and those that only provide a shared library for dlopen(). +Arch-specific packages can be generally grouped into three categories: those that provide a shell, those that provide a fooConfig.sh file and a shared library for linking, and those that only provide a shared library for dlopen(). *No shells:* Very few Tcl extension packages provide a shell. Providing a shell for an extension is frowned upon. The extension's shared library can be dynamically loaded into a Tcl interpreter through the standard `+package require ...+` mechanism without providing a shell that automatically loads the shared library. The exceptions to this rule are the shells that are commonly expected to be present on a system, including Tk (wish) and Expect (expect, expectk). @@ -126,4 +126,4 @@ Some arch-specific Tcl extensions provide a shared library and a corresponding ` If the extension does *not* provide a `+fooConfig.sh+` file, then the shared library *must not* be installed directly in `+%{_libdir}+`, but in the package-specific installation directory in `+%{tcl_sitearch}+` instead. This may require a patch to update the extension's `+pkgIndex.tcl+` file to look for the shared library in the correct location. *Stubs are ok if put in -devel subpackage:* -Some Tcl extensions provide a static 'stub' library. Stub libraries are a Tcl-ism to provide version-independent dynamic linking on a variety of platforms. These are not normal static libraries that provide the library's actual functionality, but instead provide a level of indirection pointing to the shared library. These stub libraries do not have the same static linking issues that are generally frowned upon in Fedora, and thus are acceptible. If a package provides such a stub library, it must be placed in a -devel subpackage. More information on stubs can be found on the Tcl wiki: http://wiki.tcl.tk/285 +Some Tcl extensions provide a static 'stub' library. Stub libraries are a Tcl-ism to provide version-independent dynamic linking on a variety of platforms. These are not normal static libraries that provide the library's actual functionality, but instead provide a level of indirection pointing to the shared library. These stub libraries do not have the same static linking issues that are generally frowned upon in Fedora, and thus are acceptable. If a package provides such a stub library, it must be placed in a -devel subpackage. More information on stubs can be found on the Tcl wiki: http://wiki.tcl.tk/285 diff --git a/guidelines/modules/ROOT/pages/UnownedDirectories.adoc b/guidelines/modules/ROOT/pages/UnownedDirectories.adoc index 0cf674b..b322c01 100644 --- a/guidelines/modules/ROOT/pages/UnownedDirectories.adoc +++ b/guidelines/modules/ROOT/pages/UnownedDirectories.adoc @@ -70,7 +70,7 @@ to include the directory _and_ the entire tree below it. %{_includedir}/%{name}-%{version}/*.h ---- -This is the same as the unversioned scenario with the addition that everytime the package is upgraded to a new version the old directory will remain on the filesystem. Correct would be: +This is the same as the unversioned scenario with the addition that every time the package is upgraded to a new version the old directory will remain on the filesystem. Correct would be: ---- %{_docdir}/%{name}-%{version}/ diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index e63d69b..af15c95 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -147,7 +147,7 @@ and in most situations `++` won't be used at all. Simply do not include those which you don't have. Note that the Dist tag is supplied by other portions of the system -and may in some circomstances contain additional structure, +and may in some circumstances contain additional structure, including tildes. As this is not under the control of the packager, that structure is not covered here. diff --git a/guidelines/modules/ROOT/pages/WeakDependencies.adoc b/guidelines/modules/ROOT/pages/WeakDependencies.adoc index d168f72..31c0b85 100644 --- a/guidelines/modules/ROOT/pages/WeakDependencies.adoc +++ b/guidelines/modules/ROOT/pages/WeakDependencies.adoc @@ -69,7 +69,7 @@ dependencies cannot enforce a older version of a package to be chosen. If there are multiple (typically virtual) providers for a dependency the requiring package may add a Suggests: to provide a hint to the dependency -resolver as to which poption is preferred. `+Enhances:+` should only +resolver as to which option is preferred. `+Enhances:+` should only be used for the rare occasion when the main package and other providers agree that adding the hint to the required package is for some reason the cleaner solution. diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index bfa5326..1832230 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -219,7 +219,7 @@ such as `+%{_libexecdir}/%{name}+`. If upstream's build scripts support the use of `+%{_libexecdir}+` then that is the most appropriate place to configure it -(eg. passing `+--libexecdir=%{_libexecdir}/%{name}+` to autotools configure). +(e.g., passing `+--libexecdir=%{_libexecdir}/%{name}+` to autotools configure). If upstream's build scripts do not support that, `+%{_libdir}/%{name}+` is a valid second choice. If you have to patch support for using one of these directories in, @@ -441,7 +441,7 @@ Fedora packages which use `+pkg-config+` to build against a library (e.g. 'foo') == Conditional build-time dependencies -If the spec file contains conditional dependencies selected based on presence of optional `+--with(out) foo+` arguments to `+rpmbuild+`, build the source RPM to be submitted with the default options, ie. so that none of these arguments are present in the `+rpmbuild+` command line. The reason is that those requirements get "serialized" into the resulting source RPM, ie. the conditionals no longer apply. +If the spec file contains conditional dependencies selected based on presence of optional `+--with(out) foo+` arguments to `+rpmbuild+`, build the source RPM to be submitted with the default options, i.e., so that none of these arguments are present in the `+rpmbuild+` command line. The reason is that those requirements get "serialized" into the resulting source RPM, i.e., the conditionals no longer apply. == Summary and description @@ -711,7 +711,7 @@ object with which it should link. This allows developers to simply link against unversioned library symlink and the dynamic linker will link against the correct object. -Keep in mind that although the filename is usually the library's SONAME plus an incrementing minor version there's nothing that intrinsically links these. ldconfig uses the SONAME as the value for a symlink to the actual filename. The dynamic linker then uses that symlink to find the library, disregarding the actual filename. The dynamic linker merely does a simple equality check on the field and does not check for ABI incompatibilities or similar problems. This is the main reason for using an {abi-comparison-tool} and incrementing the the SONAME. +Keep in mind that although the filename is usually the library's SONAME plus an incrementing minor version there's nothing that intrinsically links these. ldconfig uses the SONAME as the value for a symlink to the actual filename. The dynamic linker then uses that symlink to find the library, disregarding the actual filename. The dynamic linker merely does a simple equality check on the field and does not check for ABI incompatibilities or similar problems. This is the main reason for using an {abi-comparison-tool} and incrementing the SONAME. The SONAME field is written to the shared object by linker, using (at least in case of `+ld+`) the `+-soname SONAME+` flags. This can be passed as an option to `+gcc+` like this: @@ -728,9 +728,9 @@ $ objdump -p /path/to/libfoo.so.0.n | grep 'SONAME' [#packaging-static-libraries] == Packaging Static Libraries -Packages including libraries SHOULD exclude static libs as far as possible (eg by configuring with _--disable-static_). Applications linking against libraries SHOULD link against shared libraries not static versions. +Packages including libraries SHOULD exclude static libs as far as possible (e.g., by configuring with _--disable-static_). Applications linking against libraries SHOULD link against shared libraries not static versions. -Libtool archives, _foo.la_ files, SHOULD NOT be included. Packages using libtool will install these by default even if you configure with _--disable-static_, so they may need to be removed before packaging. Due to bugs in older versions of libtool or bugs in programs that use it, there are times when it is not always possible to remove *.la files without modifying the program. In most cases it is fairly easy to work with upstream to fix these issues. Note that if you are updating a library in a stable release (not devel) and the package already contains *.la files, removing the *.la files SHOULD be treated as an API/ABI change -- ie: Removing them changes the interface that the library gives to the rest of the world thus MUST follow Fedora policies for potentially destabilizing updates. +Libtool archives, _foo.la_ files, SHOULD NOT be included. Packages using libtool will install these by default even if you configure with _--disable-static_, so they may need to be removed before packaging. Due to bugs in older versions of libtool or bugs in programs that use it, there are times when it is not always possible to remove *.la files without modifying the program. In most cases it is fairly easy to work with upstream to fix these issues. Note that if you are updating a library in a stable release (not devel) and the package already contains *.la files, removing the *.la files SHOULD be treated as an API/ABI change -- i.e., removing them changes the interface that the library gives to the rest of the world thus MUST follow Fedora policies for potentially destabilizing updates. === Packaging Static Libraries @@ -995,8 +995,8 @@ Mixing the two styles, while valid, is bad from a QA and usability point of view Fedora's RPM includes a `+%makeinstall+` macro but it must *NOT* be used when make install DESTDIR=%\{buildroot} works. %makeinstall is a kludge that can work with Makefiles that don't make use of the DESTDIR variable but it has the following potential issues: -* `+%makeinstall+` overrides a set of Make variables during "make install" and prepends the %\{buildroot} path. I.e. it performs make prefix="%\{buildroot}%\{_prefix}" libdir="%\{buildroot}%\{_libdir} ...". -* It is error-prone and can have unexpected effects when run against less than perfect Makefiles, e.g. the buildroot path may be included in installed files where variables are substituted at install-time. +* `+%makeinstall+` overrides a set of Make variables during "make install" and prepends the %\{buildroot} path, i.e. it performs make prefix="%\{buildroot}%\{_prefix}" libdir="%\{buildroot}%\{_libdir} ...". +* It is error-prone and can have unexpected effects when run against less than perfect Makefiles, e.g., the buildroot path may be included in installed files where variables are substituted at install-time. * It can trigger unnecessary and wrong rebuilds when executing "make install", since the Make variables have different values compared with the %build section. * If a package contains libtool archives, it can cause broken *.la files to be installed. @@ -1051,11 +1051,11 @@ Note: If you call perl or python in your spec file (and it is not already a Buil Use `+%global+` instead of `+%define+`, unless you really need only locally defined submacros within other macro definitions (a very rare case). -Rationale: The two macro defining statements behave the same when they are a the top level of rpm's nesting level. +Rationale: The two macro defining statements behave the same when they are at the top level of rpm's nesting level. But when they are used in nested macro expansions (like in `+%{!?foo: ... }+` constructs, `+%define+` theoretically only lasts until the end brace (local scope), while `+%global+` definitions have global scope. -Note that %define and %global differ in more ways than just scope: the body of a %define'd macro is lazily expanded (ie when used), but the body of %global is expanded at definition time. It's possible to use %%-escaping to force lazy expansion of %global. +Note that %define and %global differ in more ways than just scope: the body of a %define'd macro is lazily expanded (i.e., when used), but the body of %global is expanded at definition time. It's possible to use %%-escaping to force lazy expansion of %global. == Handling Locale Files @@ -1192,9 +1192,9 @@ Since these are config files, they must be marked as %config(noreplace) in the % == Timestamps -When adding file copying commands in the spec file, consider using a command that preserves the files' timestamps, eg. `+cp -p+` or `+install -p+`. +When adding file copying commands in the spec file, consider using a command that preserves the files' timestamps, e.g., `+cp -p+` or `+install -p+`. -When downloading sources, patches etc, consider using a client that preserves the upstream timestamps. For example `+wget -N+` or `+curl -R+`. To make the change global for wget, add this to your `+~/.wgetrc+`: `+timestamping = on+`, and for curl, add to your `+~/.curlrc+`: `+-R+`. +When downloading sources, patches etc., consider using a client that preserves the upstream timestamps. For example `+wget -N+` or `+curl -R+`. To make the change global for wget, add this to your `+~/.wgetrc+`: `+timestamping = on+`, and for curl, add to your `+~/.curlrc+`: `+-R+`. == Parallel make @@ -1539,7 +1539,7 @@ Explicit `+Provides:+` need to be aware of whether the package is supplying thin Examples of packages that should explicitly provide only arch-specific `+Provides:+` include native code libraries or plug-ins and their associated -devel packages. Packages that should explicitly provide only arch-independent `+Provides:+` include most stand-alone programs (in addition to all noarch packages). Even though these programs may themselves be arch-specific, clients that run them should not care about their arch in most cases. A package that explicitly provides, for example, both a native code library as well as an interpreted language interface to that library should have both arch-specific (for clients of the native code library) and arch-independent (for clients of the interpreted language interface) Provides:. -If there is no standard naming for a package or other long term naming compatibility requirements involved with the rename, the Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one (ie. if introduced in FC-X, keep in all subsequent package revisions for distros FC-X and FC-(X+1), drop in FC-(X+2)), and the distro version where it is planned to be dropped documented in a comment in the specfile. Maintainers of affected packages should be notified and encouraged to switch to use the new name. Forward compatibility Provides: in older distro branches can be considered in order to make it possible for package maintainers to keep same simple specfiles between branches but still switch to the newer name. +If there is no standard naming for a package or other long term naming compatibility requirements involved with the rename, the Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one (i.e., if introduced in FC-X, keep in all subsequent package revisions for distros FC-X and FC-(X+1), drop in FC-(X+2)), and the distro version where it is planned to be dropped documented in a comment in the specfile. Maintainers of affected packages should be notified and encouraged to switch to use the new name. Forward compatibility Provides: in older distro branches can be considered in order to make it possible for package maintainers to keep same simple specfiles between branches but still switch to the newer name. For packages that are not usually pulled in by using the package name as the dependency such as library only packages (which are pulled in through library soname depenencies), there's usually no need to add the Provides. Note however that the -devel subpackages of lib packages are pulled in as build dependencies using the package name, so adding the Provides is often appropriate there. @@ -1561,7 +1561,7 @@ If an update to your package resolves a known security concern (at the time of t == 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. +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 (i.e., 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. [#bootstrapping] == Bootstrapping @@ -1592,7 +1592,7 @@ TIP: Since Fedora 30, when bootstrapping mode is enabled, the `+~bootstrap+` suffix is appended to the dist tag. This avoids the need to bump release - between bootsrap and final build. + between bootstrap and final build. You can temporarily enable bootstrapping by commit, which changes `+%bcond_with bootstrap+` to `+%bcond_without bootstrap+` and later reverting the commit to do final build.