PR#1255: Adjust guidelines for %autorelease+%autochangelog - packaging-committee

packaging-committee

#1255 Adjust guidelines for %autorelease+%autochangelog

Merged a year ago by ngompa. Opened a year ago by zbyszek.

zbyszek/packaging-committee rpmautospec into master

Drop discussion of builds in older branches with %autorelease

Zbigniew Jędrzejewski-Szmek • a year ago

3db83e4

Adjust "Renaming or replacing" for rpmautospec

Zbigniew Jędrzejewski-Szmek • a year ago

0cd555f

Adjust guidelines for %autorelease+%autochangelog

Zbigniew Jędrzejewski-Szmek • a year ago

67b6169

guidelines/modules/ROOT/nav.adoc

file modified

		`@@ -14,6 +14,7 @@`
		`* xref:Initial_Service_Setup.adoc[Initial Service Setup]`
		`* xref:Langpacks.adoc[Language Packs]`
		`* xref:LicensingGuidelines.adoc[Licensing]`
		`+ * xref:manual-changelog.adoc[Manual Changelog]`
		`* xref:Naming.adoc[Naming]`
		`* xref:PatchUpstreamStatus.adoc[Patch Status]`
		`* xref:Per-Product_Configuration.adoc[Per-Product Configuration]`

guidelines/modules/ROOT/pages/Versioning.adoc

file modified

