package-maintainer-docs/modules/ROOT/pages/Package_Retirement_Process.adoc

= Package Retirement Process

When a package reaches the end of its useful life,
the Package Retirement Process lets other people
— and automated processes! —
know both not to expect any more releases,
and why it was removed.
The process is governed by https://docs.fedoraproject.org/en-US/fesco/Policy_for_orphan_and_retired_packages/[Policy for Orphan and Retired Packages].

[#what_can_be_retired]
== What can be retired ==

Packages can normally only be retired in the following branches:

* Branched (until the Final Freeze)
* Rawhide
* EPEL branches (epel7, epel8)

== Procedure

Please execute the following steps in the order indicated.

=== RPM

If the package is being replaced by some other package,
ensure that the `Obsoletes`/`Provides` tags are properly set by the new package
as specified in https://docs.fedoraproject.org/en-US/packaging-guidelines/#renaming-or-replacing-existing-packages[Renaming/Replacing Guidelines].

=== Git

Run `fedpkg retire DESCRIPTION`
in Fedora branches Rawhide and Branched (if it exists at the moment)
and all EPEL branches (if applicable).
`DESCRIPTION` should explain why the package was retired.
Examples of good messages are _Obsoleted by bar_ and _Renamed to bar_.

The command will remove all files from the branch,
add a file name `dead.package` containing the description
and push the changes.

Do not run the command in any supported or end-of-life Fedora release branch.
Packages must not be retired from stable releases.

Start retiring from  the oldest branch,
i.e. retire on Branched before you retire on Rawhide.
If you retire Rawhide before Branched,
it will still work, but will block the package in more Koji tags,
because tag inheritance will not be used automatically then.

=== Comps

Remove the package from https://fedoraproject.org/wiki/How_to_use_and_edit_comps.xml_for_package_groups[comps] if it is listed.

=== Spins

Remove the package from any https://pagure.io/fedora-kickstarts[spin kickstart file].

[#upstream_release_monitoring]
=== Upstream Release Monitoring

Remove the package from xref:Upstream_Release_Monitoring.adoc[Upstream release monitoring] if it is listed.

=== Koji

To keep retired packages from being pushed to the mirrors,
they need to be blocked in Koji.
This will happen automatically during the next compose
(for rawhide, the branched release and for EPEL).

You can check whether a package is blocked in koji
with `koji list-pkgs --show-blocked`.
There should an entry with `[BLOCKED]`
for each branch the package was retired in.
It is enough for a package to be blocked in an older tag
to be also blocked in a newer tag
due to inheritance. Example output:

....
$ koji list-pkgs  --show-blocked --tag f21 --package curry
Package                 Tag                     Extra Arches     Owner
----------------------- ----------------------- ---------------- ---------------
curry                   f20                                      gemi            [BLOCKED]
....

Please wait for two days to allow for a compose to happen
and mirrors to be updated.
If the package is not blocked automatically after two days,
please file a https://pagure.io/releng/new_issue[ticket for release engineering]
and mention package names
and the branches where the packages need to be blocked.
Use only one ticket for all the packages you retired at once,
do not open one ticket for each package if you retired several packages.

== EPEL

The retirement process can be used for EPEL as well
with one difference:

* You can remove the package from any EPEL branch
whether or not it has been released.

For example, if your package has been added to base RHEL in RHEL-6.4
then perform the steps above
but use the `el6` branch instead of `rawhide`.

When you need to add package from EPEL to any RHEL release,
only retire EPEL branch when package is released in that RHEL release.

[#claiming]
== Claiming Ownership of a Retired Package

If you really want to maintain a retired package,
you need to be aware that if upstream is dead,
fixing release critical bugs, etc
becomes your responsibility.
This is to ensure the high quality and standards of packaging
remain for Fedora package collection.
There may be additional issues with retired packages.
If possible, consult with the former maintainer for more information.
The process is a bit different from unorphaning a package.

. See if you can figure out why the package was retired
including searching for information about orphaned packages on https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel mailing list]
or emailing the former maintainer.
You can also check `dead.package` in the SCM
(url like: https://src.fedoraproject.org/rpms/system-config-network/blob/rawhide/f/dead.package[https://src.fedoraproject.org/rpms/**package_name_here**/blob/rawhide/f/dead.package])

. Announce on https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel]
which packages you would like to become the owner of.

. Retired Fedora packages (rawhide branch retired) require a re-review
if they are retired for more than eight weeks
or if there is no previous review of the package.
Submit a review request (a new bugzilla ticket)
and have the package approved by a reviewer
as if it were new to Fedora.
See the xref:Package_Review_Process.adoc[Package Review Process] for more information.
To unretire a EPEL branch if the package is still in Fedora,
no re-review is required.

. Request unretirement by filing a https://pagure.io/releng/new_issue?template=package_unretirement&title=Unretire%20%3Cpkgname%3E[releng ticket].
Specify all branches that need to be un-retired
(including `rawhide` for Rawhide, unless it is for EPEL only)
and include the link to re-review.
In this ticket,
request that the https://docs.pagure.org/releng/[Release Engineering team] unblock the package
for the releases that the package should be un-retired for.
In this request,
clearly specify which branches should be unblocked.

. Restore the contents in Git and prepare a new build and update (if necessary).

[#obsoleting_packages]
== Obsoleting Packages

While not strictly part of the process,
please consider what will happen
to systems which have the now-retired packages installed.
Generally, such packages will simply remain on the system as it is updated,
becoming increasingly outdated.

Please consider adding your package to https://src.fedoraproject.org/rpms/fedora-obsolete-packages/[fedora-obsolete-packages]
if there are upgrade path issues or security concerns.

Please follow https://docs.fedoraproject.org/en-US/packaging-guidelines/#renaming-or-replacing-existing-packages[the relevant packaging guidelines]
if another package will be providing
similar or identical functionality to the retired package,
or if it is necessary that the package be removed from end-user systems
on system updates.

[#complete_removal]
== Completely Removing a Package

In rare cases, such as when licensing issues are discovered,
it may be necessary to completely remove a package from Fedora.
This differs from normal retirement
in that the package is removed also from stable and end-of-life releases.

For complete removal, first follow the xref:Procedure[procedure for normal removal].

Additionally, retire the package in '''all''' dist-git branches.
Since `fedpkg retire` refuses to work on stable branches,
simulate it with the following:
....
$ DESC="my description"; git rm -r . && echo "$DESC" > dead.package && git add dead.package && git commit -m "$DESC"
....

Finally, add the package to fedora-obsolete-packages.