Build promotion use cases

Build promotion use cases
	Chapter 12. Use cases

Promote build from one configuration into another

Get artifacts of a tested build from QA configuration, optionally run some steps to re-arrange them, and put into a new build in the release configuration. The new build should take value of property next build version of the release configuration.

We'll use the configuration tree root.promotion-samples.product1 running at http://livedemo.pmease.com:8081 to demonstrate this use case. This configuration has two child configurations: QA and Release. You can make a try to see that successful builds in QA configuration can be promoted into Release configuration. We'll examine several key points below.
Change to basic settings tab of configuration root.promotion-samples.product1.QA, there is a section named promote destinations. It specifies root.promotion-samples.product1.Release as the destination configuration.

Change to repositories tab of the configuration root.promotion-samples.product1.Release. There defines a QuickBuild repository which pulls desired artifacts from the build being promoted, and put under the configuration's checkouts directory.

	Warning
	When define the QuickBuild repository to check out artifacts from source build, please make sure you've set a correct servlet URL (through administration -> system settings menu) for QuickBuild instance containing the source build.

Change to steps tab of the configuration root.promotion-samples.product1.Release. The default step runs two steps serially: one is used to checkout artifact from the promotion source, and another is used to publish artifacts from the configuration's checkouts directory into the build's artifacts directory.
In this way, build is able to be promoted from QA to Release. If you leave the promote as version property as blank when do the promote, version of the new build will be value of property "next build version" of the Release configuration.

This use case still works if the QA and Release configuration resides in different machines.

Promote build from one configuration into another and re-label the source code with new version

Get artifacts of a tested build from QA configuration, optionally run some steps to re-arrange them, and put into a new build in the release configuration. The new build should take value of property next build version of the release configuration, and create new release label on the source code.

We'll use the configuration tree root.promotion-samples.product2 running at http://livedemo.pmease.com:8081 to demonstrate this use case. Compared to the configurations used in last use case, the only difference is steps definition of root.promotion-sample.product2.Release. It contains three additional steps in order to re-label the source code:

check if "repository1" can be re-labeled

This step is optional, and is used to make sure that "repository1" exists in the source build and has already got a label. Otherwise, the step will fail, and can cause the whole build fail depending on step success condition of the default step.

	Note
	You should not check the label described in this step for Subversion and Perforce repositories, as QuickBuild can get the same set of source code to re-label even if they are not labeled previously. This is because QuickBuild uses the repository revision/change number (recorded automatically for each checkout) to re-produce the source code.

prepare source code for tag

This step is used to check out the same set of source code used by the source build. This is necessary in order to run the label step.

tag source code

This step is used to create new label on the checked out source code.

In this way, build is able to be promoted from QA to Release with the source code being re-labeled. Further, you can put QA and Release configuration at different machines, and the promotion process described here still works.
If you want to promote a promoted build in Release configuration into another configuration, and want to re-label the source code again, you need to make sure that repository1 is checked out (altough we don't use it) in Release configuration. However the label step in Release configuration is not necessary in order to get the source code being re-labeled by downstream configurations, as repository1 has already got label information in the QA configuration.
For this use case, if the repository is Subversion or Perforce, the label step in QA configuration will not be necessary, as QuickBuild records the repository revision (or change number for Perforce) for each checkout so that the same source code can be re-produced later. So you can promote and a build from nightly configuration to other configurations and re-label the source code even if the nightly build does not label the source code.

This use case still works if the QA and Release configuration resides in different machines.

Run additional steps to further process an existing build (for example, deploy an existing build)

Get artifacts of a particular build from configuration root.myproduct.test, and run additional steps to deploy them into another machine.

With some modifications, we can implement this use case using use case promote build from one configuration into another:

Replace configuration root.promotion-samples.product1.QA with configuration root.myproduct.test.
Replace configuration root.promotion-samples.product1.Release with a configuration created for the purpose of deployment, for example root.myproduct.deployment.
Edit configuration root.myproduct.deployment to include additional processing steps to deploy artifacts retrieved from the source build in configuration root.myproduct.test. The processing step can be implemented using step of type build which calls a builder to process artifacts.

This use case still works if the QA and Release configuration resides in different machines.

Promote build from one configuration into another by constructing the new build from the source code of source build.

Promote build from one configuration into another configuration. However, instead of retrieving artifacts from the source build, the promoted build should build artifacts from the same set of source code of source build.

We'll use the configuration tree root.promotion-samples.product3 running at http://livedemo.pmease.com:8081 to demonstrate this use case.
Repositories, builders and steps information are defined in configuration root.promotion-samples.product3 (this is not necessary for this use case, but will greatly simplify child configuration definitions).
The child configurations (QA and Release) contains the default step definitions. Compared to QA configuration, the default step of Release configuration includes an additional step "check if source build can be re-produced" which is used to fail the promoted build if repository1 does not exist in source build or does not have a label applied. step necessary condition gurantees that this step will not be run if current build is a not a promoted build.
For the same reason we put in use case Promote build from one configuration into another and re-label the source code with new version, the step "check if source build can be re-produced" is not necessary in case of Subversion or Perforce repository.

This use case still works if the QA and Release configuration resides in different machines.