+92 -77

		`@@ -9,6 +9,9 @@`
		`which are treated as updates by RPM's version comparison algorithm`
		`while accommodating varied and often inconsistent upstream versioning schemes.`

		+ The `+Version:+` field contains the upstream project version,
		+ and the `+Release:+` field specifies the downstream release number.
		`+`
		`== Some definitions`

		`Note that upstreams may each have their own terminology`
		`@@ -51,7 +54,7 @@`
		`from RPM's implementation then simply using upstream's versions directly`
		`will result in updates which don't actually update any packages.`

		`- == Epoch: tag`
		+ == `+Epoch+` tag

		The `+Epoch:+` tag provides the most significant input to RPM's version comparison function.
		`If present, it must consist of a positive integer.`
		`@@ -60,6 +63,26 @@`
		The `+Epoch:+` tag, once introduced to a package,
		`must never be removed or decreased.`

		+ == `+Release+` tag
		`+`
		+ The `+Release:+` should be managed automatically using the `+%autorelease+` macro:
		`+ [source, rpm-spec]`
		`+ ----`
		`+ Release: %autorelease`
		`+ ----`
		`+`
		`+ As described in`
		`+ https://docs.pagure.org/fedora-infra.rpmautospec/autorelease.html[%autorelease documentation],`
		`+ the build machinery will`
		+ replace the macro with the number of builds since the last commit that changed the `+Version+` field,
		+ suffixed with the `%{?dist}` tag.
		+ This means that a commit that changes `+Version+` automatically gets `Release: 1%{?dist}`,
		+ and commits after that get `Release: 2%{?dist}`, `Release: 3%{?dist}`, and so on.
		`+`
		+ Alternatively, the `+Release:+` field may be updated manually.
		`+ See xref:Versioning.adoc#traditional-versioning[Traditional versioning`
		`+ with part of the upstream version information in the release field].`
		`+`
		`== Simple versioning`

		`Most upstream versioning schemes are "simple";`
		`@@ -79,12 +102,8 @@`

		`To package release versions of software using this versioning scheme:`

		- * Use the upstream verbatim in the `+Version:+` tag.
		+ * Use the upstream project version verbatim in the `+Version:+` tag.
		`Don't trim leading zeroes.`
		- * Use a `+Release:+` tag starting with 1 (never 0).
		`- Append the xref:DistTag.adoc[Dist Tag].`
		`- Increment the release (by 1) for each update you make.`
		- Reset to 1 whenever you change `+Version:+`.

		`== Complex versioning`

		`@@ -105,6 +124,9 @@`
		`* More than one of the above may apply (lucky you).`
		`Follow all of the relevant recommendations below together.`

		+ This subsection describes how to modify the upstream project version to be suitable for the `+Version+` field.
		+ Use of `Release: +%autorelease+` remains unchanged.
		`+`
		`=== Handling non-sorting versions with tilde, dot, and caret`

		The tilde symbol ('`+~+`') is used before a version component which must sort earlier than any non-tilde component.
		`@@ -177,6 +199,7 @@`
		"`+0+`" sorts lower than any other possible value that upstream might choose.
		`If upstream does choose to release "version 0",`
		then just set `+Release:+` higher than the previous value.
		+ (When `%autorelease` is used, this happens automatically.)

		`=== Upstream uses invalid characters in the version`

		`@@ -241,118 +264,122 @@`

		`[%header]`
		`\|===`
		`- \|Upstream\| Version field \| Release field \| Explanation`
		`-`
		`- \|1.0 \|1.0 \| 1%{?dist} \| The first release.`
		`-`
		`- \|1.1 \|1.1 \| 1%{?dist} \| An upstream update.`
		`+ \|Upstream version \| Version tag \| Explanation`

		`- \|1.1 \|1.1 \| 2%{?dist} \| You made a change to the package but the upstream version didn't change.`
		`+ \|1.0 \|1.0 \| The first release.`

		`- \|1.2 \|1.2 \| 1%{?dist} \| The upstream version changed, so Release: goes back to 1.`
		`+ \|1.1 \|1.1 \| An upstream update.`

		`- \|1.2.1 \|1.2.1 \|1%{?dist} \| Extra levels of versioning are OK…`
		`+ \|1.2.1 \|1.2.1 \| Another upstream update. Extra levels of versioning are OK…`

		`- \|1.3 \|1.3 \|1%{?dist} \| …they can come and go without problems.`
		`+ \|1.3 \|1.3 \| …they can come and go without problems.`
		`\|===`

		+ In this case the full N-V-R could be e.g. `pkg-1.2.1-1.fc{CURRENTVER}` (immediately after an update)
		+ or `pkg-1.2.1-5.fc{CURRENTVER}` (after downstream rebuilds with the same upstream version).
		`+`
		`[%header]`
		`\|===`
		`- \|Upstream\| Version field \| Release field \| Explanation`
		`+ \|Upstream version \| Version tag \| Explanation`

		`- \| 5.2 \| 5.2 \| 1%{?dist} \|`
		`+ \| 5.2 \| 5.2 \| Upstream release.`

		`- \| 5.2a \| 5.2a \| 1%{?dist} \| Upstream introduced a letter to indicate a patch release. You trust upstream to use letters in alphabetical order, so it's OK to use the version as is.`
		`+ \| 5.2a \| 5.2a \| Upstream introduced a letter to indicate a patch release. You trust upstream to use letters in alphabetical order, so it's OK to use the version as is.`

		`- \| 5.2b \| 5.2b \| 1%{?dist} \| Another patch release after 5.2 - this is not a beta.`
		`+ \| 5.2b \| 5.2b \| Another patch release after 5.2 — this is not a beta.`

		`- \| 5.2b.1 \| 5.2b.1 \| 1%{?dist} \| Even this is OK as long as the sequence increases.`
		`+ \| 5.2b.1 \| 5.2b.1 \| Even this is OK as long as the sequence increases.`

		`- \| 5.3 \| 5.3 \| 1%{?dist} \|`
		`+ \| 5.3 \| 5.3 \| Another upstream release.`
		`\|===`

		+ In this case the full N-V-R could be e.g. `pkg-5.2b.1-1.fc{CURRENTVER}`.
		`+`
		`==== Complex versioning with a reasonable upstream`

		`[%header]`
		`\|===`
		`- \|Upstream version \| Full package NEVRA \| Notes`
		`+ \|Upstream version \| Version tag \| Notes`

		- \| 1.0.0-rc1 \| `+pkg-1.0.0~rc1-1%{?dist}+` \| first prerelease
		+ \| 1.0.0-rc1 \| `+1.0.0~rc1+` \| first prerelease

		- \| 1.0.0-rc2 \| `+pkg-1.0.0~rc2-1%{?dist}+` \| second prerelease
		+ \| 1.0.0-rc2 \| `+1.0.0~rc2+` \| second prerelease

		- \| 1.0.0 \| `+pkg-1.0.0-1%{?dist}+` \| release
		+ \| 1.0.0 \| `+1.0.0+` \| release

		- \| 1.0.1 \| `+pkg-1.0.1-1%{?dist}+` \| bugfix release
		+ \| 1.0.1 \| `+1.0.1+` \| bugfix release

		- \| 1.0.1-security1 \| `+pkg-1.0.1.security1-1%{?dist}+` \| security bufix release
		+ \| 1.0.1-security1 \| `+pkg-1.0.1.security1+` \| security bufix release
		`\|===`

		+ In this case the full N-V-R could be e.g. `pkg-1.0.0~rc2-42.fc{CURRENTVER}` (if many rebuilds were done).
		`+`
		`==== Complex versioning with non-sorting upstream post-release versions`

		`[%header]`
		`\|===`
		`- \|Upstream version \| Full package NEVRA \| Notes`
		`-`
		- \| 1.1.0~BETA \| `+pkg-1.1.0~BETA-1%{?dist}+` \| this is a prerelease, first beta
		`+ \|Upstream version \| Version tag \| Notes`

		- \| 1.1.0~BETA1 \| `+pkg-1.1.0~BETA1-1%{?dist}+` \| this is a prerelease, second beta
		+ \| 1.1.0~BETA \| `+1.1.0~BETA+` \| this is a prerelease, first beta

		- \| 1.1.0~BETA2 \| `+pkg-1.1.0~BETA2-1%{?dist}+` \| this is a prerelease, third beta
		+ \| 1.1.0~BETA1 \| `+1.1.0~BETA1+` \| this is a prerelease, second beta

		- \| 1.1.0~CR1 \| `+pkg-1.1.0~CR1-1%{?dist}+` \| this is a prerelease, candidate release 1
		+ \| 1.1.0~BETA2 \| `+1.1.0~BETA2+` \| this is a prerelease, third beta

		- \| 1.1.0~CR2 \| `+pkg-1.1.0~CR2-1%{?dist}+` \| this is a prerelease, candidate release 2
		+ \| 1.1.0~CR1 \| `+1.1.0~CR1+` \| this is a prerelease, candidate release 1

		- \| \| `+pkg-1.1.0~CR2-2%{?dist}+` \| this is a prerelease, candidate release 2, second build
		+ \| 1.1.0~CR2 \| `+1.1.0~CR2+` \| this is a prerelease, candidate release 2

		- \| 1.1.0-1% \| `+pkg-1.1.0-1%{?dist}+` \| final release
		+ \| 1.1.0-1% \| `+1.1.0+` \| final release

		- \| 1.1.0-GA1 \| `+pkg-1.1.0.20201001.GA1-1%{?dist}+` \| post release, GA1
		+ \| 1.1.0-GA1 \| `+1.1.0.20201001.GA1+` \| post release, GA1

		- \| 1.1.0-CP1 \| `+pkg-1.1.0.20201011.CP1-1%{?dist}+` \| post release, CP1, after GA1, does not sort properly
		+ \| 1.1.0-CP1 \| `+1.1.0.20201011.CP1+` \| post release, CP1, after GA1, does not sort properly

		- \| 1.1.0-CP2 \| `+pkg-1.1.0.20201101.CP2-1%{?dist}+` \| post release, CP2, after CP1
		+ \| 1.1.0-CP2 \| `+1.1.0.20201101.CP2+` \| post release, CP2, after CP1

		- \| 1.1.0-SP1 \| `+pkg-1.1.0.20210101.SP1-1%{?dist}+` \| post release, SP1, after CP2
		+ \| 1.1.0-SP1 \| `+1.1.0.20210101.SP1+` \| post release, SP1, after CP2

		- \| 1.1.0-SP1-CP1 \| `+pkg-1.1.0.20210105.SP1_CP1-1%{?dist}+` \| post release, SP1_CP1, after SP1
		+ \| 1.1.0-SP1-CP1 \| `+1.1.0.20210105.SP1_CP1+` \| post release, SP1_CP1, after SP1
		`\|===`

		+ In this case the full N-V-R could be e.g. `pkg-1.1.0.20210105.SP1_CP1-1.fc{CURRENTVER}`.

		`==== Complex versioning with a pre- and post-release snapshots`

		`[%header]`
		`\|===`
		`- \|Upstream version \| Full package NEVRA \| Notes`
		`+ \|Upstream version \| Version \| Notes`

		- \| 1.0.0-rc1 \| `+pkg-1.0.0~rc1-1%{?dist}+` \| First prerelease
		+ \| 1.0.0-rc1 \| `+1.0.0~rc1+` \| First prerelease

		- \| 1.0.0-rc2 \| `+pkg-1.0.0~rc2-1%{?dist}+` \| Second prerelease
		+ \| 1.0.0-rc2 \| `+1.0.0~rc2+` \| Second prerelease

		- \| git commit `f00fabd` \| `+pkg-1.0.0~rc2^20210101gf00fabd-1%{?dist}+` \| Post-prerelease snapshot
		+ \| git commit `f00fabd` \| `+1.0.0~rc2^20210101gf00fabd+` \| Post-prerelease snapshot

		- \| 1.0.0 \| `+pkg-1.0.0-1%{?dist}+` \| A release
		+ \| 1.0.0 \| `+1.0.0+` \| A release

		- \| \| `+pkg-1.0.0-2%{?dist}+` \| A rebuild from the same sources
		+ \| 1.0.1 \| `+1.0.1+` \| A bugfix release

		- \| 1.0.1 \| `+pkg-1.0.1-1%{?dist}+` \| A bugfix release
		+ \| git commit `bbbccc0` \| `+1.0.1^20210203gbbbccc0+` or `+pkg-1.0.1^1.gbbbccc0+` \| A snapshot

		- \| git commit `bbbccc0` \| `+pkg-1.0.1^20210203gbbbccc0-1%{?dist}+` or `+pkg-1.0.1^1.gbbbccc0-1%{?dist}+` \| A snapshot
		+ \| 1.0.1-security1 \| `+1.0.1.security1+` \| A security bufix release. From past history we know that the bugfix releases will have sortable versions. If not, we could use '`+<date>.security1+`' instead.

		- \| 1.0.1-security1 \| `+pkg-1.0.1.security1-1%{?dist}+` \| A security bufix release. From past history we know that the bugfix releases will have sortable versions. If not, we could use '`+<date>.security1+`' instead.
		`-`
		- \| git commit `abc0202` \| `+pkg-1.0.1.security1^20210301gabc0202-1%{?dist}+` or `+pkg-1.0.1.security1^1.gabc0202-1%{?dist}+` \| Another snapshot
		+ \| git commit `abc0202` \| `+1.0.1.security1^20210301gabc0202+` or `+pkg-1.0.1.security1^1.gabc0202+` \| Another snapshot
		`\|===`

		+ In this case the full N-V-R could be e.g. `pkg-1.0.1.security1^20210301gabc0202-1.fc{CURRENTVER}`.

		`- == Traditional versioning with part of the upstream version information in the release field`
		`+ [#traditional-versioning]`
		`+ == Traditional versioning with part of the upstream version information in the Release field`

		`The method described in this section is deprecated, but may be used.`
		`As mentioned in the <<Handling non-sorting versions with tilde, dot, and caret>> section above,`
		`this method is recommended for packages with complex versioning when supporting RHEL7`
		`and other systems with old rpm versions.`

		+ In this method, `+%autorelease+` is not used, and the `Release` field must be managed manually.
		`+`
		`This method for dealing with most pre- and post-release versions and unsortable versions`
		involves potentially removing some information from the `+Version:+` tag
		while imposing additional structure onto the `+Release:+` tag.
		`@@ -382,7 +409,7 @@`
		and in most situations `+<minorbump>+` won't be used at all.
		`Simply do not include those which you don't have.`

		`- Note that the Dist tag is supplied by other portions of the system`
		`+ Note that the dist tag is supplied by other portions of the system`
		`and may in some circumstances contain additional structure,`
		`including tildes.`
		`As this is not under the control of the packager,`
		`@@ -454,6 +481,17 @@`
		`Release and post-release versions must use`
		a `+Release:+` tag greater than or equal to 1.

		+ === Rebuilds in older branches using `<minorbump>`
		`+`
		`+ In the situation described in <<Only an old branch needs a change>>,`
		+ you may adjust the `+Release+` by appending a number after the dist tag,
		`+ creating a E-V-R for F{CURRENTVER} that still compares lower than the one in F{NEXTVER}.`
		+ Set `+<minorbump>+` to an in integer beginning with '1'
		`+ and increase it by one for each minor bump you need to do.`
		+ Remove `+<minorbump>+` once you are able
		`+ to increase the package release normally`
		`+ without introducing ordering issues.`
		`+`
		`=== Examples`

		`Examples of many possible versioning scenarios of traditional versioning`
		`@@ -461,29 +499,6 @@`
		`https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples].`


		`-`
		`-`
		`-`
		`- == You need to change an old branch without rebuilding the others`
		`-`
		`- Sometimes, you may find yourself in a situation where an older branch needs a fix,`
		`- but the newer branches are fine.`
		- For example, if a package has a version-release of `+1.0-1%{?dist}+`
		`- in F{CURRENTVER} and F{NEXTVER},`
		`- and only F{CURRENTVER} needs a fix.`
		`- Normally, you would need to bump the release in each of the branches`
		`- to ensure that F{CURRENTVER} < F{NEXTVER},`
		`- but that is a waste of time and energy for the newer branches`
		`- which do not need to be touched.`
		`-`
		- In this case, you may set `+<minorbump>+`
		`- to an in integer beginning with '1'`
		`- and increasing by one for each minor bump you need to do.`
		- Remove `+<minorbump>+` once you are able
		`- to increase the package release normally`
		`- without introducing ordering issues.`
		`-`
		`-`
		`== Rawhide is allowed to lag temporarily`

		`A package may temporarily have a lower EVR in Rawhide`

