PR#972: suppress indentation warning - packaging-committee

packaging-committee

#972 suppress indentation warning

Merged 3 years ago by pbokoc. Opened 4 years ago by jibecfed.

jibecfed/packaging-committee indent into master

suppress indentation warning

Jibec • 4 years ago

786b5fe

guidelines/modules/ROOT/pages/Ada.adoc

file modified

+37 -37

		`@@ -11,20 +11,20 @@`
		`== 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 +++<var>Gnatmake_optflags</var>+++ and +++<var>GPRbuild_optflags</var>+++,`
		`- which contain builder, compiler and linker flags.`
		`+ there are the macros +++<var>Gnatmake_optflags</var>+++ and +++<var>GPRbuild_optflags</var>+++,`
		`+ 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 +++<var>Gnatlink_flags</var>+++ 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 +++<var>Gnatlink_flags</var>+++ shall be passed to it.`
		`** For packages whose build systems use Comfignat there is the macro +++<var>Comfignat_make</var>+++.`
		`- 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 @@`
		`+`
		`For the installation stage of Comfignat-using packages, the macro +++<var>make_install</var>+++ (not +++<var>makeinstall</var>+++) is recommended.`
		`* The macro +++<var>GNAT_arches</var>+++ 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 @@`
		`== 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 @@`

		`* 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 +++<var>Directories.Libdir</var>+++ which is defined there.`
		`- The value of +++<var>Directories.Libdir</var>+++ 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 +++<var>Directories.Libdir</var>+++ which is defined there.`
		`+ The value of +++<var>Directories.Libdir</var>+++ 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 +++<var>Directories.Includedir</var>+++ 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 +++<var>Directories.Includedir</var>+++ 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 +++<var>Externally_Built</var>+++ attribute equal to “true”.`

		`Here’s an example of what a project file installed with a library may look like:`
		`@@ -107,16 +107,16 @@`
		`== 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`

guidelines/modules/ROOT/pages/Golang.adoc

file modified

+14 -14

		`@@ -30,7 +30,7 @@`

		`* 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 @@`
		`=== 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 @@`
		`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 @@`
		`* 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 @@`
		`* 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]`
		`====`

guidelines/modules/ROOT/pages/Golang_advanced.adoc

file modified

+1 -1

		`@@ -275,7 +275,7 @@`
		`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]`
		`----`

guidelines/modules/ROOT/pages/LibreOfficeExtensions.adoc

file modified

+1 -1

		`@@ -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`

guidelines/modules/ROOT/pages/Naming.adoc

file modified

+20 -20

		`@@ -64,14 +64,14 @@`
		`There are a few exceptions to the no underscore '_' rule.`

		`* httpd, pam, and SDL addon packages are excluded,`
		`- refer to "'''Addon Packages <<httpd, pam, and SDL>> '''".`
		`+ refer to "'''Addon Packages <<httpd, pam, and SDL>> '''".`
		`* packages that are locale specific,`
		`- and use the locale in the name are excluded,`
		`- refer to "'''Addon Packages <<locales>> '''".`
		`+ and use the locale in the name are excluded,`
		`+ refer to "'''Addon Packages <<locales>> '''".`
		`* Compat packages where the base package name ends in a digit.`
		`- refer to "<<Multiple packages with the same base name>>"`
		`+ refer to "<<Multiple packages with the same base name>>"`
		`* 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 @@`

		`* 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`

guidelines/modules/ROOT/pages/Ruby.adoc

file modified

+22 -22

		`@@ -105,22 +105,22 @@`
		`== 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 @@`
		`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`

guidelines/modules/ROOT/pages/UsersAndGroups.adoc

file modified

+31 -31

		`@@ -186,44 +186,44 @@`
		`=== 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.`

guidelines/modules/ROOT/pages/index.adoc

file modified

+1 -1

		`@@ -305,7 +305,7 @@`
		* 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`

jibecfed commented 4 years ago

in the internationalization system of our docs, the tool po4a we use to convert asciidoc files into pot displays three lines of warning for each missing indentation.

most of the time it is cosmetic issues in adoc (like here), but sometimes it's po4a bugs that I want to see
this PR has no impact on your rendering, it is fully cosmetic