Skip to content

autorelease.rst

Latest commit

 

History

History
203 lines (123 loc) · 6.62 KB

autorelease.rst

File metadata and controls

203 lines (123 loc) · 6.62 KB
Raw

The %autorelease Macro

The contents of the Release field

Fedora's Versioning Guidelines define the different elements of which a release field consists. They are as follows:

<pkgrel>%{?dist}[.<minorbump>]

Square brackets indicate an optional item.

The %autorelease macro accepts these parameters to allow packagers to specify the different portions of the release field:

  • -b <baserelease>: Allows specifying a custom base release number (the default is 1).

    For instance, this can be used to keep release numbers on older Fedora releases way lower than on newer ones for the same package version.

  • -r <minorbump>: Allows specifying a custom rightmost (minor) release number (the default is 0).

    This is only used when previous commit contained [start rightmost] line or rightmost number is greater than 0. This provides a different way to ensure release stays lower on older Fedora releases. Rightmost bumps can be started by explicit %autorelease -r 1.

  • -n: Don’t render the dist tag, e.g. for use in macros, if the dist tag is added later.

Important

To date, the %autorelease parameters are ignored in the headers of automatically generated changelog entries.

Note

In the prototype version the macro was named %autorel. To make its purpose more obvious, it is %autorelease now.

One-off bumping release numbers

You can bump the release to a higher value in a commit by adding a magic comment like this to the commit log (on its own line):

[bump release: <number>]

This would ensure that the release number is at minimum the specified number (if it were higher anyway, it would not change anything).

One use case for this would be, if a sub-package is split out into its own component and its release number sequence should not be reset. E.g. if the last release number while it was still a sub-package was 4, add [bump release: 5] to the commit log to let the sequence continue seamlessly.

You don’t have to undo this later, when the version changes, the release will be reset to 1 (or the value specified by %autorelease -b …).

Rightmost minor release numbers

You can also continue doing only rightmost bumps. Easiest way is to use magic comment in commit:

[start rightmost]

This would freeze current release number and increment separate number on the right of release.

Use case for this would be for multiple supported branches, which contain equivalent changes. Example might be rebased version in multiple branches. But latest branch build should be considered latest, even if older stable branch contained more commits modifying spec file. Stable branch can use this magic comment to be always lower than development branch like rawhide.

This provides similar functionality to rpmdev-bumpspec -r tool, but generated from commit messages.

Rightmost bumping release numbers

You can bump also the rightmost number to a higher value. Similar to bump release magic comment, you can bump rightmost number to a higher value.:

[bump rightmost: <number>]

This will start rightmost bumps if not yet started already. Sometimes it might be needed to start different number than trailing .1 on right side of the release.

Alternative to this commit line is using %autorelease -r …. You don't have to undo this later, it will reset to 1 when version or release number changes.

Examples

Example: The Simple Case

.. literalinclude:: examples/test-autorelease.spec
   :language: spec

Will generate the following NEVR:

test-autorelease-1.0-1.fc34.x86_64

Example: The Custom Base Release Case

.. literalinclude:: examples/test-autorelease-baserelease.spec
   :language: spec

Will generate the following NEVR:

test-autorelease-baserelease-1.0-100.fc34.x86_64

Traditional versioning with part of the upstream version information in the release field

Additional parameters are available to support an older form of package versioning. This form is recommended for packages with complex versioning requirements when support for RHEL7 and other systems with old rpm versions is required. See Traditional Versioning in the Packaging Guidelines for details.

The release field is extended:

<pkgrel>[.<extraver>][.<snapinfo>]%{?dist}[.<minorbump>]

Square brackets indicate an optional item.

The %autorelease macro accepts these parameters to allow packagers to specify those added fields:

  • -p: Designates a pre-release, i.e. pkgrel will be prefixed with 0..
  • -e <extraver>: Allows specifying the extraver portion of the release.
  • -s <snapinfo>: Allows specifying the snapinfo portion of the release.
  • -r <minorbase>: Allows specifying the minorbump portion of the release.

In the modern versioning, those fields are embedded in the package Version instead.

Example: The Pre-Release Case

.. literalinclude:: examples/test-autorelease-prerelease.spec
   :language: spec

Will generate the following NEVR:

test-autorelease-prerelease-1.0-0.1.pre1.fc34.x86_64

Example: The Extraver Case

.. literalinclude:: examples/test-autorelease-extraver.spec
   :language: spec

Will generate the following NEVR:

test-autorelease-extraver-1.0-1.pre1.fc34.x86_64

Example: The Snapshot Case

.. literalinclude:: examples/test-autorelease-snapshot.spec
   :language: spec

Will generate the following NEVR:

test-autorelease-snapshot-1.0-1.20200317git1234abcd.fc34.x86_64

Example: The Snapshot and Extraver case

.. literalinclude:: examples/test-autorelease-extraver-snapshot.spec
   :language: spec

Will generate the following NEVR:

test-autorelease-extraver-snapshot-1.0-1.pre1.20200317git1234abcd.fc34.x86_64