guidelines/modules/ROOT/pages/index.adoc

file modified

+74 -101

		`@@ -1096,133 +1096,101 @@`
		`[#changelogs]`
		`== Changelogs`

		`- _Every time_ you make changes, that is,`
		`- whenever you increment the E-V-R of a package,`
		`- add a changelog entry.`
		`- This is important not only to have an idea about the history of a package,`
		`- but also to enable users, fellow packagers, and QA people`
		`- to easily spot the changes that you make.`
		`+ The changelog describes the changes to the package that are relevant`
		`+ to the users of the package. This includes new upstream versions, important`
		`+ changes to how the package is built, rebuilds, and other changes affecting the outcome.`
		`+ Changes which are only relevant to packagers should not be mentioned in the`
		`+ changelog. This includes spec file cleanups, build error fixes or workarounds,`
		`+ and other changes which don't have an effect on content of the binary packages.`

		`- If a particular change is related to a Bugzilla bug,`
		`- include the bug ID in the changelog entry for easy reference, e.g.`
		`+ The changelog should be generated automatically from git commit logs`
		+ using the `+%autochangelog+` macro:

		`[source, rpm-spec]`
		`----`
		`%changelog`
		`- * Wed Jun 14 2003 Joe Packager <joe at gmail.com> - 1.0-2`
		`- - Added README file (#42).`
		`+ %autochangelog`
		`----`

		`- You must use one of the following formats:`
		`+ The commit subject (the first line of the commit message)`
		`+ and optionally some additional lines`
		`+ are used to generate the changelog text.`
		`+ The commit author name and email address and the commit timestamp`
		`+ are also used in changelog entry.`

		`- [source, rpm-spec]`
		`- ----`
		`- %changelog`
		`- * Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> - 0.6-4`
		`- - And fix the link syntax.`
		`- ----`
		`+ The text in the the commit message which will become part of the changelog`
		`+ should should provide a brief summary of the changes relevant for the user.`
		`+ The commit message may contain additional information that is relevant`
		`+ to packagers.`

		`- [source, rpm-spec]`
		`- ----`
		`- %changelog`
		`- * Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> 0.6-4`
		`- - And fix the link syntax.`
		`- ----`
		`+ If a particular change is related to a Bugzilla bug,`
		`+ include the bug ID in the changelog entry for easy reference, e.g.`

		`- [source, rpm-spec]`
		`+ [source]`
		`----`
		`- %changelog`
		`- * Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com>`
		`- - 0.6-4`
		`- - And fix the link syntax.`
		`+ Add README file (rhbz#1000042)`
		`----`

		`- Changelog entries should provide a brief summary`
		`- of the changes done to the package between releases,`
		`- including noting updating to a new version,`
		`- adding a patch, fixing other spec sections,`
		`- note bugs fixed, and CVE's if any.`
		`- They must never simply contain an entire copy of the source CHANGELOG entries.`
		`+ If a particular commit fixes a CVE, this information should be included too.`
		`+`
		`The intent is to give the user a hint as to what changed`
		`in a package update without overwhelming them with the technical details.`
		`- Links to upstream changelogs can be entered`
		`+ They must never simply contain an entire copy of the source CHANGELOG entries.`
		`+ Links to upstream NEWS files or changelogs can be entered`
		`for those who want additional information.`
		`- If you wish to "scramble" or "obfuscate" your email address in the changelog,`
		`- you may do so, provided that it is still understandable by humans.`

		`- === Multiple Changelog Entries per Release`
		`+ See https://docs.pagure.org/fedora-infra.rpmautospec/autochangelog.html[autochangelog documentation]`
		`+ for the details of how the changelog is generated from git commit messages,`
		`+ and how to create multi-line entries or skip entries for certain commits.`

		`- In some situations, it may be useful for packagers`
		`- to have multiple changelog entries in the spec file,`
		`- but not increment the release field for each one.`
		`- There are two supported methods for doing this:`
		+ Packagers may alternatively use a manual changelog instead of the `+%autochangelog+` macro.
		`+ This is described in xref:manual-changelog.adoc[Manual Changelog].`

		`- ==== Updating and replacing the existing date line`
		`+ === Example`

		`- In this situation, you have added this changelog entry,`
		`- but have not built the package yet:`
		`+ The packager updates package to version 1.0 and creates a commit`

		`- [source, rpm-spec]`
		`+ [console]`
		`----`
		`- %changelog`
		`- * Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`- - Fix spelling errors in package description`
		`- ----`
		`-`
		`- The next day, you make additional changes to the spec,`
		`- and need to add a new changelog line,`
		`- then you would update the existing date line for 1.0-1,`
		`- and append any new notes, making the changelog look like this:`
		`-`
		`- [source, rpm-spec]`
		`- ----`
		`- %changelog`
		`- * Nov 13 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`- - Fix spelling errors in package description`
		`- - Add a patch to fix compilation problems on F15`
		`- ----`
		`-`
		`- Please remember that this is only acceptable if 1.0-1 has not yet been built.`
		`+ $ git show`
		`+ commit 0000000000001234567890ABCDEF000000000000`
		`+ Author: Joe Packager <joe@example.com>`
		`+ Date: Wed Jun 14 2003`

		`- You can do this any number of times,`
		`- until you actually build 1.0-1 in the buildsystem.`
		`- Once you've done that,`
		`- you must change the E-V-R and any new entries should be added`
		`- as described in <<changelogs>>.`
		`+ Version 1.0`

		`- ==== Repeat the old version release with a new entry`
		`+ ... (rhbz#1000024)`
		`+ - Also fixes the slowdown reported in rhbz#1000025`
		`+ - Upstream changelog: https://example.com/package/NEWS.html#v1.0`

		`- In this situation, you have added this changelog entry,`
		`- but have not built the package yet:`
		`+ Whitespace in the spec file has been cleaned up.`

		`- [source, rpm-spec]`
		`- ----`
		`- %changelog`
		`- * Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`- - Fix spelling errors in package description`
		`+ diff --git package.spec package.spec`
		`+ index 5c77064c03..efcd53a61c 100644`
		`+ --- package.spec`
		`+ +++ package.spec`
		`+ @@ -1,5 +1,5 @@`
		`+ Name: package`
		`+ -Version: 0.1`
		`+ +Version: 0.2`
		`+ Release: %autorelease`
		`+ ...`
		`----`

		`- The next day, you make additional changes to the spec,`
		`- and need to add a new changelog line.`
		`- Now, you can add an additional changelog item with the new date,`
		`- but the same Version-Release, so your new changelog looks like this:`
		`+ When the package is built, an appropriate changelog entry will be generated.`
		+ It can be previewed with `rpmautospec generate-chagengelog`:

		`- [source, rpm-spec]`
		`+ [console]`
		`----`
		`- %changelog`
		`- * Nov 13 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`- - Add a patch to fix compilation problems on F15`
		`-`
		`- * Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`- - Fix spelling errors in package description`
		`+ $ rpmautospec generate-changelog`
		`+ * Wed Jun 14 2003 Joe Packager <joe@example.com> - 0.2-1`
		`+ - Version 1.0 (rhbz#1000024)`
		`+ - Also fixes the slowdown reported in rhbz#1000025`
		`+ - Upstream changelog: https://example.com/package/NEWS.html#v1.0`
		`----`

		`- Please remember that this is only acceptable if 1.0-1 has not yet been built.`
		`+ Note that the sentence about whitespace is not included in the changelog.`

		`- You can do this any number of times,`
		`- until you actually build 1.0-1 in the buildsystem.`
		`- Once you've done that, you must change the E-V-R`
		`- and any new entries should be added as described in <<changelogs>>.`

		`== Manpages`

		`@@ -2955,7 +2923,7 @@`
		`to the extent applicable.`

		`If a package is being renamed without any functional changes,`
		`- or is a compatible enough replacement to an existing package`
		`+ or is a compatible-enough replacement to an existing package`
		`(where "enough" means that it includes only changes of magnitude`
		`that are commonly found in version upgrade changes),`
		`provide clean upgrade paths and compatibility with:`
		`@@ -2984,10 +2952,14 @@`

		CAUTION: Take `+%{?dist}+` into account:
		`When deciding what $obsEVR should be,`
		- remember that it needs to be higher than the previous `Release:`
		- with `+%{?dist}+` expanded.
		- Example: if the package previously had `+Release: 4%{?dist}+`
		`- the release in $obsEVR should be at least 5.`
		+ remember that it needs to be higher than the previous `Release:`,
		+ including the `+%{?dist}+` suffix.
		+ Example: if the package previously had the release tag of `+-4.fcNN+`,
		`+ the release specified in $obsEVR should be at least 5.`
		`+`
		+ NOTE: If the replaced package uses `rpmautospec`,
		`+ either look at the built package (e.g. in koji) to find the actual release tag of the latest build,`
		+ or use `+rpmautospec calculate-release+` to calculate just the release number.

		`If retired packages need to be removed from end user machines`
		`because they cause dependency issues which interfere with upgrades`
		`@@ -3004,14 +2976,15 @@`
		it must be preserved in both the `+Provides:+` and `+Obsoletes:+`.
		`For example, assume foo being renamed to bar,`
		`bar is compatible with foo,`
		`- and the last foo package release being foo-1.0-3%\{?dist} with Epoch: 2.`
		+ and the last foo package release being `+foo-1.0-3.fcNN+` with `+Epoch: 2+`.
		`The following should be added to bar`
		`(and similarly for all subpackages as applicable):`

		`[source, rpm-spec]`
		`----`
		`Provides: foo = 2:%{version}-%{release}`
		`- Obsoletes: foo <= 2:1.0-4 # Important: We set the Obsoletes release to 4 to be higher than the previous Release: 3%{?dist}`
		`+ # Important: We set the Obsoletes release to 4 to be higher than the last build of foo`
		`+ Obsoletes: foo < 2:1.0-4`
		`----`

		Explicit `+Provides:+` need to be aware of whether

guidelines/modules/ROOT/pages/manual-changelog.adoc

file added

+119

		`@@ -0,0 +1,119 @@`
		`+ = Manual Changelog`
		`+`
		`+ This describes the traditional method of managing changelogs that provides a`
		`+ separate text log of user-visible changes independently of the git commit messages.`
		+ This is an alternative for the recommended method with `+%autochangelog+`
		`+ described in xref:index.adoc#changelogs[Changelogs].`
		`+`
		`+ _Every time_ you make changes, that is,`
		`+ whenever you increment the E-V-R of a package,`
		+ add a changelog entry in the `+%changelog+` section.
		`+`
		`+ Changelog entries should provide a brief summary`
		`+ of the changes done to the package between releases.`
		+ They must never simply contain an entire copy of the source `CHANGELOG` entries.
		`+ The same general rules should be followed as described in`
		`+ xref:index.adoc#changelogs[Changelogs].`
		`+`
		`+ You must use one of the following formats:`
		`+`
		`+ [source, rpm-spec]`
		`+ ----`
		`+ %changelog`
		`+ * Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> - 0.6-4`
		`+ - And fix the link syntax.`
		`+ ----`
		`+`
		`+ [source, rpm-spec]`
		`+ ----`
		`+ %changelog`
		`+ * Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> 0.6-4`
		`+ - And fix the link syntax.`
		`+ ----`
		`+`
		`+ [source, rpm-spec]`
		`+ ----`
		`+ %changelog`
		`+ * Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com>`
		`+ - 0.6-4`
		`+ - And fix the link syntax.`
		`+ ----`
		`+`
		`+ If you wish to "scramble" or "obfuscate" your email address in the changelog,`
		`+ you may do so, provided that it is still understandable by humans.`
		`+`
		`+ === Multiple Changelog Entries per Release`
		`+`
		`+ In some situations, it may be useful for packagers`
		`+ to have multiple changelog entries in the spec file,`
		`+ but not increment the release field for each one.`
		`+ There are two supported methods for doing this:`
		`+`
		`+ === Updating and replacing the existing date line`
		`+`
		`+ In this situation, you have added this changelog entry,`
		`+ but have not built the package yet:`
		`+`
		`+ [source, rpm-spec]`
		`+ ----`
		`+ %changelog`
		`+ * Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`+ - Fix spelling errors in package description`
		`+ ----`
		`+`
		`+ The next day, you make additional changes to the spec,`
		`+ and need to add a new changelog line,`
		`+ then you would update the existing date line for 1.0-1,`
		`+ and append any new notes, making the changelog look like this:`
		`+`
		`+ [source, rpm-spec]`
		`+ ----`
		`+ %changelog`
		`+ * Nov 13 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`+ - Fix spelling errors in package description`
		`+ - Add a patch to fix compilation problems on F15`
		`+ ----`
		`+`
		`+ Please remember that this is only acceptable if 1.0-1 has not yet been built.`
		`+`
		`+ You can do this any number of times,`
		`+ until you actually build 1.0-1 in the buildsystem.`
		`+ Once you've done that,`
		`+ you must change the E-V-R and any new entries should be added`
		`+ as described in`
		`+ xref:index.adoc#changelogs[Changelogs].`
		`+`
		`+ === Repeat the old version release with a new entry`
		`+`
		`+ In this situation, you have added this changelog entry,`
		`+ but have not built the package yet:`
		`+`
		`+ [source, rpm-spec]`
		`+ ----`
		`+ %changelog`
		`+ * Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`+ - Fix spelling errors in package description`
		`+ ----`
		`+`
		`+ The next day, you make additional changes to the spec,`
		`+ and need to add a new changelog line.`
		`+ Now, you can add an additional changelog item with the new date,`
		`+ but the same Version-Release, so your new changelog looks like this:`
		`+`
		`+ [source, rpm-spec]`
		`+ ----`
		`+ %changelog`
		`+ * Nov 13 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`+ - Add a patch to fix compilation problems on F15`
		`+`
		`+ * Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1`
		`+ - Fix spelling errors in package description`
		`+ ----`
		`+`
		`+ Please remember that this is only acceptable if 1.0-1 has not yet been built.`
		`+`
		`+ You can do this any number of times,`
		`+ until you actually build 1.0-1 in the buildsystem.`
		`+ Once you've done that, you must change the E-V-R`
		`+ and any new entries should be added as described in`
		`+ xref:index.adoc#changelogs[Changelogs].`

zbyszek commented a year ago

See https://fedoraproject.org/wiki/Changes/Rpmautospec_by_Default

The general approach is the the previous recommendations are described
with "may" and moved to the end or to a separate page. Use of
rpmautospec is shown briefly, but with enough information for normal
packaging workflows. Links are provided to the rpmautospec docs in
case packagers need more information.

ngompa commented on line 180 of guidelines/modules/ROOT/pages/index.adoc a year ago

Use example.com for the domain

rebased onto 4019447dad3e1fd6f288137dfb3fd70d293dd93c

a year ago

rebased onto c999163c821779ca52476b1a04395156fe14e983

a year ago

zbyszek commented a year ago

Updated with example.com everywhere and some spurious newlines removed.

churchyard commented on line 142 of guidelines/modules/ROOT/pages/Versioning.adoc a year ago

1{?dist} here is missing the % sign

1 new commit added

Adjust "Renaming or replacing" for rpmautospec

a year ago

rebased onto 82fbee70c968817414bef442589d0b44f81297eb

a year ago

zbyszek commented a year ago

1{?dist} here is missing the % sign

Fixed. I made the same error in other places, they are fixed now too.

oturpe commented a year ago

Ok, I read through the whole change set AND the resulting Versioning.adoc.
Thank you for your effort.
This looks good, but I also have multiple suggestions:

Release field
I would move this section right under section Epoch: tag.
So the simple tags would be handled first, followed by deep dive into Version:.
I would also prefer both Release and Epoch sections be named similarly
(so either switch to Release: tag or to Epoch field.)

Upstream has never chosen a version
Said section needs an update, too, since it talks about bumping Release.
Maybe just add When %autorelease is used, this happens automatically.?

Tables
I think section Complex versioning with a reasonable upstream would read better if column Full package NEVRA was changed to Version: field.
The RA part was a constant there already,
and with Rpmautospec by Default, it makes even less sense to include it.

The same goes for sections Complex versioning with non-sorting upstream post-release versions and Complex versioning with a pre- and post-release snapshots,
if the few rows where release is incremented are removed.
Having the Release part there does not bring much clarity there.
Perhaps it did when tilde and caret were not available?

Mixed mode
What is the purpose of the Mixed Mode section?
It seems to just describe the traditional way.
Either just remove it, or explain it more.

Also, Mixed mode refers to the Complex versioning section, which makes heavy use of tilde and caret.
They are not available in this context —
the higher level section is about what to do if an old EL version does not support them.

The links are also broken there. [[Section header]] is not a valid Asciidoc link.
Try xref:_section_header[Section header]].

