From f2678d19b6372b72adf47f09346d8c454402a4ce Mon Sep 17 00:00:00 2001
From: Nicolas Mailhot <nim@fedoraproject.org>
Date: Jul 07 2019 14:16:21 +0000
Subject: forge: add some templates and documentation


---

diff --git a/common.lua b/common.lua
index 0f28a8d..170eca7 100644
--- a/common.lua
+++ b/common.lua
@@ -1,4 +1,6 @@
 -- Convenience Lua functions that can be used within rpm macros
+-- Most of those emulate
+-- https://github.com/rpm-software-management/rpm/issues/573
 
 -- Set a spec variable
 -- Echo the result if verbose
diff --git a/macros.fedora-misc-srpm b/macros.fedora-misc-srpm
index 3431190..b7ea445 100644
--- a/macros.fedora-misc-srpm
+++ b/macros.fedora-misc-srpm
@@ -3,6 +3,9 @@
 # A directory for rpm macros
 %rpmmacrodir /usr/lib/rpm/macros.d
 
+# A directory for spec template examples
+%_spectemplatedir %{_datadir}/rpmdevtools/fedora
+
 # A directory for appdata metainfo.  This has changed between releases so a
 # macro is useful.
 %_metainfodir %{_datadir}/metainfo
diff --git a/redhat-rpm-config.spec b/redhat-rpm-config.spec
index ed2d550..b8ec004 100644
--- a/redhat-rpm-config.spec
+++ b/redhat-rpm-config.spec
@@ -82,6 +82,21 @@ Source801: forge.lua
 # Documentation
 Source900: buildflags.md
 
+# Spec templates
+# Because redhat-rpm-config does not have a proper upstream repository like
+# everyone else files end up directly in the src.rpm. Therefore, use a fake
+# extension for example spec files as otherwise copr tries to build them
+# instead of the main spec file. However, that also means pretty much every dev
+# tool from text editors to SCM web frontends won't apply the correct syntax
+# highlighting when inspecting those files. And the spec files get more
+# complicated as a result. This sucks.
+# https://bugzilla.redhat.com/show_bug.cgi?id=1655322
+Source950: spectemplate-forge-0-release.fake
+Source951: spectemplate-forge-1-tag.fake
+Source952: spectemplate-forge-2-commit.fake
+Source953: spectemplate-forge-3-multi.fake
+Source954: spectemplate-forge-4-branch.fake
+
 BuildArch: noarch
 BuildRequires: perl-generators
 Requires: coreutils
@@ -115,24 +130,43 @@ Requires: %{_bindir}/xargs
 Conflicts: gcc < 8.0.1-0.22
 
 Provides: system-rpm-config = %{version}-%{release}
+Provides: redhat-rpm-macros = %{version}-%{release}
 
 %global rrcdir /usr/lib/rpm/redhat
+# Pull in _spectemplatedir definition, the spec file uses it
+%{load:%{SOURCE100}}
 
 %description
 Red Hat specific rpm configuration files.
 
 %package -n kernel-rpm-macros
 Summary: Macros and scripts for building kernel module packages
-Requires: redhat-rpm-config >= 13
+Requires:  %{name} = %{version}-%{release}
 
 %description -n kernel-rpm-macros
 Macros and scripts for building kernel module packages.
 
+%package  -n redhat-rpm-templates
+Summary:   Example rpm spec templates for the macros provided by %{name}
+BuildArch: noarch
+Requires:  %{name} = %{version}-%{release}
+Requires:  rpmdevtools
+
+%description -n redhat-rpm-templates
+This package contains documented rpm spec templates showcasing how to use the
+macros provided by %{name}.
+
 %prep
 # Not strictly necessary but allows working on file names instead
 # of source numbers in install section
 %setup -c -T
 cp -p %{sources} .
+for template in spectemplate*\.fake ; do
+  rad="${template%.fake}"
+  mv "${rad}.fake" "${rad}.spec"
+  grep -v '^#' "${rad}.spec" > "${rad}-bare.spec"
+  touch -r "${rad}.spec" "${rad}-bare.spec"
+done
 
 %install
 mkdir -p %{buildroot}%{rrcdir}
