From 522142a1f87794cd4ea02e6813a1e4d53957fd26 Mon Sep 17 00:00:00 2001 From: Nicolas Mailhot Date: Nov 02 2018 18:27:11 +0000 Subject: [PATCH 1/4] document the use of forge macros --- diff --git a/guidelines/modules/ROOT/examples/spectemplate-forge-branch.spec b/guidelines/modules/ROOT/examples/spectemplate-forge-branch.spec new file mode 100644 index 0000000..3986a30 --- /dev/null +++ b/guidelines/modules/ROOT/examples/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/guidelines/modules/ROOT/examples/spectemplate-forge-commit.spec b/guidelines/modules/ROOT/examples/spectemplate-forge-commit.spec new file mode 100644 index 0000000..0af8bb4 --- /dev/null +++ b/guidelines/modules/ROOT/examples/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/guidelines/modules/ROOT/examples/spectemplate-forge-multi.spec b/guidelines/modules/ROOT/examples/spectemplate-forge-multi.spec new file mode 100644 index 0000000..3730473 --- /dev/null +++ b/guidelines/modules/ROOT/examples/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 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 ” to process only the declaration block suffixed with +# +# — without “-a” of “-z ” 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 ” to process only the declaration block suffixed with +# +# — without “-a” of “-z ” 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/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec b/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec new file mode 100644 index 0000000..7a57e69 --- /dev/null +++ b/guidelines/modules/ROOT/examples/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/guidelines/modules/ROOT/examples/spectemplate-forge-tag.spec b/guidelines/modules/ROOT/examples/spectemplate-forge-tag.spec new file mode 100644 index 0000000..bf0035b --- /dev/null +++ b/guidelines/modules/ROOT/examples/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 diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc index 2e389f2..6b54ddc 100644 --- a/guidelines/modules/ROOT/pages/SourceURL.adoc +++ b/guidelines/modules/ROOT/pages/SourceURL.adoc @@ -14,6 +14,56 @@ There are several cases where upstream is not providing the source to you in an Here are some specific examples: +== Using Forges (Hosted Revision Control) + +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 `redhat-rpm-config` `+%{forgemeta}+` macro. Common Forge 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}+`. + +Templates showcasing the various ways `+%{forgemeta}+` can be used are provided here and in the `rpmdevtools-redhat-rpm-config` package. + +=== `+%{forgemeta}+` Examples + +==== Release + +.spectemplate-forge-release.spec +[source] +---- +include::{examplesdir}/spectemplate-forge-release.spec[] +---- + +==== Tag + +.spectemplate-forge-tag.spec +[source] +---- +include::{examplesdir}/spectemplate-forge-tag.spec[] +---- + +==== Commit + +.spectemplate-forge-commit.spec +[source] +---- +include::{examplesdir}/spectemplate-forge-commit.spec[] +---- + +==== Branch +.spectemplate-forge-branch.spec +[source] +---- +include::{examplesdir}/spectemplate-forge-branch.spec[] +---- + +==== Multiple Sources +.spectemplate-forge-multi.spec +[source] +---- +include::{examplesdir}/spectemplate-forge-multi.spec[] +---- + == Using Revision Control In some cases you may want to pull sources from upstream's revision control system because there have been many changes since the last release and you think that a tarball that you generate from there will more accurately show how the package relates to upstream's development. Here's how you can use a comment to show where the source came from: From d31d886a5cfcd6440374c1e010c8d2318ff56af6 Mon Sep 17 00:00:00 2001 From: Nicolas Mailhot Date: Nov 03 2018 12:37:04 +0000 Subject: [PATCH 2/4] Forge: sync with redhat-rpm-config PR47 --- diff --git a/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec b/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec index 7a57e69..d005310 100644 --- a/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec +++ b/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec @@ -1,19 +1,3 @@ -# 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 diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc index 6b54ddc..beaa671 100644 --- a/guidelines/modules/ROOT/pages/SourceURL.adoc +++ b/guidelines/modules/ROOT/pages/SourceURL.adoc @@ -16,17 +16,15 @@ Here are some specific examples: == Using Forges (Hosted Revision Control) -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 `redhat-rpm-config` `+%{forgemeta}+` macro. Common Forge examples are GitLab and GitHub. `+%{forgemeta}+` centralizes and abstracts our knowledge about those forges, so packagers do not have to handle download quirks manually. +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 `redhat-rpm-config` `+%{forgemeta}+` macro. Common Forge 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}+`. -Templates showcasing the various ways `+%{forgemeta}+` can be used are provided here and in the `rpmdevtools-redhat-rpm-config` package. +The following examples are taken from the `redhat-rpm-templates` package, that provides their latest version. -=== `+%{forgemeta}+` Examples - -==== Release +=== Release Example .spectemplate-forge-release.spec [source] @@ -34,7 +32,7 @@ Templates showcasing the various ways `+%{forgemeta}+` can be used are provided include::{examplesdir}/spectemplate-forge-release.spec[] ---- -==== Tag +=== Tag Example .spectemplate-forge-tag.spec [source] @@ -42,7 +40,7 @@ include::{examplesdir}/spectemplate-forge-release.spec[] include::{examplesdir}/spectemplate-forge-tag.spec[] ---- -==== Commit +=== Commit Example .spectemplate-forge-commit.spec [source] @@ -50,14 +48,14 @@ include::{examplesdir}/spectemplate-forge-tag.spec[] include::{examplesdir}/spectemplate-forge-commit.spec[] ---- -==== Branch +=== Branch Example .spectemplate-forge-branch.spec [source] ---- include::{examplesdir}/spectemplate-forge-branch.spec[] ---- -==== Multiple Sources +=== Multiple Sources Example .spectemplate-forge-multi.spec [source] ---- From 6403a7363ee212452a64c0ba1ca4deb3b365df99 Mon Sep 17 00:00:00 2001 From: Nicolas Mailhot Date: Nov 03 2018 12:42:27 +0000 Subject: [PATCH 3/4] forge: tweak release comments --- diff --git a/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec b/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec index d005310..7b7ec09 100644 --- a/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec +++ b/guidelines/modules/ROOT/examples/spectemplate-forge-release.spec @@ -1,3 +1,7 @@ +# This template shows how to package a commit 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 From f64369e384245ecf1f14ae3f14c6910913fa56c7 Mon Sep 17 00:00:00 2001 From: Nicolas Mailhot Date: Dec 04 2018 19:23:00 +0000 Subject: [PATCH 4/4] add more empty lines --- diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc index beaa671..25e053f 100644 --- a/guidelines/modules/ROOT/pages/SourceURL.adoc +++ b/guidelines/modules/ROOT/pages/SourceURL.adoc @@ -49,6 +49,7 @@ include::{examplesdir}/spectemplate-forge-commit.spec[] ---- === Branch Example + .spectemplate-forge-branch.spec [source] ---- @@ -56,6 +57,7 @@ include::{examplesdir}/spectemplate-forge-branch.spec[] ---- === Multiple Sources Example + .spectemplate-forge-multi.spec [source] ----