From 67b6169de975be0fa5a69dcfe4069889bff2259d Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 08 2023 09:15:00 +0000 Subject: [PATCH 1/3] Adjust guidelines for %autorelease+%autochangelog 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. --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 2e11852..49bfab1 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -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] diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index 4fc178a..b4e7b7e 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -9,6 +9,9 @@ The overriding goal is to provide sequences of packages 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 @@ non-sorting version sequence:: 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 @@ when necessary to avoid ordering issues. 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 @@ and the vast majority of software projects use something which works like this. 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 @@ in a particular situation: * 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 @@ you **must** use `+Version: 0+`. "`+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,136 @@ $ rpmdev-vercmp 2~almost^post 2.0.1 [%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 '`+.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 '`+.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}`. + +== Only an old branch needs a change + +Sometimes, an older branch needs a fix, but the newer branches are fine. +For example, both F{PREVVER} and F{CURRENTVER} are built from the same dist-git commit, +and only F{PREVVER} needs a fix. +If only F{PREVVER} was changed, its `Release` would increase +and thus the E-V-R for F{PREVVER} would sort higher than E-V-R in F{CURRENTVER}. +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`, +you **may** rebuild just the older branch, +see <`>>. -== 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 <> 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 +423,7 @@ in the use of `++` or `++`, and in most situations `++` 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 +495,17 @@ and increasing for each revision of the package. Release and post-release versions **must** use a `+Release:+` tag greater than or equal to 1. +=== Rebuilds in older branches using `` + +In the situation described in <>, +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 `++` to an in integer beginning with '1' +and increase it by one for each minor bump you need to do. +Remove `++` 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 +513,6 @@ are available from 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 `++` -to an in integer beginning with '1' -and increasing by one for each minor bump you need to do. -Remove `++` 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 diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 09f6e51..0d10914 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1096,133 +1096,101 @@ to remind maintainers to update the separate *-doc package when needed. [#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 - 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 - 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 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 -- 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] ----- -%changelog -* Nov 12 2010 Toshio Kuratomi - 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 - 1.0-1 -- Fix spelling errors in package description -- Add a patch to fix compilation problems on F15 +[console] ---- +$ git show +commit 0000000000001234567890ABCDEF000000000000 +Author: Joe Packager +Date: Wed Jun 14 2003 -Please remember that this is only acceptable if 1.0-1 has not yet been built. + Version 1.0 -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 <>. + ... (rhbz#1000024) + - Also fixes the slowdown reported in rhbz#1000025 + - Upstream changelog: https://example.com/package/NEWS.html#v1.0 -==== Repeat the old version release with a new entry + Whitespace in the spec file has been cleaned up. -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 - 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 - 1.0-1 -- Add a patch to fix compilation problems on F15 - -* Nov 12 2010 Toshio Kuratomi - 1.0-1 -- Fix spelling errors in package description +$ rpmautospec generate-changelog +* Wed Jun 14 2003 Joe Packager - 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 <>. == Manpages diff --git a/guidelines/modules/ROOT/pages/manual-changelog.adoc b/guidelines/modules/ROOT/pages/manual-changelog.adoc new file mode 100644 index 0000000..45f7def --- /dev/null +++ b/guidelines/modules/ROOT/pages/manual-changelog.adoc @@ -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 - 0.6-4 +- And fix the link syntax. +---- + +[source, rpm-spec] +---- +%changelog +* Fri Jun 23 2006 Jesse Keating 0.6-4 +- And fix the link syntax. +---- + +[source, rpm-spec] +---- +%changelog +* Fri Jun 23 2006 Jesse Keating +- 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 - 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 - 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 - 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 - 1.0-1 +- Add a patch to fix compilation problems on F15 + +* Nov 12 2010 Toshio Kuratomi - 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]. From 0cd555fc6e4eb3343297fa7223dd71188a8dc1bb Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 08 2023 09:15:00 +0000 Subject: [PATCH 2/3] Adjust "Renaming or replacing" for rpmautospec When rpmautospec is used, %{dist} is not directly visible to the maintainer, so adjust the text to use ".fcNN" instead, which is what the maintainer will see when %autorelease is expanded. With this adjustment, the text should apply to both %autorelease and traditional release handling. Also, add a note to point the maintainer to 'rpmautospec calculate-release'. Change '<=' to '<' in one more place: '<=' is just confusing, because equality generally cannot be achieved because of %{dist} and the operator was changed to '<' in most places, but apparently forgotten here. Addresses https://pagure.io/fedora-infra/rpmautospec/issue/225. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 0d10914..b004ae3 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2923,7 +2923,7 @@ the new package should make the change transparent to end users 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: @@ -2952,10 +2952,14 @@ use only the `+Obsoletes:+` line from the above example. 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 @@ -2972,14 +2976,15 @@ If the obsoleted package had an Epoch set, 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 From 3db83e48d5bd7d52a7f8a28601895c61f67048c2 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 08 2023 09:15:00 +0000 Subject: [PATCH 3/3] Drop discussion of builds in older branches with %autorelease There is a disagreement how to proceed with "rebuilds in older branches": - rpmautospec does not really support adding a minor bump. ('%{autorelease -b 0}.' sets the Release correctly, but %autochangelog is generated as if '-b' was not set, so the release fields disagree.) - But even if it could be made to work, it is quite inconvenient, so it's not clear if is worth the trouble. (In my opinion — no.) - We could either ask people to rebuild, - Or we could remove the requirement to have a higher version-release in later releases, - Or we could tweak that rul to only require a higher version, but allow a lower release. If we do this, we might want to adjust tooling to only warn about version downgrades, but silently allow release downgrades. A quick check using 'dnf repoquery' shows that there are packages using minorbumps, but it also seems that the majority are doing that in error: $ dnf repoquery --releasever=37 --qf '%{name}-%{version}-%{release}' \ '--disablerepo=*' '--enablerepo=updates-source' '--enablerepo=fedora-source' \ --arch=src | rg 'fc37.\d' | wc -l 96 $ dnf repoquery --releasever=37 --qf '%{name}-%{version}-%{release}' \ '--disablerepo=*' '--enablerepo=updates-source' '--enablerepo=fedora-source' \ --arch=src | rg 'fc38.\d' | wc -l 83 Considering that F38 hasn't been released yet, those 83 packages should not be using minorbumps. So there's probably ≤13 packages in F37 using a minorbump as intended. So let's remove this subsection for now, so that the other part of the changes can be merged, and discuss how to handle this case separately. --- diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index b4e7b7e..5ed52c0 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -370,20 +370,6 @@ In this case the full N-V-R could be e.g. `pkg-1.1.0.20210105.SP1_CP1-1.fc{CURRE In this case the full N-V-R could be e.g. `pkg-1.0.1.security1^20210301gabc0202-1.fc{CURRENTVER}`. -== Only an old branch needs a change - -Sometimes, an older branch needs a fix, but the newer branches are fine. -For example, both F{PREVVER} and F{CURRENTVER} are built from the same dist-git commit, -and only F{PREVVER} needs a fix. -If only F{PREVVER} was changed, its `Release` would increase -and thus the E-V-R for F{PREVVER} would sort higher than E-V-R in F{CURRENTVER}. -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`, -you **may** rebuild just the older branch, -see <`>>. - [#traditional-versioning] == Traditional versioning with part of the upstream version information in the Release field