Conary:Redirect Package Policy

From rPath Wiki

Building Redirects

When you want to rename a package (for instance, because the upstream name has changed), or move package maintenance from one repository (or branch) to another, use a redirect. A redirect allows users with the old version installed to follow the movement of the package to the new version that continues to be maintained. The main purpose of this document is to describe the recommended procedure for creating redirects.

The general procedure is a bit different depending on whether you are changing the name or moving repositories, but most of the steps are the same.

First, you need to create the package to which you will be redirecting, including cooking it. When possible, you should consider shadowing to the new repository rather than starting over, just to preserve the information about the package heritage:

cvc shadow newlabel packagename:source=oldlabel
cvc checkout packagename=newlabel

Alternatively, you will want to create the new package and copy the existing recipe over:

cvc newpkg packagename[=newlabel]
cd packagename
cp .../path/to/oldpackage/oldpackagename.recipe packagename.recipe
cvc add packagename.recipe
$EDITOR packagename.recipe

Update anything you need to, including the name if it has changed, and commit:

cvc commit

Cook the new package into the repository; the binary troves must exist for the redirect to work:

cvc cook packagename[=newlabel]

Redirecting to a Package

Now that the new package exists, you can redirect to it.

You might want to save the old recipe, so that if the redirection is removed later, revision history from before the redirect is preserved:

cvc rename oldpackagename.recipe oldpackagename.recipe.preredirect

Now, replace the recipe with a redirect recipe:

class OldPackageName(RedirectRecipe):
    name = 'oldpackagename'
    version = '0'
    def setup(r):
        r.addRedirect('packagename', 'destination')

Note that 'destination' can be a branch or a label, but not a specific version.

We use the version number '0' by convention for redirects, because it makes them pretty obvious in an update message. It's not required, but it has proven useful already.

Now add the new recipe file and test-cook your redirection:

cvc add oldpackagename.recipe
cvc cook oldpackagename.recipe

Make sure that you get the redirection that you intended, and if so, commit and cook the redirection:

cvc commit
cvc cook oldpackagename

Handling Redirect with PackageSpec

If the old recipe used PackageSpec to create multiple packages from one source component, you will need to redirect both old packages.

class OldPackageName(RedirectRecipe):
    name = 'oldpackagename'
    version = '0'

    def setup(r):
        r.addRedirect('newpackagename', 'destination')
        r.addRedirect('newotherpackagename', 'destination',
                       fromTrove='oldotherpackagename')

Redirecting to Nothing

In some instances it may be advisable to redirect to a non-existent package to remove a package from the system. Times when this is necessary may be when a package has been removed or deprecated completely from a repository. Use this type of redirect when retiring a package from a repository or when a package is no longer maintained. Using this redirect allows for shadows not to break. In these instances, use the r.addRemoveRedirect variable:

class OldPackageName(RedirectRecipe):
    name = 'oldpackagename'
    version = '0'

    def setup(r):
        r.addRemoveRedirect()

In this instance the redirect recipe will remove the package from a system if that system contains a version of the package setup after the original redirect recipe was committed. If the package version came before the original redirect recipe was committed it will remain unaffected. The r.addRemoveRedirect variable is useful when depreciating a package out of use by removing post redirect versions of packages and not allowing new installations and/or upgrades.

After completion of your r.addRemoveRedirect recipe, recook and commit to your repository to allow its use.

Group Redirects

A group redirect recipe is a way to point existing users to a completely different set of groups on a (possibly) different label. It can be used for major version updates (for example: updates.example.com@ex:product-3 -> updates.example.com@ex:product-4).

class GroupProductDist(RedirectRecipe):
    name = 'group-product-dist'
    version = '0'

    def setup(r):
        for x in ['group-product', 'group-product-core', 'group-product-dist']:
            r.addRedirect(x, 'updates.example.com@ex:product-4', fromTrove = x)

This example assumes multiple groups making up one appliance. The top-level group is group-product-dist, which in turn contains group-product and group-product-core. All three groups are then redirected to the same group name on the new label: updates.example.com@ex:product-4. Any user updating their system, currently on @ex:product-3, will be automatically redirected to the new groups on the new label when upgrading or installing.