From 67521a18e0a97b0709cf1935d8c42918e3bb5535 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 20 2021 20:35:59 +0000
Subject: [PATCH 1/9] Remove mention of F28


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 732efe4..3e67b31 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -3113,7 +3113,7 @@ For example, to disable the brp-python-bytecompile script:
 Any package that disables a BRP script this way MUST also note the reason
 in an accompanying comment.
 For a list of the BRP scripts run by default,
-on F28 and newer invoke: `+fgrep '%__brp_' /usr/lib/rpm/redhat/macros+`
+invoke: `+fgrep '%__brp_' /usr/lib/rpm/redhat/macros+`
 
 == Packaging for EPEL
 

From c3b4c91b061a00ab853e7eceee673a611dd905f6 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 20 2021 20:35:59 +0000
Subject: [PATCH 2/9] More consistent section headings


I tried to apply more consistent capitalization for section headings,
and use source code formatting where appropriate in those headings.

I have left some headings alone because they were seemingly intended to
be complete sentences, which is pretty bad but not something I want to
change in a "small fixes" series.

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 3e67b31..1011c8d 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -117,7 +117,7 @@ and the xref:LicensingGuidelines.adoc[Licensing Guidelines]
 to ensure that your package is licensed appropriately
 and that the license is properly indicated.
 
-=== Fedora trademarks
+=== Fedora Trademarks
 
 Packagers *MUST NOT* add any Fedora trademark assets
 including the Fedora logo,
@@ -235,7 +235,7 @@ including Fedora derivatives,
 is not permitted in spec files of packages in the main Fedora repositories
 unless those macros and conditionals are also present in Fedora.
 
-=== Spec file Encoding
+=== Spec File Encoding
 
 Unless you need to use characters outside the
 https://commons.wikimedia.org/wiki/File:Ascii_full.png[ASCII repertoire],
@@ -566,7 +566,7 @@ before any services are started
 (and before `+/var+` is available).
 `+/var/run+` is a legacy symlink to `+/run+`.
 
-=== No Files or Directories under /srv, /usr/local, or /home/$USER
+=== No Files or Directories Under `+/srv+`, `+/usr/local+`, or `+/home/$USER+`
 
 The https://www.pathname.com/fhs/pub/fhs-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM[FHS says]:
 
@@ -605,7 +605,7 @@ once installed and configured by a user,
 can use `+/srv+` as a location for data.
 The package simply must not do this out of the box
 
-=== Limited usage of /opt, /etc/opt, and /var/opt
+=== Limited Usage of `+/opt+`, `+/etc/opt+`, and `+/var/opt+`
 
 `+/opt+` and its related directories (`+/etc/opt+` and `+/var/opt+`)
 is reserved for the use of vendors in the FHS.
@@ -706,7 +706,7 @@ $ rpm -ql $(rpm -qf /usr/sbin/ifconfig)|grep sbin/ifconfig
 
 So you'd want to use `+Requires: /sbin/ifconfig+` in your spec file.
 
-== Use rpmlint
+== Use `+rpmlint+`
 
 Run rpmlint on binary and source rpms to examine them for common errors,
 and fix them (unless rpmlint is wrong, which can happen, too).
@@ -764,7 +764,7 @@ A versioned dependency on a package with a defined Epoch
 MUST be included in that dependency.
 Otherwise the dependency will not function as expected.
 
-=== Dependency types
+=== Dependency Types
 
 `Requires` MUST be used if the dependency is required
 for the software to function correctly.
@@ -812,7 +812,7 @@ This means that gtk+-devel should contain
 
 `+Requires: glib-devel%{?_isa} libXi-devel%{?_isa} libXext-devel%{?_isa} libX11-devel%{?_isa}+`
 
-=== Rich/Boolean dependencies
+=== Rich/Boolean Dependencies
 
 Packages MAY make full use of the
 https://rpm-software-management.github.io/rpm/manual/boolean_dependencies.html[rich (or Boolean) dependency feature]
@@ -917,7 +917,7 @@ as RPM dependencies
 and anything brought into the buildroot by the build system
 can change over time.
 
-=== BuildRequires and %\{_isa}
+=== BuildRequires and `+%{_isa}+`
 
 You MUST NOT use arched BuildRequires.
 The arch ends up in the built SRPM
@@ -942,7 +942,7 @@ This would prevent yum-builddep
 or similar tools that use the SRPM's requirements
 from operating correctly.
 
-=== BuildRequires based on pkg-config
+=== BuildRequires Based on `+pkg-config+`
 
 Fedora packages which use `+pkg-config+`
 to build against a library (e.g. 'foo') on which they depend,
@@ -950,7 +950,7 @@ to build against a library (e.g. 'foo') on which they depend,
 For more information, see
 xref:PkgConfigBuildRequires.adoc[Packaging:PkgConfigBuildRequires].
 
-== Conditional build-time dependencies
+== Conditional Build-Time Dependencies
 
 If the spec file contains conditional dependencies
 selected based on presence of optional
@@ -962,7 +962,7 @@ The reason is that those requirements get "serialized"
 into the resulting source RPM,
 i.e., the conditionals no longer apply.
 