You want to change an old branch without rebuilding the others
I think this would read better and communicate the same thing:

== Only an old branch needs a change

Sometimes, an older branch needs a fix, but the newer branches are fine.
For example, both F{PREVIOUSOSVER} and F{MAJOROSVER} are built from the same dist-git commit, and only F{PREVIOUSOSVER} needs a fix.
If only F{PREVIOUSOSVER} was changed, its `Release` would increase
and thus the E-V-R for F{PREVIOUSOSVER} would sort higher than E-V-R in F{MAJOROSVER}.
To avoid this situation, rebuild the package also in the later branches,
possibly with just an empty commit to make `%autorelease` bump the release.

If the package does not use `%autorelease`, it is also possible to adjust `Release` by appending a number after the dist tag, like `+7.%{?dist}.1+`.

Another section with almost identical name, You want to change an old branch without rebuilding the others, could also be removed, because the same content is here.

Suggestion to simply let older release sort higher than the newer ones is contradicted by section Rawhide is allowed to lag temporarily, so at least that suggestion must be removed.

Navigation
manual-changelogs.adoc should be added to nav.adoc.

Semantic linebreaks
They should be used everywhere.

Edited a year ago by oturpe

rebased onto 7762d489bb6fd0bb4a9f1142ff58a5e8dbf14dc0