@@ -161,6 +195,10 @@ mkdir -p %{buildroot}%{_rpmluadir}/fedora/{rpm,srpm}
 install -p -m 644 -t %{buildroot}%{_rpmluadir}/fedora common.lua
 install -p -m 644 -t %{buildroot}%{_rpmluadir}/fedora/srpm forge.lua
 
+install -m 0755 -vd   %{buildroot}%{_spectemplatedir}
+install -m 0644 -vp   spectemplate*\.spec \
+                      %{buildroot}%{_spectemplatedir}
+
 %files
 %dir %{rrcdir}
 %{rrcdir}/macros
@@ -185,7 +223,7 @@ install -p -m 644 -t %{buildroot}%{_rpmluadir}/fedora/srpm forge.lua
 %dir %{_rpmluadir}/fedora
 %dir %{_rpmluadir}/fedora/srpm
 %dir %{_rpmluadir}/fedora/rpm
-%{_rpmluadir}/fedora/*.lua
+%{_rpmluadir}/fedora/*lua
 %{_rpmluadir}/fedora/srpm/*lua
 
 %doc buildflags.md
@@ -201,6 +239,9 @@ install -p -m 644 -t %{buildroot}%{_rpmluadir}/fedora/srpm forge.lua
 %{rrcdir}/find-provides.d/modalias.prov
 %{_rpmconfigdir}/macros.d/macros.kmp
 
+%files -n redhat-rpm-templates
+%{_spectemplatedir}/*.spec
+
 %changelog
 * Mon Jul 01 2019 Florian Festi <ffesti@redhat.com> - 134-1
 - Switch binary payload compression to Zstandard level 19
diff --git a/spectemplate-forge-0-release.fake b/spectemplate-forge-0-release.fake
new file mode 100644
index 0000000..0b38ed6
--- /dev/null
+++ b/spectemplate-forge-0-release.fake
@@ -0,0 +1,74 @@
+# Any software publishing website, permitting the download of source archives
+# via normalized URLs, that can be deduced from a project root URL and version,
+# commit, tag, scm, extension… values is a “forge” that can be supported by
+# the forgemeta macro. Common examples are GitLab and GitHub. forgemeta
+# centralizes and abstracts our knowledge about those forges, so packagers do
+# not have to handle download quirks manually.
+#
+# forgemeta makes it easy to switch from release to tag to commit source
+# archives. Using forgemeta, forge download URLs or guideline changes are
+# propagated to spec files without manual refactoring.
+#
+# When those changes result in a different naming or structure of the source
+# archive, the source file needs to be uploaded to the build system before
+# rebuilding existing spec files. That is the main drawback of using
+# forgemeta.
+#
+# This template shows how to package a release state using the forgemeta macro.
+# That should be the default target use case.
+# Other less common use cases are documented in separate templates.
+#
+# The project url on the forge, for example
+# https://gitlab.gnome.org/GNOME/gtk/
+%global forgeurl 
+#
+# Packaging a release requires setting Version before calling forgemeta.
+# Because most forges follow the git model, and git made no provision for
+# release objects, forgemeta will try to guess the customary way to write
+# release tags on the selected forge.
+# If it guesses wrong use the forge-tag template instead of this one.
+Version:         
+#
+# forgemeta converts the suppplied rpm variables to variables that can be used
+# in the spec file. Most of those can be overriden before or after the
+# forgemeta call.
+#  – use the “-i” flag to display the variables forgemeta reads and sets
+#  – use the “-v” flag if you want verbose processing
+#  – remove  “-i” and “-v” before commit
+%forgemeta
+
+# The following lines use  variables computed by forgemeta as default values.
+# You can replace them with manual definitions. For example, replace forgeurl
+# with the project homepage if it exists separately from the repository URL.
+# Only replace the variables when it adds value to the spec file and you
+# understand the consequences. Release ordering is controlled by the packager
+# with x%{?dist}/0.x%{?dist} number chains.
+Name:    
+Release: 1%{?dist}
+Summary: 
+URL:     %{forgeurl}
+Source:  %{forgesource}
+%description
+
+
+%prep
+# forgesetup calls setup with the correct flags for archives downloaded from
+# the selected forge. A forgeautosetup autosetup wrapper is also provided. If
+# you disagree with the computed setup/autosetup flags, just call
+# setup/autosetup directly.
+#  – use the “-v” flag if you want verbose processing
+%forgesetup
+#
+# After this point the archive extraction is done. forgemeta is no longer used.
+
+%build
+
+%install
+
+%check
+
+%files
+%license 
+%doc 
+
+%changelog
diff --git a/spectemplate-forge-1-tag.fake b/spectemplate-forge-1-tag.fake
new file mode 100644
index 0000000..6cde5ed
--- /dev/null
+++ b/spectemplate-forge-1-tag.fake
@@ -0,0 +1,46 @@
+# This template shows how to package a tag state using the forgemeta macro.
+# For more explanations on forgemeta, read the forgemeta-release template.
+#
+# The project url on the forge
+%global forgeurl 
+#
+# The tag being packaged
+%global tag      
+#
+#  – use the “-i” flag to display the variables forgemeta reads and sets
+#  – use the “-v” flag if you want verbose processing
+#  – remove  “-i” and “-v” before commit
+%forgemeta
+
+# The following lines use variables computed by forgemeta as default values.
+# You can replace them with manual definitions.
+# forgemeta will prepend tag information to dist. Release ordering is
+# controlled by the packager with x%{?dist}/0.x%{?dist} numbers chains.
+Name:    
+Version: 
+Release: 1%{?dist}
+Summary: 
+URL:     %{forgeurl}
+Source:  %{forgesource}
+%description
+
+
+%prep
+#  – an autosetup wrapper, forgeautosetup, is also provided
+#  – use the “-v” flag if you want verbose processing; remove it before commit
+#  – call forgesetup/autosetup directly if you do not like the result
+%forgesetup
+#
+# After this point the archive extraction is done. forgemeta is no longer used.
+
+%build
+
+%install
+
+%check
+
+%files
+%license 
+%doc 
+
+%changelog
diff --git a/spectemplate-forge-2-commit.fake b/spectemplate-forge-2-commit.fake
new file mode 100644
index 0000000..ac10f65
--- /dev/null
+++ b/spectemplate-forge-2-commit.fake
@@ -0,0 +1,46 @@
+# This template shows how to package a commit state using the forgemeta macro.
+# For more explanations on forgemeta, read the forgemeta-release template.
+#
+# The project url on the forge
+%global forgeurl 
+#
+# The commit being packaged (when using git, a full hash)
+%global commit   
+#
+#  – use the “-i” flag to display the variables forgemeta reads and sets
+#  – use the “-v” flag if you want verbose processing
+#  – remove  “-i” and “-v” before commit
+%forgemeta
+
+# The following lines use variables computed by forgemeta as default values.
+# You can replace them with manual definitions.
+# forgemeta will prepend commit information to dist. Release ordering is
+# controlled by the packager with x%{?dist}/0.x%{?dist} numbers chains.
+Name:    
+Version: 
+Release: 1%{?dist}
+Summary: 
+URL:     %{forgeurl}
+Source:  %{forgesource}
+%description
+
+
+%prep
+#  – an autosetup wrapper, forgeautosetup, is also provided
+#  – use the “-v” flag if you want verbose processing; remove it before commit
+#  – call forgesetup/autosetup directly if you do not like the result
+%forgesetup
+#
+# After this point the archive extraction is done. forgemeta is no longer used.
+
+%build
+
+%install
+
+%check
+
+%files
+%license 
+%doc 
+
+%changelog
diff --git a/spectemplate-forge-3-multi.fake b/spectemplate-forge-3-multi.fake
new file mode 100644
index 0000000..eadb6b8
--- /dev/null
+++ b/spectemplate-forge-3-multi.fake
@@ -0,0 +1,81 @@
+# This template shows how to package multiple source archives using the
+# forgemeta macro.
+#
+# PACKAGING MULTIPLE PROJECT ARCHIVES IN A SINGLE SPEC IS DISCOURAGED. IT OFTEN
+# REQUIRES ERROR-INDUCING VERSIONNING DECISIONS. In rpm, versioning is not an
+# administrative decoration. Versioning controls the upgrade logic. If upstream
+# deemed necessary to release a project through multiple archives, mirror its
+# decision using multiple spec files. That will be safer, simpler, and
+# ultimately less work.
+#
+# For more explanations on forgemeta, read the forgemeta-release template.
+#
+# Start by declaring the characteristics of each source using a	number-suffixed
+# variable block:
+#  – no suffix and zero suffix blocks are aliases
+#  – they are “special” and identify the main source archive
+#  — they use Version: to identify a release
+#  – other blocks use a version<number> variable for the same need
+#  – the syntax is otherwise identical to single archive mode; see the various
+#    forge templates for examples.
+#
+# Main archive. In this example we package a full release
+%global forgeurl0 
+Version:          
+
+# Second archive.
+%global forgeurl1 
+%global version1  
+
+# Third archive. This time a tag. Continue as necessary.
+%global forgeurl2 
+%global tag2      
+
+#  – use the “-a” flag to process all the source archives in a single pass
+#  – use     “-z <number>” to process only the declaration block suffixed with
+#    <number>
+#  — without “-a” of “-z <number>” only the main archive is processed
+#  – use the “-i” flag to display the variables forgemeta reads and sets
+#  – use the “-v” flag if you want verbose processing
+#  – remove  “-i” and “-v” before commit
+%forgemeta -a
+
+# The following lines use variables computed by forgemeta as default values.
+# You can replace them with manual definitions.
+# Release ordering is controlled by the packager with x%{?dist}/0.x%{?dist}
+# numbers chains.
+Name:    
+Release: 1%{?dist}
+Summary: 
+URL:     %{forgeurl0}
+# https://github.com/rpm-software-management/rpm/issues/539
+Source0: %{forgesource0}
+Source1: %{forgesource1}
+Source2: %{forgesource2}
+%description
+
+
+%prep
+#  – use the “-a” flag to process all the source archives in a single pass
+#  – use     “-z <number>” to process only the declaration block suffixed with
+#    <number>
+#  — without “-a” of “-z <number>” only the main archive is processed
+#  – an autosetup wrapper, forgeautosetup, is also provided
+#  – forgeautosetup does not understand “-a”
+#  – use the “-v” flag if you want verbose processing; remove it before commit
+#  – call forgesetup/autosetup directly if you do not like the result
+%forgesetup -a
+#
+# After this point the archive extraction is done. forgemeta is no longer used.
+
+%build
+
+%install
+
+%check
+
+%files
+%license 
+%doc 
+
+%changelog
diff --git a/spectemplate-forge-4-branch.fake b/spectemplate-forge-4-branch.fake
new file mode 100644
index 0000000..4034ecd
--- /dev/null
+++ b/spectemplate-forge-4-branch.fake
@@ -0,0 +1,49 @@
+# This template shows how to package a branch state using the forgemeta macro.
+#
+# BRANCH STATES ARE NOT REPRODUCIBLE AND SHOULD NEVER BE SHARED WITH OTHERS.
+#
+# For more explanations on forgemeta, read the forgemeta-release template.
+#
+# The project url on the forge
+%global forgeurl 
+#
+# The branch being packaged
+%global branch   
+#
+#  – use the “-i” flag to display the variables forgemeta reads and sets
+#  – use the “-v” flag if you want verbose processing
+#  – remove  “-i” and “-v” before commit
+%forgemeta
+
+# The following lines use variables computed by forgemeta as default values.
+# You can replace them with manual definitions.
+# forgemeta will prepend branch information to dist. Release ordering is
+# controlled by the packager with x%{?dist}/0.x%{?dist} number chains.
+Name:    
+Version: 
+Release: 1%{?dist}
+Summary: 
+URL:     %{forgeurl}
+Source:  %{forgesource}
+%description
+
+
+%prep
+#  – an autosetup wrapper, forgeautosetup, is also provided
+#  – use the “-v” flag if you want verbose processing; remove it before commit
+#  – call forgesetup/autosetup directly if you do not like the result
+%forgesetup
+#
+# After this point the archive extraction is done. forgemeta is no longer used.
+
+%build
+
+%install
+
+%check
+
+%files
+%license 
+%doc 
+
+%changelog