-== Summary and description
+== Summary and Description
 
 The summary should be a short and concise description of the package.
 The description expands upon this.
@@ -1224,7 +1224,7 @@ in order for the default compiler to correctly compile their package.
 Packagers choosing to use a non-default compiler
 should document the reason for this decision in a comment in the spec file.
 
-== Compiler macros
+== Compiler Macros
 
 If clang is being used to build a package,
 packagers must set the %toolchain macro to clang:
@@ -1251,7 +1251,7 @@ The values of these variables are controled by setting the %toolchain macro
 to either clang or gcc.
 
 
-== Compiler flags
+== Compiler Flags
 
 Compilers used to build packages must honor the applicable compiler flags
 set in the system rpm configuration.
@@ -1305,7 +1305,7 @@ until the machine is rebooted, not start on demand and quit on idle.
 
 * Your package runs as root.
 
-== Debuginfo packages
+== Debuginfo Packages
 
 Packages should produce useful `+-debuginfo+` packages,
 or explicitly disable them when it is not possible to generate a useful one
@@ -1392,7 +1392,7 @@ Should you come across such a case,
 please open a ticket with the {packaging-committee}
 and explain it to us so that we can extend the Guidelines to address it.
 
-=== Pkgconfig Files (foo.pc)
+=== Pkgconfig Files (`+foo.pc+`)
 
 The placement of pkgconfig(.pc) files depends on their usecase.
 Since they are almost always used for development purposes,
@@ -1433,7 +1433,7 @@ Whenever possible (and feasible),
 Fedora packages containing libraries SHOULD build them as shared libraries.
 It is not necessary to call `+ldconfig+` when installing shared libraries.
 
-=== Listing shared library files
+=== Listing Shared Library Files
 
 Shared libraries installed directly into `+%{_libdir}+` *SHOULD NOT* be listed
 in the `%files` section of the spec by using a glob in a way
@@ -1450,7 +1450,7 @@ using something like `libfoo.so.X*` is recommended instead,
 since dependent packages usually don't have to be rebuilt
 for changes of this kind.
 
-=== Downstream .so name versioning
+=== Downstream `+.so+` Name Versioning
 
 In cases where upstream ships unversioned .so *library*
 (so this is not needed for plugins, drivers, etc.),
@@ -1480,7 +1480,7 @@ you should use an {abi-comparison-tool} to check for ABI differences
 in the built shared libraries.
 If it detects any incompatibilities, bump the _n_ number by one.
 
-==== SONAME handling
+==== SONAME Handling
 
 When running an executable linked to shared object with SONAME field,
 the dynamic linker checks for this field