a year ago

zbyszek commented a year ago

Thank you for the review. A detailed look like this is always very useful.

I updated the text with the suggested changes. Earlier I resisted to change the order (to Epoch-Release-Simple_versioning-Complex_versioning), but indeed it makes the structure much clearer. I edited all the tables to just have a Version column. I don't think it made much sense to have some like this and others with full N-V-R. But I added a short sentence that gives an example of a full N-V-R (without macros), so it's easier for the reader to visualize the effect.

nphilipp commented on line 106 of guidelines/modules/ROOT/pages/Versioning.adoc a year ago

I’d like the example to still have the same upstream version multiple times, probably mentioning that the release number will be bumped between them.

nphilipp commented on line 258 of guidelines/modules/ROOT/pages/Versioning.adoc a year ago

Do we still have the rule that E-V-R, F(N-1) must be smaller than E-V-R, F(N)? I thought not having that strict requirement was one argument to have the simplified release calculation algorithm.

nphilipp commented a year ago

Thanks for picking up the slack, @zbyszek! Can’t be said too often…

oturpe commented on line 250 of guidelines/modules/ROOT/pages/Versioning.adoc a year ago

Uh oh, my mistake, the version variables are actually called PREVVER, CURRENTVER and NEXTVER.
So wherever I suggested to use {PREVIOUSOSVER} should be {PREVVER},
and similarly {MAJOROSVER} should be {CURRENTVER}.

