This document will describe the process for transitioning from one package name to another package name. This process is called 'obsoletion' and is typically used to standardize naming conventions for packages while providing an easy upgrade path for users.
For our purposes, the term 'obsolete' means that we are retiring the CSWfoo package name in favour of one or more new CSWbar, CSWbaz, etc packages. User systems may have CSWfoo installed though, so to maintain clean dependencies we need to provide a new version of CSWfoo that depends on the newly created names. The obolete package will contain no files and exists only to make transition to the new names easier.
The catalogname of the stub package should be oldcatalogname_stub even if the new catalogname has been updated according to new policies (e.g. Perl modules).
Support in GAR already exists for this. To make a package CSWfoo obsolete CSWbar, simply define:
OBSOLETED_BY_CSWfoo = CSWbar
This makes a stub package (CSWbar / bar_stub) that has no files (save maybe a license) that depends on CSWfoo. The CSWbar package has, as part of it's prototype a definition of the form:
When this package is installed, it will provide the file /var/sadm/pkg/CSWbar/install/obsolete.
The obsolete File Format
The format for the obsolete file is straight forward. It is:
pkg_name catalog_name - catalog_description
CSWfoo foo - foo does something great
Where pkg_name is the CSWfoo, catalog_name would be foo and the catalog_description will match the description for CSWfoo. There may be multiple lines in this file as many sub packages might replace a single legacy package. This will be common when runtime (rt) packages are split.
The only two fields most tools will care about are the first two (package and catalog names).
Removal of Obsolete Packages
Package tools may sweep systems to remove any package that contains the obsolete file in it's /var/sadm/pkg directory. Care should be taken if the package in question is not a leaf node in the dependency chain although removing packages from the middle of the dependency graph won't actually break other installed packages.
# pkgutil --cleanup 1 OBSOLETE package: CSWpmnetssh2 1 package to remove. Do you want to continue? ([y],n,auto)