@@ -1619,7 +1619,7 @@ a build dependency on the `+-static+` package
 which provides those files MUST be present so that the usage can be tracked.
 
 [#bundling]
-== Bundling and Duplication of system libraries
+== Bundling and Duplication of System Libraries
 
 Fedora packages SHOULD make every effort to avoid having
 multiple, separate, upstream projects
@@ -1671,7 +1671,7 @@ either in comments placed adjacent to the Provides: above,
 or in an additional file checked into the SCM
 and referenced by a comment placed adjacent to the `+Provides:+` above.
 
-=== Avoid bundling of fonts in other packages
+=== Avoid Bundling of Fonts in Other Packages
 
 Fonts in general-purpose formats such as
 Type1, OpenType TT (TTF) or OpenType CFF (OTF)
@@ -1681,7 +1681,7 @@ and should always be packaged in the system-wide font repositories
 instead of private application directories.
 For more information, see: xref:FontsPolicy.adoc[Packaging/FontsPolicy].
 
-== Beware of Rpath
+== Beware of `+rpath+`
 
 Sometimes, code will hardcode specific library paths when linking binaries
 (using the -rpath or -R flag).
@@ -1714,7 +1714,7 @@ ERROR   0001: file '/usr/bin/xapian-tcpsrv' contains a standard rpath '/usr/lib6
 
 Any rpath flagged by check-rpaths *MUST* be removed.
 
-=== Rpath for Internal Libraries
+=== `+rpath+` for Internal Libraries
 
 When a program installs internal libraries
 they are often not installed in the system path.
@@ -1747,7 +1747,7 @@ That way the dynamic linker can find the libraries
 without having to link all the programs with an rpath.
 
 [#alternatives-to-rpath]
-=== Alternatives to Rpath
+=== Alternatives to `+rpath+`
 
 Often, rpath is used because a binary is looking for libraries
 in a non-standard location
@@ -1765,7 +1765,7 @@ in /etc/ld.so.conf.d/, which contained the following:
 Make sure that you also make a 64bit version of this file (e.g. foo64.conf)
 as well (unless the package is disabled for 64bit architectures, of course).
 
-=== Removing Rpath
+=== Removing `+rpath+`
 
 There are several different ways to fix the rpath issue:
 
@@ -1795,7 +1795,7 @@ chrpath --delete $RPM_BUILD_ROOT%{_bindir}/xapian-tcpsrv
 Make sure that you remember to add a
 *BuildRequires: chrpath* if you end up using this method.
 
-== Configuration files
+== Configuration Files
 
 Configuration files must be marked as such in packages.
 
@@ -1821,7 +1821,7 @@ Packages MUST NOT install repository configuration files which violate
 the https://docs.fedoraproject.org/en-US/fesco/Third_Party_Repository_Policy/[Third Party Repository Policy],
 unless those files are installed under `+%{_docdir}+`.
 
-== Per-product Configuration
+== Per-Product Configuration
 
 In the Fedora.next world,
 we will have a set of curated Fedora Products
@@ -1838,12 +1838,12 @@ that need to behave differently between Fedora.next Products.
 SystemV-style initscripts are forbidden in Fedora.
 Systemd units must be used instead.
 
-== Systemd units
+== Systemd Units
 
 Detailed guidelines for packaging systemd units
 and systemd-managed services are xref:Systemd.adoc[here].
 
-== Desktop files
+== Desktop Files
 
 If a package contains a GUI application,
 then it needs to also include a properly installed .desktop file.
@@ -1858,7 +1858,7 @@ https://standards.freedesktop.org/menu-spec/latest/apa.html[Categories],
 https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt[StartupNotify]
 entries.
 
-=== Icon tag in Desktop Files
+=== Icon Tag in Desktop Files
 
 The icon tag can be specified in two ways:
 
@@ -1875,7 +1875,7 @@ because it allows for icon theming
 (it assumes .png by default, then tries .svg and finally .xpm),
 but either method is acceptable.
 
-=== .desktop file creation
+=== `+.desktop+` File Creation
 
 If the package doesn't already include and install its own .desktop file,
 you need to make your own.
@@ -1896,7 +1896,7 @@ Type=Application
 Categories=Graphics;
 ....
 
-=== desktop-file-install usage
+=== `+desktop-file-install+` Usage
 
 It is not simply enough to just include the .desktop file in the package,
 one MUST run `+desktop-file-install+` (in `+%install+`)
@@ -1930,7 +1930,7 @@ desktop-file-validate %{buildroot}/%{_datadir}/applications/foo.desktop
 
 Do *not* apply a vendor tag to .desktop files (using --vendor).
 
-== AppData files
+== AppData Files
 
 Packages containing graphical applications should include AppData files.
 See xref:AppData.adoc[Packaging:AppData] for the relevant guidelines.
@@ -1988,7 +1988,7 @@ For more details on proper use of `+%autosetup+`,
 refer to the
 https://rpm-software-management.github.io/rpm/manual/autosetup.html[RPM documentation].
 
-=== Using %\{buildroot} and %\{optflags} vs $RPM_BUILD_ROOT and $RPM_OPT_FLAGS
+=== Using `+%{buildroot}+` and `+%{optflags}+` vs `+$RPM_BUILD_ROOT+` and `+$RPM_OPT_FLAGS+`
 
 There are two styles of defining the rpm Build Root and Optimization Flags
 in a spec file:
@@ -2007,7 +2007,7 @@ Mixing the two styles, while valid,
 is bad from a QA and usability point of view,
 and should not be done in Fedora packages.
 
-=== Why the %makeinstall macro should not be used
+=== Why the `+%makeinstall+` Macro Should Not Be Used
 
 Fedora's RPM includes a `+%makeinstall+` macro
 but it must *NOT* be used when make install DESTDIR=%\{buildroot} works.
@@ -2057,7 +2057,7 @@ or missing information (when`+%{?foo}+` is expanded to the empty string).
 Even easier is to simply avoid macros in `+Summary:+` and `+%description+`
 unless they are defined in the current spec file.
 
-=== Improper use of %_sourcedir
+=== Improper Use of `+%_sourcedir+`
 
 Packages which use files itemized as Source# files,
 must refer to those files by their `+Source#+` macro name,
@@ -2088,7 +2088,7 @@ and packagers are encouraged to use their best judgment
 when determining the proper package for these files.
 RPM macro files MUST NOT be marked as `+%config+`.
 
-== Scripting inside of spec files
+== Scripting Inside of Specfiles
 
 Sometimes it is necessary to write a short script (perhaps a one-liner)
 that is executed in the %prep, %build, or %install sections of a spec file
@@ -2111,7 +2111,7 @@ Note: If you call Perl or Python in your spec file
 (and it is not already a BuildRequires for the package),
 you need to explicitly add a BuildRequires for Perl or Python.
 
-== %global preferred over %define
+== `+%global+` Preferred Over `+%define+`
 
 Use `+%global+` instead of `+%define+`,
 unless you really need only locally defined submacros
@@ -2287,7 +2287,7 @@ under %\{_localstatedir}/log.
 Unless the software being packaged rotates its own logs,
 it must also ship a logrotate config file to rotate its log file(s).
 
-=== Logrotate config file
+=== `+logrotate+` Config File
 
 Logrotate config files should be named in a way that matches
 the daemon/software which is generating the logs,
@@ -2299,7 +2299,7 @@ and should use standard file permissions (0644) and ownership (root:root).
 Since these are config files,
 they must be marked as %config(noreplace) in the %files list.
 
-==== Example minimal logrotate config file
+==== Example Minimal `+logrotate+` Config File
 
 ....
 /var/log/example/*log {
@@ -2323,7 +2323,7 @@ To make the change global for wget,
 add this to your `+~/.wgetrc+`: `+timestamping = on+`,
 and for curl, add to your `+~/.curlrc+`: `+-R+`.
 
-== Parallel make
+== Parallel Make
 
 Whenever possible, invocations of `+make+` should be done as
 
@@ -2372,7 +2372,7 @@ according to the following matrix
 
 Further clarification: That should hold true irrespective of the builder's uid.
 
-== Build packages with separate user accounts
+== Build Packages with Separate User Accounts
 
 When building software,
 which you have not conducted a full security-audit on,
@@ -2383,7 +2383,7 @@ The same applies to reviewers/testers.
 Rebuild src.rpms in a separate account
 which does not have access to any sensitive data.
 
-== Relocatable packages
+== Relocatable Packages
 
 The use of RPM's facility for generating relocatable packages
 is strongly discouraged.
@@ -2664,7 +2664,7 @@ It may be that some patches truly are Fedora-specific; in that case, say so:
 Patch0: jna-jni-path.patch
 ....
 
-=== Applying patches
+=== Applying Patches
 
 Normally, patches to a package SHOULD be listed in `+PatchN:+` tags
 in the RPM spec file and applied using the %patch or %autosetup macros.
@@ -2791,7 +2791,7 @@ Cons:
 
 * Absolute symlinks may break when used with chroots.
 
-== Replacing a symlink to a directory or a directory to any type file
+== Replacing a Symlink to a Directory or a Directory to Any Type File
 
 In some cases replacing a symlink to a directory requires special handling.
 Replacing a directory with any type of file always requires special handling.
@@ -2973,14 +2973,14 @@ in the Fedora package.
 For details on how to package cron files, refer to:
 xref:CronFiles.adoc[CronFiles].
 
-== Security Updates To Resolve Known CVE Issues
+== Security Updates to Resolve Known CVE Issues
 
 If an update to your package resolves a known security concern
 (at the time of the update)
 with a Common Vulnerabilities and Exposures (CVE) number assigned to it,
 you should mention the CVE number in the RPM changelog entry.
 
-== Build time network access
+== Build Time Network Access
 
 Packages in the Fedora buildsystem are built in a mock chroot
 with no access to the internet.
@@ -3043,7 +3043,7 @@ Please note that usage of pre-built binaries
 in bootstrap still needs an exception from the Packaging Committee
 as stated in <<General Exception Policy>>.
 
-== System cryptographic policies
+== System Cryptographic Policies
 
 Applications which make use the SSL or TLS cryptographic protocols
 MUST follow xref:CryptoPolicies.adoc[Crypto Policies].

From 13972da9a859436cb85f6c4eb0f5e64372c6b817 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 20 2021 20:35:59 +0000
Subject: [PATCH 3/9] Small fixes to Shebang Lines section


Fix capitalization and two comma faults.

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 1011c8d..57e69c5 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -3048,7 +3048,7 @@ as stated in <<General Exception Policy>>.
 Applications which make use the SSL or TLS cryptographic protocols
 MUST follow xref:CryptoPolicies.adoc[Crypto Policies].
 
-== Shebang lines
+== Shebang Lines
 
 When packaging script files,
 where the interpreter to be used is specified in the first line of the script
@@ -3067,14 +3067,14 @@ in `+/usr/bin+`.
 Various checks are also applied to verify that the shebang lines are valid,
 and the build process can fail as a result of these.
 Finally, other language-specific modifications may also be made.
-It is thus generally unnecessary, to manually modify executable scripts
+It is thus generally unnecessary to manually modify executable scripts
 to fix `+env+` usage as long as this functionality is enabled.
 
 If the automatic checks and modifications break a package,
 there are two primary options:
 
-* The packager can elect to fix the shebang lines manually,
-using patches, scripting via sed, or other similar methods.
+* The packager can elect to fix the shebang lines manually
+(using patches, scripting via sed, or other similar methods).
 * The packager can remove the executable permission from the script
 so that the checks and modifications are not made.
 

From a61898c301f9eb3bcd504cb6ca340ba57521aff8 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 20 2021 20:35:59 +0000
Subject: [PATCH 4/9] Better formatting for the BRP section


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 57e69c5..3ea19f4 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -3113,7 +3113,9 @@ For example, to disable the brp-python-bytecompile script:
 Any package that disables a BRP script this way MUST also note the reason
 in an accompanying comment.
 For a list of the BRP scripts run by default,
-invoke: `+fgrep '%__brp_' /usr/lib/rpm/redhat/macros+`
+invoke:
+
+ fgrep '%__brp_' /usr/lib/rpm/redhat/macros
 
 == Packaging for EPEL
 

From 56ca6bdd24d9bbb3549ec629cf20b7dbe936543d Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 20 2021 21:04:11 +0000
Subject: [PATCH 5/9] Fix formatting issues in Cmake guidelines


This fixes a few instances of bad formatting as well as minor
capitalization and grammar issues.

---

diff --git a/guidelines/modules/ROOT/pages/CMake.adoc b/guidelines/modules/ROOT/pages/CMake.adoc
index fe64c66..dd69a18 100644
--- a/guidelines/modules/ROOT/pages/CMake.adoc
+++ b/guidelines/modules/ROOT/pages/CMake.adoc
@@ -60,30 +60,30 @@ for more information.
 Holds the location of the actual directory where the build was made.
 When making
 https://fedoraproject.org/wiki/Changes/CMake_to_do_out-of-source_builds[out-of-source builds],
-this macro is the same as %_vpath_builddir,
+this macro is the same as `+%_vpath_builddir+`,
 which should be used preferably in such cases.
 See the xref:vpath.adoc[Defining source and build directories]
 for more information.
 When doing in-source builds (that means before Fedora 33
 https://fedoraproject.org/wiki/Changes/CMake_to_do_out-of-source_builds[out-of-source builds]
 change),
-this macro would differ from %_vpath_builddir
+this macro would differ from `+%_vpath_builddir+`
 and it will hold the actual location that was used for the build.
 This is useful in cases,
-when you want to use the same SPECfile for different Fedora releases
+when you want to use the same specfile for different Fedora releases
 where on some the build is in-source and on some out-of-source
 AND you need to know the builddir location -
-e.g. when using "cmake -B %__cmake_builddir -LH"
-inbetween of %cmake and "%cmake_build".
+e.g. when using `+cmake -B %__cmake_builddir -LH+`
+between `+%cmake+` and `+%cmake_build+`.
 Whenever possible, using out-of-source builds is advised,
-as this is the direction both Fedora and CMake upstream bears.
+as this is the direction both Fedora and CMake upstream are moving.
 
-Warning: This macro is suitable only for rare compatibility reasons.
+WARNING: This macro is suitable only for rare compatibility reasons.
 Once all active Fedora releases will use
 https://fedoraproject.org/wiki/Changes/CMake_to_do_out-of-source_builds[out-of-source builds],
-this macro will be redundant (same as %_vpath_builddir) and removed.
+this macro will be redundant (same as `+%_vpath_builddir+`) and may be removed.
 
-== Example usage in the spec file
+== Example Usage
 
 ....
 %build
@@ -99,11 +99,11 @@ this macro will be redundant (same as %_vpath_builddir) and removed.
 
 == Notes
 
-NOTE: Since Fedora 33, `+%__cmake_in_source_build+` is not defined
+Since Fedora 33, `+%__cmake_in_source_build+` is not defined
 so if you want to have consistent behavior across different releases,
 make sure to `+%define+` or `+%undefine+` it accordingly.
 
-*NOTE*: `+-DCMAKE_SKIP_RPATH:BOOL=ON+`.
+`+-DCMAKE_SKIP_RPATH:BOOL=ON+`.
 With recent cmake-2.4, it should not be used.
 This CMake version should handle RPATHs issues correctly
 (set them in build-dir, remove them during installation).
@@ -119,7 +119,6 @@ will *not* strip rpaths;
 in this case `+INSTALL(TARGETS ...)+` must be used
 in combination with changing the `+OUTPUT_NAME+` property.
 
-*NOTE*: CMake has good documentation in two places:
-
+CMake has good documentation in two places:
 * https://cmake.org/documentation/
 * https://gitlab.kitware.com/cmake/community/wikis/Home

From 069f26bc487dd9712416e01027c2035bb532322a Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 20 2021 21:58:35 +0000
Subject: [PATCH 6/9] Minor formatting and changes


---

diff --git a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc
index 0374922..ff83d88 100644
--- a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc
+++ b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc
@@ -44,15 +44,16 @@ and help prevent them from being mixed up with other sections.
 
 These filters use regular expressions.
 The regular expression variant used for these filters
-follow.the `POSIX.2` regular expression standard (see man regex(7) ).
+follows the `POSIX.2` regular expression standard
+(see the `+regex(7)` manpage).
 In this variant,
 the literal characters `+^.[$()|*+?{+` need to be backslash escaped.
 Because rpm interprets backslashes as part of its parsing of spec files,
 you will need to use a *double backslash* for any escapes.
 A literal backslash ("`+\+`") is represented by four backslashes.
 
-The regex engine is only passed the final string, after rpm macro expansion.
-So you can't use unescaped data via rpm macros.
+The regex engine is only passed the final string, after RPM macro expansion.
+So you can't use unescaped data via RPM macros.
 For instance, if you generate a list of files to match in a macro
 and that list contains `+libfoo.so+`
 you'll have to use `+libfoo\\.so+` to escape the ("`+.+`").
@@ -99,13 +100,13 @@ because you should be anchoring your regular expressions.
 
 === Filtering provides and requires after scanning
 
-In addition to preventing rpm from scanning
+In addition to preventing RPM from scanning
 files and directories for automatic dependency generation
-you can also tell rpm to discard a discovered dependency
-before it records the dependency in the rpm metadata.
+you can also tell RPM to discard a discovered dependency
+before it records the dependency in the RPM metadata.
 Use `+__requires_exclude+` and `+__provides_exclude+` for this.
 These macros should be defined as regular expressions.
-If an entry that rpm's automatic dependency generator created
+If an entry that RPM's automatic dependency generator created
 matches the regular expression
 then it will be filtered out of the requires or provides.
 For example:
@@ -183,7 +184,7 @@ At this time, filtering of private libraries is non-trivial.
 This is because the symbols you want to filter from the private libraries
 are usually required by the public applications that the package ships.
 In order to filter,
-you need to find out what symbols rpm is extracting for the private library
+you need to find out what symbols RPM is extracting for the private library
 and then remove those in both
 `+%__provides_exclude+` and `+%__requires_exclude+`.
 
@@ -194,7 +195,7 @@ that you want to filter and
 that requires that private library.
 You could:
 
-* First build the rpm: `+$ rpmbuild -ba foo.spec+`
+* First build the RPM: `+$ rpmbuild -ba foo.spec+`
 * then determine what provides rpm decided for the private library:
 `+$ rpm -qp foo-1.0-1.x86_64.rpm+`:
 
@@ -205,7 +206,7 @@ foo(x86-64) = 1.0-1.fc19
 ....
 
 * See that `+libprivate.so()(64bit)+`
-appears to be the only symbol that rpm extracted for this package.
+appears to be the only symbol that RPM extracted for this package.
 Note that on 32bit, the provides will be `+libprivate.so+`
 so your regex needs to capture both.
 +

From 9d8c74b82ebeec38c04b953932432b549ca19fa5 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 20 2021 23:40:49 +0000
Subject: [PATCH 7/9] Fix formatting of the Scriptlets guidelines


Fix a number of formatting issues, and apply semantic breaks to a
section that was just flowed to 80 columns.

---

diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc
index ee18e42..53087d6 100644
--- a/guidelines/modules/ROOT/pages/Scriptlets.adoc
+++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc
@@ -26,10 +26,10 @@ unless a different language has been specified.
 
 The basic syntax is similar to the %build, %install, and other sections
 of the rpm spec file.
-The scripts support a special flag, -p
+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.
-(i.e., %post -p /sbin/ldconfig)
+(i.e., `+%post -p /sbin/ldconfig+`)
 
 When scriptlets are called,
 they will be supplied with an argument.
@@ -41,12 +41,12 @@ So for the common case of install, upgrade, and uninstall we have:
 [cols=",,,",]
 |===================================
 | |install |upgrade |uninstall
-|%pretrans |$1 == 1 |$1 == 2 |(N/A)
-|%pre |$1 == 1 |$1 == 2 |(N/A)
-|%post |$1 == 1 |$1 == 2 |(N/A)
-|%preun |(N/A) |$1 == 1 |$1 == 0
-|%postun |(N/A) |$1 == 1 |$1 == 0
-|%posttrans |$1 == 1 |$1 == 1 |(N/A)
+|`+%pretrans+` |`+$1 == 1+` |`+$1 == 2+` |(N/A)
+|`+%pre+` |`+$1 == 1+` |`+$1 == 2+` |(N/A)
+|`+%post+` |`+$1 == 1+` |`+$1 == 2+` |(N/A)
+|`+%preun+` |(N/A) |`+$1 == 1+` |`+$1 == 0+`
+|`+%postun+` |(N/A) |`+$1 == 1+` |`+$1 == 0+`
+|`+%posttrans+` |`+$1 == 1+` |`+$1 == 1+` |(N/A)
 |===================================
 
 Note that these values will vary
@@ -62,7 +62,7 @@ if [ $1 -gt 1 ] ; then
 fi
 ....
 
-...for %pre and %post scripts rather than checking that it equals 2.
+for `+%pre+` and `+%post+` scripts rather than checking that it equals 2.
 
 All scriptlets MUST exit with the zero exit status.
 Because RPM in its default configuration does not execute
@@ -99,36 +99,36 @@ is more likely to result in broader system wide problems.
 [#ordering]
 == Ordering
 
-The scriptlets in %pre and %post are respectively run
+The scriptlets in `+%pre+` and `+%post+` are respectively run
 before and after a package is installed.
-The scriptlets %preun and %postun
+The scriptlets `+%preun+` and `+%postun+`
 are run before and after a package is uninstalled.
-The scriptlets %pretrans and %posttrans
+The scriptlets `+%pretrans+` and `+%posttrans+`
 are run at start and end of a transaction.
 On upgrade, the scripts are run in the following order:
 
-1.  %pretrans of new package
-2.  %pre of new package
+1.  `+%pretrans+` of new package
+2.  `+%pre+` of new package
 3.  (package install)
-4.  %post of new package
-5.  %triggerin of other packages (set off by installing new package)
-6.  %triggerin of new package (if any are true)
-7.  %triggerun of old package (if it's set off by uninstalling the old package)
-8.  %triggerun of other packages (set off by uninstalling old package)
-9.  %preun of old package
+4.  `+%post+` of new package
+5.  `+%triggerin+` of other packages (set off by installing new package)
+6.  `+%triggerin+` of new package (if any are true)
+7.  `+%triggerun+` of old package (if it's set off by uninstalling the old package)
+8.  `+%triggerun+` of other packages (set off by uninstalling old package)
+9.  `+%preun+` of old package
 10. (removal of old package)
-11. %postun of old package
+11. `+%postun+` of old package
 
-12. %triggerpostun of old package
+12. `+%triggerpostun+` of old package
 (if it's set off by uninstalling the old package)
 
-13. %triggerpostun of other packages
+13. `+%triggerpostun+` of other packages
 (if they're set off by uninstalling the old package)
 
-14. %posttrans of new package
+14. `+%posttrans+` of new package
 
 [#pretrans]
-=== The %pretrans Scriptlet
+=== The `+%pretrans+` Scriptlet
 
 Note that the `+%pretrans+` scriptlet will,
 in the particular case of system installation,
@@ -141,7 +141,7 @@ for more information.
 
 == Writing Scriptlets
 
-Some tips for writing good scriptlets
+Here are some tips for writing good scriptlets:
 
 === Saving state between scriptlets
 
@@ -201,6 +201,8 @@ it is better to use RPM file triggers if at all possible.
 
 == Snippets
 
+Some scriptlets to use in specific situations.
+
 === Linker Configuration Files
 
 Packages which place linker configuration files in `+/etc/ld.so.conf.d+`
@@ -257,13 +259,13 @@ via the configuration files in `+/etc/ld.so.conf.d+`.
 
 === Users and groups
 
-These are discussed on a xref:UsersAndGroups.adoc[separate page]
+These are discussed on a xref:UsersAndGroups.adoc[separate page].
 
 === GConf
 
 GConf is a configuration scheme currently used by the GNOME desktop.
-Programs which use it setup default values in a [NAME] .schemas file
-which is installed under %\{_sysconfdir}/gconf/schemas/[NAME] .schemas.
+Programs which use it setup default values in a `+.schemas+` file
+which is installed under `+%{_sysconfdir}/gconf/schemas/[NAME].schemas+`.
 These defaults are then registered with the gconf daemon
 which monitors the configuration values
 and alerts applications when values the applications are interested in change.
@@ -272,7 +274,7 @@ about what each value in the configuration system means
 (which gets displayed when you browse the database in the gconf-editor program).
 
 For packaging purposes, we have to disable schema installation during build,
-and also register the values in the [NAME] .schemas file
+and also register the values in the `+[NAME].schemas+` file
 with the gconf daemon on installation
 and unregister them on removal.
 Due to the ordering of the scriptlets, this is a four step process.
@@ -286,7 +288,7 @@ make install DESTDIR=$RPM_BUILD_ROOT
 ...
 ....
 
-The GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL environment variable
+The `+GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL+` environment variable
 suppresses the installation of the schema during the building of the package.
 An alternative for some packages is to pass a configure flag:
 
@@ -297,8 +299,8 @@ An alternative for some packages is to pass a configure flag:
 ....
 
 Unfortunately, this configure switch only works
-if the upstream packager has adapted their Makefile.am to handle it.
-If the Makefile.am is not configured,
+if the upstream packager has adapted their `+Makefile.am+` file to handle it.
+If the `+Makefile.am+` file is not configured,
 this switch won't do anything
 and you'll need to use the environment variable instead.
 
@@ -317,20 +319,22 @@ Requires(preun): GConf2
 
 In this section we uninstall old schemas during upgrade using one of two macros.
 
-`+%gconf_schema_prepare+` is used for any current GConf schemas. It
-takes care of uninstalling previous versions of schemas that this package
-currently installs. It takes a space separated list of schema names without
-path or suffix that the package installs. Note that behind the scenes, this
-macro works with the `+%post+` scriptlet to only process GConf schemas
-if changes have occurred.
-
-`+%gconf_schema_obsolete+` is used for schemas that this package
-previously provided but no longer does. It will deregister the old schema if
-it is present on the system. Nothing will happen if the old schema is not
-present. This macro takes a space separated list of schemas to uninstall. One
-example of using this might be if the package changed names. If the old schema
-was named `+foo.schemas+` and the new schema is named
-`+foobar.schemas+` you'd use:
+`+%gconf_schema_prepare+` is used for any current GConf schemas.
+It takes care of uninstalling previous versions of schemas
+that this package currently installs.
+It takes a space separated list of schema names without path or suffix
+that the package installs.
+Note that behind the scenes, this macro works with the `+%post+` scriptlet
+to only process GConf schemas if changes have occurred.
+
+`+%gconf_schema_obsolete+` is used for schemas
+that this package previously provided but no longer does.
+It will deregister the old schema if it is present on the system.
+Nothing will happen if the old schema is not present.
+This macro takes a space separated list of schemas to uninstall.
+One example of using this might be if the package changed names.
+If the old schema was named `+foo.schemas+`
+and the new schema is named `+foobar.schemas+` you'd use:
 
 ....
 %gconf_schema_prepare foobar
@@ -344,10 +348,10 @@ The next section does the processing of the newly installed schemas:
 %gconf_schema_upgrade schema1 schema2
 ....
 
-`+%gconf_schema_upgrade+` takes a space separated list of schemas that
-the package currently installs just like `+%gconf_schema_prepare+`.
-Behind the scenes, it does the actual work of registering the new version of
-the schema and deregistering the old version.
+`+%gconf_schema_upgrade+` takes a space separated list of schemas
+that the package currently installs just like `+%gconf_schema_prepare+`.
+Behind the scenes, it does the actual work of registering the new version
+of the schema and deregistering the old version.
 
 The last section is for unregistering schemas when a package is removed:
 
@@ -356,15 +360,17 @@ The last section is for unregistering schemas when a package is removed:
 %gconf_schema_remove schema1 schema2
 ....
 
-When a package is upgraded rpm invokes the `+%pre+` scriptlet to register
-and deregister the schemas. When a package is uninstalled, the
-`+%preun+` scriptlet is used. `+%gconf_schema_remove+` takes
-the list of schemas that this package currently provides and removes them for us.
+When a package is upgraded rpm invokes the `+%pre+` scriptlet
+to register and deregister the schemas.
+When a package is uninstalled, the `+%preun+` scriptlet is used.
+`+%gconf_schema_remove+` takes the list of schemas
+that this package currently provides and removes them for us.
 
 ==== Rebuilds for changes to macros
 
-When macros change, packages that make use of them have to be rebuilt to
-pick up the changes. This repoquery command can be used to find the schema
+When macros change, packages that make use of them have to be rebuilt
+to pick up the changes.
+This repoquery command can be used to find the schema
 including packages to rebuild:
 
 ....

From fea2e79c03434ff01f69355a32d8cebd4373a262 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 21 2021 00:01:17 +0000
Subject: [PATCH 8/9] Remove ancient mailing list address


Just link to the packaging committee main page instead of sending people
to an old address for the devel list.

---

diff --git a/guidelines/modules/ROOT/pages/Conflicts.adoc b/guidelines/modules/ROOT/pages/Conflicts.adoc
index 7344ec8..d852b13 100644
--- a/guidelines/modules/ROOT/pages/Conflicts.adoc
+++ b/guidelines/modules/ROOT/pages/Conflicts.adoc
@@ -1,3 +1,5 @@
+include::{partialsdir}/attributes.adoc[]
+
 = Conflicts Guidelines
 
 *Author:* https://fedoraproject.org/wiki/TomCallaway[ Tom 'spot' Callaway] +
@@ -5,6 +7,7 @@
 *Initial Draft:* Tuesday Dec 5, 2006 +
 *Last Revised:* Wednesday Oct 31, 2012 +
 
+
 == Conflicts
 
 Users should always be able to install the latest packages from Fedora's repos
@@ -172,7 +175,7 @@ xref:EnvironmentModules.adoc[Environment Modules]
 to let the user switch between them.
 If the library is not 100% ABI-compatible get one of the upstreams to rename.
 See xref:#_approaching_upstream[Approaching Upstream] for ideas on persuasion.
-If neither upstream will budge open a ticket for FPC
+If neither upstream will budge open a ticket for the {packaging-committee}
 to evaluate what sort of hoops both packages would need to implement
 to not conflict at runtime.
 
@@ -235,8 +238,8 @@ we should go through the process of determining
 which package has a more valid claim to the name
 and rename the files in the package we're including
 if it doesn't have the more valid claim.
-If you think your situation is unique, please send email to
-fedora-devel-list[at]redhat.com to make your case.
+If you think your situation is unique, please open a ticket
+with the {packaging-committee}.
 
 In the second case,
 where there is no known package to conflict with at this time,
diff --git a/guidelines/modules/ROOT/pages/_partials/attributes.adoc b/guidelines/modules/ROOT/pages/_partials/attributes.adoc
new file mode 100644
index 0000000..e8e3eeb
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/_partials/attributes.adoc
@@ -0,0 +1,12 @@
+////
+A collection of useful attributes
+
+To use these in a document, just add the following near the top:
+
+:include::{partialsdir}/attributes.adoc[]
+
+////
+:abi-comparison-tool: https://fedoraproject.org/wiki/How_to_check_for_ABI_changes_in_a_package[ABI comparison tool]
+:packaging-committee: https://pagure.io/packaging-committee[Fedora Packaging Committee]
+:scl-guidelines: https://fedoraproject.org/wiki/User:Toshio/SCL_Guidelines_(draft)[Software Collections]
+:updates-policy: https://docs.fedoraproject.org/en-US/fesco/Updates_Policy/[Updates Policy]

From c9e8a276b57947ff551f33a412b26d6e8bbd4acb Mon Sep 17 00:00:00 2001
From: Jason Tibbitts <j@tib.bs>
Date: Oct 21 2021 00:02:43 +0000
Subject: [PATCH 9/9] Update versions list


Just use F35 as current so we get a few extra months before we're out of
date again.

---

diff --git a/guidelines/modules/ROOT/pages/_partials/versions.adoc b/guidelines/modules/ROOT/pages/_partials/versions.adoc
index 7a0011e..b579e12 100644
--- a/guidelines/modules/ROOT/pages/_partials/versions.adoc
+++ b/guidelines/modules/ROOT/pages/_partials/versions.adoc
@@ -12,6 +12,6 @@ versions, because then those guidelines will be wrong when these macros are
 updated.  In that you instead simply hardcode the version numbers.
 ////
 
-:NEXTVER: 31
-:CURRENTVER: 30
-:PREVVER: 29
+:NEXTVER: 36
+:CURRENTVER: 35
+:PREVVER: 34