From 786b5fe0cc09965634ea6d389ebcc7ad032ba209 Mon Sep 17 00:00:00 2001 From: Jibec Date: Apr 19 2020 14:01:11 +0000 Subject: suppress indentation warning --- diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc index 74867cf..4edce9f 100644 --- a/guidelines/modules/ROOT/pages/Ada.adoc +++ b/guidelines/modules/ROOT/pages/Ada.adoc @@ -11,20 +11,20 @@ and the link:../ReviewGuidelines/[Review Guidelines]. == Compilation * Ada code in Fedora *MUST* be compiled using GNAT, the default Ada compiler in Fedora. -All packages that contain Ada code *MUST* have “`+BuildRequires: gcc-gnat+`” -to ensure that the compiler is available. + All packages that contain Ada code *MUST* have “`+BuildRequires: gcc-gnat+`” + to ensure that the compiler is available. * There are a number of RPM macros that contain Fedora’s standard compiler and linker flags adapted for GNAT. -The appropriate macro *MUST* be used in the build stage. The right macro to use depends on what build tools the package uses. + The appropriate macro *MUST* be used in the build stage. The right macro to use depends on what build tools the package uses. ** For packages that are built with Gnatmake or GPRbuild but without Comfignat -there are the macros +++Gnatmake_optflags+++ and +++GPRbuild_optflags+++, -which contain builder, compiler and linker flags. + there are the macros +++Gnatmake_optflags+++ and +++GPRbuild_optflags+++, + which contain builder, compiler and linker flags. ** In case a package’s build system invokes the underlying GNAT tools without using Gnatmake or GPRbuild, -then the appropriate macro for each tool *MUST* be used. -If for example Gnatlink is invoked directly, then the expansion of +++Gnatlink_flags+++ shall be passed to it. + then the appropriate macro for each tool *MUST* be used. + If for example Gnatlink is invoked directly, then the expansion of +++Gnatlink_flags+++ shall be passed to it. ** For packages whose build systems use Comfignat there is the macro +++Comfignat_make+++. -It expands to a Make command with appropriate values for Comfignat’s configuration variables, -including builder, compiler and linker flags, directory variables and the directories project. -Use it alone to build the default target: + It expands to a Make command with appropriate values for Comfignat’s configuration variables, + including builder, compiler and linker flags, directory variables and the directories project. + Use it alone to build the default target: + .... %build @@ -39,13 +39,13 @@ If needed, a different target and/or additional variables may be appended: + For the installation stage of Comfignat-using packages, the macro +++make_install+++ (*not* +++makeinstall+++) is recommended. * The macro +++GNAT_arches+++ expands to a list of architectures where GNAT packages are available in Fedora. -Starting with Fedora 18, when there is a need to prevent attempts to build an Ada package on secondary architectures where GNAT has not been bootstrapped, -this *MUST* be done with “`+ExclusiveArch: %{GNAT_arches}+`”. + Starting with Fedora 18, when there is a need to prevent attempts to build an Ada package on secondary architectures where GNAT has not been bootstrapped, + this *MUST* be done with “`+ExclusiveArch: %{GNAT_arches}+`”. * All packages that contain Ada code *MUST* have “`+BuildRequires: fedora-gnat-project-common+`” to ensure that the necessary RPM macros are defined. * If the upstream source package comes with a build system, -for example a GNAT project file or makefiles and a configuration script, -then it’s probably best to use that if possible. -If not, it is recommended that the packager write a GNAT project file to control the compilation. + for example a GNAT project file or makefiles and a configuration script, + then it’s probably best to use that if possible. + If not, it is recommended that the packager write a GNAT project file to control the compilation. == Runpaths @@ -66,12 +66,12 @@ All packages that use +++GNAT_add_rpath+++ *MUST* do this == Devel packages * Ada library packages *MUST* have a -devel subpackage containing all the files that are necessary for compilation of code that uses the library. -This includes +Ada specification files (*.ads), -Ada body files (*.adb), -Ada library information files (*.ali) -and GNAT project files (*.gpr).+ -(There is no requirement to include all body files. -Typically only some body files are needed.) + This includes +Ada specification files (*.ads), + Ada body files (*.adb), + Ada library information files (*.ali) + and GNAT project files (*.gpr).+ + (There is no requirement to include all body files. + Typically only some body files are needed.) * The -devel package *MUST NOT* contain any makefiles or other files that are only used for recompiling the library. * The -devel package *MUST NOT* contain any +*.o+ files. @@ -79,16 +79,16 @@ Typically only some body files are needed.) * The -devel package *MUST* contain one or more GNAT project files to be imported by other projects that use the library. * Project files *MUST* be architecture-independent. -This means that the same project file must point to libraries in /usr/lib or /usr/lib64 depending on what target architecture the compiler is currently compiling for. -This *SHOULD* be done by importing the “directories” project -(that is, the project file directories.gpr) -and using the variable +++Directories.Libdir+++ which is defined there. -The value of +++Directories.Libdir+++ is set to either “/usr/lib” or “/usr/lib64” depending on the hardware platform. + This means that the same project file must point to libraries in /usr/lib or /usr/lib64 depending on what target architecture the compiler is currently compiling for. + This *SHOULD* be done by importing the “directories” project + (that is, the project file directories.gpr) + and using the variable +++Directories.Libdir+++ which is defined there. + The value of +++Directories.Libdir+++ is set to either “/usr/lib” or “/usr/lib64” depending on the hardware platform. * Project files *MUST NOT* contain hard-coded directory names, neither absolute nor relative; they should get them from some source. -The source may be an Autoconf-generated configuration script or other build system. -Project files that aren’t pre-processed by such a build system *SHOULD* use the variable +++Directories.Includedir+++ rather than a hard-coded “/usr/include”. + The source may be an Autoconf-generated configuration script or other build system. + Project files that aren’t pre-processed by such a build system *SHOULD* use the variable +++Directories.Includedir+++ rather than a hard-coded “/usr/include”. * If the “directories” project is used, -then the -devel package *MUST* have an explicit “`+Requires: fedora-gnat-project-common+`”. + then the -devel package *MUST* have an explicit “`+Requires: fedora-gnat-project-common+`”. * Project files *MUST* have an +++Externally_Built+++ attribute equal to “true”. Here’s an example of what a project file installed with a library may look like: @@ -107,16 +107,16 @@ end Example; == File placement * Ada source files in -devel packages (+*.ads and *.adb+) -*MUST* be placed in the `+%{_includedir}+` directory or a subdirectory thereof. -Placing them directly in `+%{_includedir}+` may be appropriate if there are very few of them in the package and their names include the name of the library. -Otherwise they should usually be placed in a subdirectory, for example `+%{_includedir}/%{name}+`. + *MUST* be placed in the `+%{_includedir}+` directory or a subdirectory thereof. + Placing them directly in `+%{_includedir}+` may be appropriate if there are very few of them in the package and their names include the name of the library. + Otherwise they should usually be placed in a subdirectory, for example `+%{_includedir}/%{name}+`. * Ada library information files (+*.ali+) -*MUST* be placed in a subdirectory of `+%{_libdir}+`, for example `+%{_libdir}/%{name}+`. + *MUST* be placed in a subdirectory of `+%{_libdir}+`, for example `+%{_libdir}/%{name}+`. * GNAT projects files (+*.gpr+) -*MUST* be placed in the `+%{_GNAT_project_dir}+` directory or a subdirectory thereof. -A subdirectory, for example `+%{_GNAT_project_dir}/%{name}+`, may be a good idea if there are lots of project files in the same package or if they have generic names. -Otherwise they should usually be placed directly in `+%{_GNAT_project_dir}+`. -The name of the library *MUST* be included either in the name of each project file or in the name of the subdirectory where the project files are placed. + *MUST* be placed in the `+%{_GNAT_project_dir}+` directory or a subdirectory thereof. + A subdirectory, for example `+%{_GNAT_project_dir}/%{name}+`, may be a good idea if there are lots of project files in the same package or if they have generic names. + Otherwise they should usually be placed directly in `+%{_GNAT_project_dir}+`. + The name of the library *MUST* be included either in the name of each project file or in the name of the subdirectory where the project files are placed. == Rpmlint and Ada packages diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 520e47c..c88c464 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -30,7 +30,7 @@ inconvenient. * it may differ from the repository URL; * generally, the correct value will be the one used by the project in its -documentation, coding examples, and build assertions; + documentation, coding examples, and build assertions; * use the gopkg import path for all code states when a project uses it. If upstream confused itself after multiple forks and renamings, you will need @@ -43,20 +43,20 @@ Perform this fixing in `+%prep+`. === Source packages (src.rpm) * Golang source packages MUST be named after their main import path. -This -process is automated by the `+%{goname}+` macro. -This macro will remove any capitalization, "go" keywords, and any duplication in -the import path. + This + process is automated by the `+%{goname}+` macro. + This macro will remove any capitalization, "go" keywords, and any duplication in + the import path. + For example: + -- ** the import path `+github.com/kr/pretty+` will become -`+golang-github-kr-pretty+` + `+golang-github-kr-pretty+` ** the import path `+github.com/DATA-DOG/go-txdb+` will become -`+golang-github-data-dog-txdb+` + `+golang-github-data-dog-txdb+` ** the import path `+github.com/gopherjs/gopherjs+` will become -`+golang-github-gopherjs+` + `+golang-github-gopherjs+` -- + @@ -73,10 +73,10 @@ simply build the SRPM with: The SRPM filename will be the one to use in your rpmspec and spec filename. * Source packages that provide a well-known application such as `+etcd+` -MUST be named after the application. -End users do not care about the language their applications are written in. But -do not name packages after an obscure utility binary that happens to be built by -the package. + MUST be named after the application. + End users do not care about the language their applications are written in. But + do not name packages after an obscure utility binary that happens to be built by + the package. ==== Implementation: `+%{gorpmname}+` @@ -357,7 +357,7 @@ incompatible with a secure build environment such as mock: * tests that call a remote server or API over the Internet, * tests that attempt to reconfigure the system, * tests that rely on a specific app running on the system, like a database -or syslog server. + or syslog server. If a test is broken for some other reason, you can disable it the same way. However, you SHOULD also report the problem upstream. Remember to trace in a @@ -554,7 +554,7 @@ them just after the `+%goprep+` line: * replace calls to deprecated import paths with their correct value * patch code problems * remove dead code (some upstreams deliberately ship broken source code in -the hope someone will get around to fix it) + the hope someone will get around to fix it) [NOTE] ==== diff --git a/guidelines/modules/ROOT/pages/Golang_advanced.adoc b/guidelines/modules/ROOT/pages/Golang_advanced.adoc index 3d8df21..30bd1d4 100644 --- a/guidelines/modules/ROOT/pages/Golang_advanced.adoc +++ b/guidelines/modules/ROOT/pages/Golang_advanced.adoc @@ -275,7 +275,7 @@ golang-cloud-google-devel(x86-64) = 0.36.0-1.fc31 golang-ipath(cloud.google.com/go) = 0.36.0-1.fc31 ---- * `+golang-cloud-google-compute-devel-0.36.0-1.fc31.x86_64.rpm+`, which -provides: + provides: + [source] ---- diff --git a/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc b/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc index d320ff5..418a35c 100644 --- a/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc +++ b/guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc @@ -8,7 +8,7 @@ 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. .. + -An example is... + + An example is... + .... %global extname writer2latex diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc index 1ba4084..268349e 100644 --- a/guidelines/modules/ROOT/pages/Naming.adoc +++ b/guidelines/modules/ROOT/pages/Naming.adoc @@ -64,14 +64,14 @@ for more info on this case). There are a few exceptions to the no underscore '_' rule. * httpd, pam, and SDL addon packages are excluded, -refer to "'''Addon Packages <> '''". + refer to "'''Addon Packages <> '''". * packages that are locale specific, -and use the locale in the name are excluded, -refer to "'''Addon Packages <> '''". + and use the locale in the name are excluded, + refer to "'''Addon Packages <> '''". * Compat packages where the base package name ends in a digit. -refer to "*<>*" + refer to "*<>*" * packages where the upstream name naturally contains an underscore -are excluded from this. Examples of these packages include: + are excluded from this. Examples of these packages include: .... arptables_jf @@ -138,28 +138,28 @@ suffixed by either: * The package version, which SHOULD include the periods present in the original version. ** If the base package name ends with a digit, -a single underscore ("_") MUST be appended to the name, -and the version MUST be appended to that, -in order to avoid confusion over where the name ends and the version begins. + a single underscore ("_") MUST be appended to the name, + and the version MUST be appended to that, + in order to avoid confusion over where the name ends and the version begins. ** If the base package name does not end with a digit, -the version MUST be directly appended to the package name with no intervening separator. + the version MUST be directly appended to the package name with no intervening separator. * a hyphen ("-") followed by a descriptive suffix -such as "stable" -which provides some indication -as to the nature of the packaged version. + such as "stable" + which provides some indication + as to the nature of the packaged version. *Examples:* * The python-sqlalchemy package occasionally has multiple versions in Fedora -for backwards compatibility. -The most current version of python-sqlalchemy is named -`+python-sqlalchemy+` -and an older supported version is -`+python-sqlalchemy0.5+`. -No delimiter is used in this situation. + for backwards compatibility. + The most current version of python-sqlalchemy is named + `+python-sqlalchemy+` + and an older supported version is + `+python-sqlalchemy0.5+`. + No delimiter is used in this situation. * The most current version of the v8 package is named `+v8+`. -In order to package version "3.13", -the package MUST be named `+v8_3.13+`. + In order to package version "3.13", + the package MUST be named `+v8_3.13+`. Please also note that strings such as "-latest" can often become misleading over time diff --git a/guidelines/modules/ROOT/pages/Ruby.adoc b/guidelines/modules/ROOT/pages/Ruby.adoc index a5c1ea3..4cd6bac 100644 --- a/guidelines/modules/ROOT/pages/Ruby.adoc +++ b/guidelines/modules/ROOT/pages/Ruby.adoc @@ -105,22 +105,22 @@ All other code SHOULD use `+#!/usr/bin/ruby+`. == Naming Guidelines * Packages that contain Ruby Gems MUST be called -`+rubygem-%{gem_name}+`. + `+rubygem-%{gem_name}+`. * The name of a ruby extension/library package MUST start -with the interpreter it is built for -(ruby, jruby, etc.) -and then the `UPSTREAM` name. -For example: `ruby-UPSTREAM`. -If the upstream name `UPSTREAM` contains `ruby`, -that SHOULD be dropped from the name. -For example, the SQLite database driver for ruby is called `sqlite3-ruby`. -The corresponding Fedora package SHOULD be called `ruby-sqlite3`, -and not `ruby-sqlite3-ruby`. + with the interpreter it is built for + (ruby, jruby, etc.) + and then the `UPSTREAM` name. + For example: `ruby-UPSTREAM`. + If the upstream name `UPSTREAM` contains `ruby`, + that SHOULD be dropped from the name. + For example, the SQLite database driver for ruby is called `sqlite3-ruby`. + The corresponding Fedora package SHOULD be called `ruby-sqlite3`, + and not `ruby-sqlite3-ruby`. * Application packages that mainly provide user-level tools -that happen to be written in Ruby MUST follow -the general xref:Naming.adoc[Naming Guidelines] instead. + that happen to be written in Ruby MUST follow + the general xref:Naming.adoc[Naming Guidelines] instead. == Macros @@ -244,24 +244,24 @@ e.g., "Gem specification" (.gemspec). An unqualified "package" in the following always means an RPM. * Spec files MUST contain a definition of `+%{gem_name}+` -which is the name from the Gem's specification. + which is the name from the Gem's specification. * The `Source` of the package MUST be -the full URL to the released Gem archive; -the version of the package MUST be the Gem's version. + the full URL to the released Gem archive; + the version of the package MUST be the Gem's version. * The package MUST have -`BuildRequires: rubygems-devel` -to pull in the macros needed to build. + `BuildRequires: rubygems-devel` + to pull in the macros needed to build. * There SHOULD NOT be any rubygem `Requires` nor `Provides` listed, -since those are autogenerated. + since those are autogenerated. * There SHOULD NOT be `Requires: ruby(release)`, -unless you want to explicitly specify Ruby version compatibility. -The automatically generated dependency on RubyGems -(`Requires: ruby(rubygems)`) -is enough. + unless you want to explicitly specify Ruby version compatibility. + The automatically generated dependency on RubyGems + (`Requires: ruby(rubygems)`) + is enough. ==== Filtering Requires and Provides diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc index 1d91161..c251c7e 100644 --- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc +++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc @@ -186,44 +186,44 @@ exit 0 === Values given to useradd and groupadd * `+HOMEDIR+` should usually be a directory created and owned by the package, -with appropriately restrictive permissions. -One good choice for the location of the directory -is the package's data directory in case it has one. + with appropriately restrictive permissions. + One good choice for the location of the directory + is the package's data directory in case it has one. * `+USERNAME+` and `+GROUPNAME+` are the symbolic names used by your package. -Be aware that all code in the package should use these names, -not the UID or GID. -If this is not possible, please mention it within the ticket -so that the FPC can see if this is a different type of problem than we usually encounter. + Be aware that all code in the package should use these names, + not the UID or GID. + If this is not possible, please mention it within the ticket + so that the FPC can see if this is a different type of problem than we usually encounter. * `+ALLOCATED_UID+` and `+ALLOCATED_GID+` are the UID and GID -that FPC tells you has been allocated for use by your package. + that FPC tells you has been allocated for use by your package. * User accounts created by packages are rarely used for interactive logons, -and should thus generally use `+/sbin/nologin+` as the user's shell. + and should thus generally use `+/sbin/nologin+` as the user's shell. === Rationale for some of the implementation choices * We run `+getent+` before `+groupadd+` and `+useradd+` -to check whether the user/group we're about to create -already exists and skip the creation if they do. -This is what allows the local system administrators -to customize the users and groups beforehand -in case they wish to get a predefined static UID/GID mapping for those users. -Similarly, we verify whether the ID values -allocated in the "setup" package -aren't already allocated by the local system administrators. + to check whether the user/group we're about to create + already exists and skip the creation if they do. + This is what allows the local system administrators + to customize the users and groups beforehand + in case they wish to get a predefined static UID/GID mapping for those users. + Similarly, we verify whether the ID values + allocated in the "setup" package + aren't already allocated by the local system administrators. * We want to invoke `+groupadd+` explicitly -instead of relying on `+useradd+` to create the group for us. -This is because `+useradd+` alone would fail -if the group it tries to create already existed. + instead of relying on `+useradd+` to create the group for us. + This is because `+useradd+` alone would fail + if the group it tries to create already existed. * We run the `+groupadd+`/`+useradd+` always --- both on initial installs and upgrades -- in `+%pre+`. -This is made possible by the `+getent+` checks above, -and should fix things up if the user/group has disappeared -after the package to be upgraded was initially installed -(just like file permissions get reset on upgrades etc). + -- both on initial installs and upgrades -- in `+%pre+`. + This is made possible by the `+getent+` checks above, + and should fix things up if the user/group has disappeared + after the package to be upgraded was initially installed + (just like file permissions get reset on upgrades etc). * The `+exit 0+` at the end will result in the `+%pre+` scriptlet -passing through even if the user/group creation fails for some reason. -This is suboptimal but has less potential for system wide breakage -than allowing it to fail. -If the user/group aren't available -at the time the package's payload is unpacked, -rpm will fall back to setting those files owned by root. + passing through even if the user/group creation fails for some reason. + This is suboptimal but has less potential for system wide breakage + than allowing it to fail. + If the user/group aren't available + at the time the package's payload is unpacked, + rpm will fall back to setting those files owned by root. diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index d9ad7de..72e2bf0 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -305,7 +305,7 @@ The FHS defines where files should be placed on the system. * Fedora allows cross-compilers to place files in `+/usr/target+`. * Fedora does not allow new directories -directly under `+/+` or `+/usr+` without FPC approval. + directly under `+/+` or `+/usr+` without FPC approval. === Libexecdir