oturpe commented a year ago

Do we still have the rule that E-V-R, F(N-1) must be smaller than E-V-R, F(N)? I thought not having that strict requirement was one argument to have the simplified release calculation algorithm.

At least for Rawhide vs. branched releases, section Rawhide is allowed to lag temporarily only allows that in one specific situation.
I asked to change the wording here so that there would be no possibility of a conflict with that section.

Of course it may be that the rule has been removed, but Rawhide is allowed to lag temporarily has not been updated to match.

oturpe commented on line 2 of guidelines/modules/ROOT/pages/manual-changelogs.adoc a year ago

Just a tiny one here:
The file is called manual-changelogs, the nav entry says Manual Changelog, but the page title is just Manual Changelog.
Add the 's' to page title as well, or the other way round.

oturpe commented a year ago

And final comments about the Manual changelogs page:

I would add a link back to the main guidelines,
so that nobody will accidentally stumble on this page and miss %autochangelog completely:

This is an alternative for the recommended method with +%autochangelog+ described in xref:index.adoc#changelogs[Changelogs].

The first example (with Added README file (rhbz#1000042)) is out of place.
The paragraph describing it is gone, and the guidance for adding rhbz# tags is available in the main page.
So, I would just delete the example.

Sections for Multiple Changelog Entries per Release use the wrong header size.
They should be === to become subsections as they should be.

oturpe commented a year ago

That's it.
Apart from the minor items listed above, this looks great.
Thank you for taking the time to do this.

(In case anyone is wondering, I am reviewing this pull request because I am one of the change owners for Rpmautospec by Default.)

zbyszek commented a year ago

I’d like the example to still have the same upstream version multiple times, probably mentioning that the release number will be bumped between them.

It makes the table much more awkward. With %autorelease we don't have a fixed string for the dist tag, so it's harder to show. By splitting out the discussion of Version, the whole thing becomes much simpler: this table shows how to handle version, and the user knows that every rebuild gets the Release tag automatically as appropriate. I had to do a bit of mental adjustment to accept this, but this becomes natural once you accept that Version is the only part that the packager needs to think about in normal use.

Do we still have the rule that E-V-R, F(N-1) must be smaller than E-V-R, F(N)? I thought not having that strict requirement was one argument to have the simplified release calculation algorithm.

AFAIK, this requirement hasn't been rescinded.
I don't think this PR is the place to change this, so I just want to update the the existing text for %autorelease but not introduce a changed requirement. I think the current text (suggested by Otto), does a good job of this.

The file is called manual-changelogs, the nav entry says Manual Changelog, but the page title is just Manual Changelog.

I dropped "s" everywhere. I guess either way works.

Updated with the other suggestions.

rebased onto 6ab6ba0447e9b35fd3e66306af9e02e5561ffac1

a year ago

zbyszek commented a year ago

Any more comments?

churchyard commented a year ago

My notes for the changes of the Versioning guidelines:

The Epoch tag and the Release tag sections make me expect a Version tag section in the middle. Not a blocker, just a nudge.

Alternatively, the Release: field may be updated manually and contain parts of the upstream version information. See Traditional versioning with part of the upstream version information in the release field.

This makes me think using manual Release without parts of the upstream version is not allowed, which still should be allowed.

Only an old branch needs a change
...
To avoid this situation, rebuild the package also in the later branches,
possibly with just an empty commit to make %autorelease bump the release.

This seems illogical to me. Previously, we said "is a waste of time and energy for the newer branches which do not need to be touched" -- why has this changed?

If the package does not use %autorelease,
you may rebuild just the older branch,
see <<Rebuilds in older branches using <code><minorbump>>>.

So I am not allowed to do this with autorelease? That seems like a needless limitation to me.

Edited a year ago by churchyard

churchyard commented a year ago

My notes about the changes for the Changelog guidelines:

They must never simply contain an entire copy of the source CHANGELOG entries.

This has been removed and I'd like it to stay. Particularly packit does this and I hate it.

The changes for the Renaming/Replacing or Removing Existing Packages guidelines seem OK.

The Manual Changelog page seems to preserve all relevant information.

rebased onto a935859f496700e4ea35be806bae14c17f343acf

a year ago

zbyszek commented a year ago

The Epoch tag and the Release tag sections make me expect a Version tag section in the middle. Not a blocker, just a nudge.

I moved the Version following a request from an earlier review (https://pagure.io/packaging-committee/pull-request/1255#comment-184246). With %autorelease, the descriptions of Epoch and Release are very simple, and then there's a lengthy description of Version. I wasn't convinced at first, but the text is easier to read this way.

This makes me think using manual Release without parts of the upstream version is not allowed, which still should be allowed.

I removed that part of the sentence. The other section describes the other approach comprehensively, so it's better not to repeat anything here.

This seems illogical to me. Previously, we said "is a waste of time and energy for the newer branches which do not need to be touched" -- why has this changed?

Minor bumps are not really useful with %autorelease. The very first commit which adds the minor bump would also cause the release number to be bumped, which defeats the purpose. So the guidelines were simplified not to mention this case at all. If you need minor bumps, you're better off with using "Traditional versioning".

So I am not allowed to do this with autorelease? That seems like a needless limitation to me.

Yeah, it just doesn't work.

They must never simply contain an entire copy of the source CHANGELOG entries.

Now it's back. (You'd need to paste the CHANGELOG into the git commit message. Not an obvious thing to do, but I guess it could be done.)

Updated with those changes.

rebased onto b4d762017a289a6dc497a0ce2b0aba20f8315373

a year ago

zbyszek commented a year ago

I rebased the PR to fix a conflict with #1258.

After talking this over with @churchyard, I added one more patch to remove the subsection "Only an old branch needs a change". See the commit for a longer explanation. In short, we have a disagreement how to handle this case, so let's leave this not documented for now, and work out some solution later.

churchyard commented a year ago

tibbs commented on line 52 of guidelines/modules/ROOT/pages/Versioning.adoc a year ago

Just a note that the last time I was in this document, I took great pains to avoid using the word "release" when discussing anything not related to the Release: tag. I thought it best to avoid any possibility of confusion. It's obvious that something was missing from the original, but maybe we could just say "Use the upstream version verbatim ...".

tibbs commented a year ago

Besides that one minor comment (which I believe applies to one other line in the document) I also want to point out that we have macros NEXTVER, CURRENTVER and PREVVER which we will update occasionally that can be used in example text to refer to a Fedora version without hardcoding something that makes the document look increasingly out of date as time passes. So instead of using "fc20" in various examples, which makes the document seem nearly a decade old, you could use fc{{CURRENTVER}} and then it gets updated whenever we remember to update the macros.

Both of my comments are minor, and something we could easily do post-merge. +1 from me.

zbyszek commented a year ago

Thank you for the review. Updates:

"upstream release version" changed to "upstream project version" in the new text
fc{CURRENTVER} is now used the versioning examples. I was aware of the macro, but when I generate the page locally, it isn't substituted correctly, and I avoided using it code snippets. But it is used in this way in DistTag page, so I now use the same formatting as there and hope that it'll render correctly.
I dropped a change from << >> to xref: that was requested earlier (https://pagure.io/packaging-committee/pull-request/1255#comment-184246). It seems that this is another case that does not render correctly in the local preview, but somehow works in the online build.

zbyszek commented a year ago

… and rebased.

rebased onto 67b6169

a year ago

oturpe commented a year ago

Most probably such problems with attribute substitution and << >> cross references can be fixed by moving to use the latest Fedora Docs tooling from Documentation Template.
The tooling used by Packaging Guidelines is either very old, or custom, or both and suffers from already fixed bugs like these.

Edited a year ago by oturpe

zbyszek commented a year ago

It's been 6 weeks since the last substantial change. All feedback has been addressed. Miro and Tibbs were +1, and other non-fpc folks too. Are we waiting for something?