Appliance Development:Release Management

From rPath Wiki

  APPLIANCE DEVELOPMENT

Release management is an established protocol used when creating and developing products, stepping through product development stages, releasing a product, and maintaining the product between releases. This page describes rPath's recommended release management strategy for Conary-based appliance products.

This strategy assumes that appliance development is centered on rPath's rBuilder product.

Define a New Product

Corporations should define a new project in rBuilder to correspond with the development of a new appliance product. This creates a repository for the packages and groups associated specifically with that product.

Not all packages and groups in a product needs to originate or even exist in the product repository to be included in the final product. For example, packages included as they exist in rPath Linux can be obtained directly from rPath's repositories when the appliance is built. This eliminates the need for identical copies of such packages the appliance product's repository.

Note that a repository is identified by a fully qualified domain name (FQDN) on the system on which it resides. In rBuilder, this FQDN incorporates the project name (projectname.example.com). Conary refers to this as the repository hostname.

Example Corporation created an rBuilder project for its EDB product that resulted in a repository hostname of edb.example.com.

Define Labels for Products and Stages

A Conary version string is part of the identity of each trove (identifiable unit) in a Conary repository, such as a package or group. A version string identifies the repository, branch, and revision information required for Conary updates.

A label in a version string identifies a particular branch in a particular repository. When a version string includes multiple labels, the last label listed is the one on which the trove resides. A single repository can use as many labels as necessary for its release management structure.

In release management, rPath recommends customizing such labels to identify the corporation, the product, the product version, and the stage of product development. These custom labels apply specifically to the contents in a product's repository, not to the contents from other repositories used in building the appliance product.

Each label consists of the following parts, separated by the @ symbol:

• The repository hostname associated with the project
• The branch name in the project's repository

One label used by Example Corporation for its EDB product is edb.example.com@excorp:edb-1-devel.

Each branch name consists of the following parts, separated by a colon:

• The namespace, usually a string identifying a corporation
• The tag, identifying the product, its version, and the stage of development

The branch name used in the previous example is excorp:edb-1-devel.

rPath recommends defining labels to match the product's release management structure. Use the following guidelines:

1. Select a string to represent the corporation, and use this as the namespace
   excorp in the example
2. Select a string to represent the product, and use this to start each tag
   edb in the example
3. Select a string to represent the version associated with the appliance product
   1 in the example, to be the first release of the appliance
4. Select a string (or absence of a string) to represent each stage in the release management process for the appliance
   devel in the example, to identify this as the development stage for this version of the appliance

Example Corporation has identified the following labels to correspond with its stages for the EDB product:

• edb.example.com@excorp:edb-1-devel for version 1 development
• edb.example.com@excorp:edb-1-test for version 1 quality assurance testing
• edb.example.com@excorp:edb-1-release for version 1 release

Example Corporation increments the version number in the label when repeating these three stages for each version.

Corporations may choose to imitate rPath Linux releases by eliminating the stage string entirely on the release label, leaving just the product and version. In the example, this would mean using the branch name excorp:edb-1 instead of excorp:edb-1-release.

Inform Packagers of Contexts

Packagers working on the appliance project must have a context for each label to which they commit packages and groups. Inform packagers of the labels to be associated with each appliance product, and ensure they follow the release management plan at each stage.

Corporations should ensure each packager working on a product has the rBuilder credentials necessary to commit to the product's labels.

Commit to a Label

Packagers should commit packages to a label only if the package is created or modified specifically for that label. Note the following guidelines:

• If a package is created for the label, it can be committed directly to that label.
• If the package requires appliance-specific modifications, packagers can shadow the package from a different label (such as from an rPath Linux release) and modify the package as needed.
• If the package exists on a different label and needs no modifications, the appliance should obtain the package from that label. Packagers do not need a redundant copy on the appliance product's label.

Corporations can choose to have packagers commit all changes to a development stage label only, or they can plan what kinds of changes can be committed to labels at various release management stages.

Promote from Stage to Stage

rPath recommends using Conary's promote operation to clone troves from one label to another. In release management, this means promoting from one stage of development to another. This operation can be performed by a single Conary command: cvc promote. When a group is promoted, all packages on the same label required to build that group are promoted, too.

Example Corporation used the following command to promote its top-level appliance group, group-edb, from edb.example.com@excorp:edb-1-devel to edb.example.com@excorp:edb-1-test:

$> cvc promote group-edb edb.example.com@excorp:edb-1-devel--edb.example.com@excorp:edb-1-test

Because the promote occured in the same repository and in the same namespace, Example Corporation could have abbreviated the command as follows:

$> cvc promote group-edb :edb-1-devel--:edb-1-test

Furthermore, because the package edb used in group-edb was also on edb.example.com@excorp:edb-1-devel, Conary located the package and promoted it to the new label.

Release a Product

rPath recommends using rBuilder or rPath Appliance Platform Update Service to distribute a product release, and using rPath Appliance Platform Entitlement Service to manage access to release labels. Use instructions for the corresponding products to configure public access to release labels.

After successfully completing testing on version 1 of the EDB appliance, Example Corporation promoted the appliance group to its release label edb.example.com@excorp:edb-1-release. They followed this by enabling mirroring of this label to a publicly-facing Update Service appliance.

Promote to Start a New Version

rPath recommends promoting troves from the label of a released version to start the development of a new version. Example Corporation performed the following promote to start the development of version 2 of the EDB appliance:

$> cvc promote group-edb :edb-1-release--:edb-2-devel

After promoting, update the group recipe as necessary to search the appropriate labels for resources. One alternative to modifying the group recipe after each new version promote is to include conary.versions and a conditional in the group recipe to set a variable to use for the setLabelPath. The code for should resemble the following:

import conary.versions
if isinstance(r.labelPath[0], conary.versions.Label):
         myLabel = str(r.labelPath[0])
else:
         myLabel = str(r.labelPath[0].trailingLabel())

r.setLabelPath(myLabel)

Some corporations may choose to implement a versionless "devel" stage as a trunk for all development that is not specific to any one version of the appliance. Corporations using this option can shadow troves from the trunk to each versioned development branch.