https://fedoraproject.org/wiki/Changes/Rpmautospec_by_Default
This document represents a proposed Change. As part of the Changes
process, proposals are publicly announced in order to receive
community feedback. This proposal will only be implemented if approved
by the Fedora Engineering Steering Committee.
== Summary ==
Rpmautospec (`%autorelease` and `%autochangelog`) is recommended as
the default approach.
Packaging Guidelines and other documentation are adjusted to describe
this approach first.
Various tools that provide spec file templates are adjusted.
== Owner ==
* Name: [[User:Nphilipp| Nils Philippsen]], [[User:Zbyszek| Zbigniew
Jędrzejewski-Szmek]]
* Email: nphilipp - at - redhat.com, zbyszek - at - in.waw.pl
== Detailed Description ==
{{admon/note|Brief reminder about rpmautospec|
The spec file contains:
<pre>
Version: 1.2.3
Release: %autorelease
...
%changelog
%autochangelog
</pre>
Rpmautospec uses git history. Whenever the package is built
(`.src.rpm` is generated), rpmautospec tooling will replace the
`%autorelease` macro with the number of commits since the last commit
that changed the `Version` field, and the `%autochangelog` macro with
a text generated from `git log`.
For details see the
[https://docs.pagure.org/fedora-infra.rpmautospec/principle.html
docs].
}}
Rpmautospec has been deployed in Fedora since F35
([[Changes/rpmautospec]]), and 3423/23045 packages use it (15%).
But it is still a "second-class citizen": most documentation doesn't
mention it, and many packagers know that it exists but don't use it in
their packages. We think that it's reasonable to switch to
`%autorelease`+`%autochangelog` for almost all packages and that
Packaging Guidelines and various packaging howtos should recommend
that approach to packagers. The "traditional" approach of
manually-managed `Release` and `%changelog` will remain valid and will
be documented as a fallback.
This change is targeted at Fedora 38, but it will actually apply to
all releases. The goal is to update the Packaging Guidelines and other
prominent documentation and tools now, and other docs and tools
possibly at a later time. Changing packages is out of scope.
It is worth mentioning that `rust2rpm` uses
`%autorelease`+`%autochangelog` since a few releases, so most rust
packages have switched. (Generally, rust spec files are recreated
using the generator for each new version, so the switch would happen
whenever a new version is packaged unless the packager opts out.)
== Feedback ==
* Thread on fedora-devel in August 2022:
[https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/T6J2WGIMRCTW77QTH4D7HPNS6KUGDQOQ/
rpmautospec by default]
** open issues: a bunch have been fixed.
** maintenance: Nils will add some co-maintainers.
** compatibility with rpmdevtools, fedpkg/rpkg, fedora-review: see
Scope section.
== Benefit to Fedora ==
Various packaging workflows become smoother for packagers and contributors:
* packagers don't need to touch the `Release` field on updates
* packagers describe changes just once in the git commit message, the
`%changelog` entry is autogenerated
* patches to the spec file can be cherry-picked between branches
without trivial conflicts
* pull requests on src.fedoraproject.org can be merged without trivial conflicts
* in workflows that regenerate the spec file (rust2rpm, pip2rpm, …)
`%changelog` section doesn't need to be copied over
== Scope ==
* Proposal owners:
** provide pull requests to Packaging Guidelines and other docs to
make `%autorelease`+`%autochangelog` the default
** implement fixes for issues reported by packagers
** make semi-regular releases of rpmautospec
([https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/K5EA5OGRX2BCZ353C7S4MQVZTSH2BH63/
0.3.1 was released on November 17th, and should be deployed to
production in about two weeks])
* Other developers:
** provide pull requests to other docs as appropriate
** accept the changes to documentation
** update other spec file generators (pip2rpm, others?)
* Somebody (TBD):
** `fedora-review` — https://pagure.io/rpkg/issue/641
** `fedpkg import` — with https://pagure.io/rpkg/c/3087dd7, the
command will fail. A replacement workflow that instead restores
`%autorelease`+`%autochangelog` in the file committed to dist-git
needs to be implemented.
* Related work
** https://pagure.io/rpkg/c/3087dd7
** https://src.fedoraproject.org/rpms/fedora-packager/pull-request/4
* Release engineering: [https://pagure.io/releng/issues #Releng issue number]
* Policies and guidelines: a list of places to be updated
** https://docs.fedoraproject.org/en-US/packaging-guidelines/#changelogs
** https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning
**
https://docs.fedoraproject.org/en-US/package-maintainers/Packaging_Tutorial_GNU_Hello/
* Trademark approval: N/A (not needed for this Change)
* Alignment with Objectives: N/A
== Upgrade/compatibility impact ==
Rpmautospec is already used by a decent number of packages, so any
issues are already being seen and need to be fixed anyway.
== How To Test ==
* Convert an existing package: `rpmautospec convert`. Ideally this
step is done right before a version bump so that the release numbers
restart at `-1`.
* Do local builds (`fedpkg local`, `fedpkg mockbuild`). Verify
correctness of version-release (`rpm -qpi`) and the changelog (`rpm
-qp --changelog`).
* Do builds in koji. Verify correctness of version-release and the changelog.
* For new packages, use `%autorelease`+`%autochangelog`. Repeat all
the tests listed above.
* Assume you are a newbie packager. Read the packaging docs and check
that the workflow is clear and the intructions are sufficient to use
rpmautospec tooling correctly.
== User Experience ==
No changes visible to end users.
== Dependencies ==
None.
== Contingency Plan ==
If it turns out that the rpmautospec workflows have unknown problems,
we can revert changes to documentation.
* Contingency mechanism: Revert changes to documentation by reverting
the appropriate commits. This can be done easily by FPC.
* Contingency deadline: Any time.
* Blocks release? No.
== Documentation ==
This page and any changes to Packaging Guidelines and other documents.
== Release Notes ==
Not needed.
--
Ben Cotton
He / Him / His
Fedora Program Manager
Red Hat
TZ=America/Indiana/Indianapolis
_______________________________________________
devel mailing list -- devel@lists.fedoraproject.org
To unsubscribe send an email to devel-le...@lists.fedoraproject.org
Fedora Code of Conduct:
https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives:
https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org
Do not reply to spam, report it:
https://pagure.io/fedora-infrastructure/new_issue
