From c5be565d56869456341be1aa4c3c1c04da48ecca Mon Sep 17 00:00:00 2001
From: Nicolas Mailhot <nim@fedoraproject.org>
Date: Nov 02 2018 16:21:58 +0000
Subject: forge: add some templates and documentation


---

diff --git a/common.lua b/common.lua
index 77ebf69..d39a21f 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 98aa6c2..83aec07 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 %{_sysconfdir}/rpmdevtools
+
 # 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 2d50640..e1d1016 100644
--- a/redhat-rpm-config.spec
+++ b/redhat-rpm-config.spec
@@ -80,6 +80,13 @@ Source801: forge.lua
 # Documentation
 Source900: buildflags.md
 
+# Spec templates
+Source950: spectemplate-forge-release.spec
+Source951: spectemplate-forge-tag.spec
+Source952: spectemplate-forge-commit.spec
+Source953: spectemplate-forge-branch.spec
+Source954: spectemplate-forge-multi.spec
+
 BuildArch: noarch
 BuildRequires: perl-generators
 Requires: coreutils
@@ -115,6 +122,7 @@ Conflicts: gcc < 8.0.1-0.22
 Provides: system-rpm-config = %{version}-%{release}
 
 %global rrcdir /usr/lib/rpm/redhat
+%{load:%{SOURCE100}}
 
 %description
 Red Hat specific rpm configuration files.
@@ -126,11 +134,27 @@ Requires: redhat-rpm-config >= 13
 %description -n kernel-rpm-macros
 Macros and scripts for building kernel module packages.
 
+%package  -n rpmdevtools-%{name}
+Summary:   Example rpm spec templates for the macros provided by %{name}
+BuildArch: noarch
+
+Requires: %{name} = %{version}-%{release}
+Requires: rpmdevtools
+
+%description -n rpmdevtools-%{name}
+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*\.spec ; do
+  target=$(echo "${template}" | sed "s|^\(.*\)\.spec$|\1-bare.spec|g")
+  grep -v '^#' "${template}" > "${target}"
+  touch -r "${template}" "${target}"
+done
 
 %install
 mkdir -p %{buildroot}%{rrcdir}
@@ -158,6 +182,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
@@ -196,6 +224,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 rpmdevtools-%{name}
+%config(noreplace) %{_spectemplatedir}/*.spec
+
 %changelog
 * Mon Oct 22 2018 Igor Gnatenko <ignatenkobrain@fedoraproject.org> - 123-1
 - Add -q option to %%forgesetup
diff --git a/spectemplate-forge-branch.spec b/spectemplate-forge-branch.spec
new file mode 100644
index 0000000..3986a30
--- /dev/null
+++ b/spectemplate-forge-branch.spec
@@ -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
diff --git a/spectemplate-forge-commit.spec b/spectemplate-forge-commit.spec
new file mode 100644
index 0000000..0af8bb4
--- /dev/null
+++ b/spectemplate-forge-commit.spec
@@ -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-multi.spec b/spectemplate-forge-multi.spec
new file mode 100644
index 0000000..3730473
--- /dev/null
+++ b/spectemplate-forge-multi.spec
@@ -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-release.spec b/spectemplate-forge-release.spec
new file mode 100644
index 0000000..7a57e69
--- /dev/null
+++ b/spectemplate-forge-release.spec
@@ -0,0 +1,70 @@
+# 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.
+#
+# 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-tag.spec b/spectemplate-forge-tag.spec
new file mode 100644
index 0000000..bf0035b
--- /dev/null
+++ b/spectemplate-forge-tag.spec
@@ -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