h1. Upgrade from QuickBuild 1.x
h2. Migration procedure
# Login to QuickBuild 1.x as administrator, switch to page _Administration/Backup Database_, and backup the database as _backup.xml_ under QuickBuild 1.x's installation directory.
# Install QuickBuild2 following the [installation guide|Installation Guide]. Assume installation directory for QuickBuild2 server is _/opt/quickbuild2_.
# Open a command prompt window, switch to directory _/opt/quickbuild2/bin_, and run command _migrate.sh <QuickBuild 1.x installation directory>_ (or _migrate.bat_ on Windows). The param _<QuickBuild 1.x installation directory>_ should be replaced by the actual installation directory of
QuickBuild 1.x.
# After migration, please check the file _/opt/quickbuild2/migrate/migrate-log.html_ for all settings that can not be migrated and needs to be re-configured.
h2. Important changes that affect 1.x users
# Full name of configuration is now separated by character '/', instead of '.'. For example, to refer to configuration _project1_ defined under _root_, the name _root/project1_ should be used instead of _root.project1_.
# Everything defined in the configuration is now inheritable except for _name_ and _description_.
# Configuration settings such as build necessary condition, variables definitions, promote settings, build clean up strategies are placed into advanced settings tab.
# Expressions have been changed a lot. Due to complexity of expressions, we can only migrate default expressions that have not been changed by users. For customized expressions, please rewrite them based on the scripting help, which can be accessed by poining mouse to the help icon when edit related properties.
# By default only one promote destination can be defined now. However multiple promote destinations can be enabled by using variables and scripts as explained in help of property _configuration_ when defined the promotion setting.
# Promotion mechanism is simplified and a QuickBuild repository is no longer necessary in order to fetch files from promotion source. Instead, promotion files are specified when define the promotion settings of related configurations.
# The step type _Send Notification_ is now removed. To specify receivers and conditions of build notifications, please edit advanced settings of related configurations, and enable proper notifications.
# By default, configuration workspaces (previously named _configuration checkout_ directory) are created under the workspace sub directory under the configuration directory. However workspace directories of different configurations can be organized to match the configuration hierarchy with the help of scripting. To demonstrate this, assume we have below configuration hierarchy:
{code}
root
projectA
componentA1
componentA2
projectB
componentB1
componentB2
{code}
Now we need to place workspace of _root_ ocnfiguration under the directory _/workspaces/root_, and workspaces of other configuations should be created under directory _workspace/root_ matching the configuration hierarchy, that is, workspace of configuration _root/projectA_ should be _workspaces/root/projectA_, and workspace of configuration _root/projectA/componentA1_ should be _workspaces/root/projectA/componentA1_, and so on. To do this, just define workspace property of the root configuration as below:
{code}
${current.parent!=null?(current.parent.workspaceDir.absolutePath+"/"+name):"/workspace/root"}
{code}
# The _build cleanly_ option of configuration is removed since it is not flexible. Instead, each step can be configured to clean up the workspace conditionally (through the property _workspace cleanup condition_), and this gives user the flexibility of defining custom behavior of clean build. For example, if you have a checkout step checking out code at agent1, and deliver code to agent2 to build with a build step. You may want to define two build type:
*clean build*: workspace of agent running the build step needs to be cleaned up before running the step, while workspace of the agent running checkout step should remain untouched.
*increment build*: workspaces of both agents should remain untouched.
For scheduled builds, the increment build type should be used; for manual builds, a dialog should be presented to give user a chance to decide whether or not perform a clean build.
To accomplish this, define a configuration variable named _buildCleanly_ with the value being _false_, and set the _prompt setting_ of the variable as _checkbox_. Then define property _workspace cleanup condition_ of checkout step as _false_, and define the same property of build step as _vars.get("buildCleanly").booleanValue_.
In this way, you've defined your own notion of clean/increment build. You can even define three or more build types by using the _selection box_ prompt setting.
# By default QuickBuild does not prompt for build version when manually triggering a build. To get build version prompted, define a variable with prompt setting being _text input_, and reference value of this variable in _next build version_ property of the configuration like below:
{code}
vars.get("buildVersion")
{code}
Here _buildVersion_ refers to name of the variable defined above. Further more, value of the variable can be specified as:
{code}
version-prefix-${vars.get("nameOfBuildNumberVariable").increase()}
{code}
Then version of the build will be auto-increasing if user has not specified value of the variable or if the build is triggered by a scheduler.
# By default QuickBuild does not prompt for build version when promoting a build. However, version of resulting build can be controlled using almost the same techinque as specifying build version when manually triggers a build mentioned above, with the exception that the variable should be defined as a promotion variable in promotion setting section of the configuration. Specifically if you want to have the resulting build always has the same version as the promoted build, just set the variable as not prompted and specify value of the promote variable as:
{code}
${build.version}
{code}
h2. Migration procedure
# Login to QuickBuild 1.x as administrator, switch to page _Administration/Backup Database_, and backup the database as _backup.xml_ under QuickBuild 1.x's installation directory.
# Install QuickBuild2 following the [installation guide|Installation Guide]. Assume installation directory for QuickBuild2 server is _/opt/quickbuild2_.
# Open a command prompt window, switch to directory _/opt/quickbuild2/bin_, and run command _migrate.sh <QuickBuild 1.x installation directory>_ (or _migrate.bat_ on Windows). The param _<QuickBuild 1.x installation directory>_ should be replaced by the actual installation directory of
QuickBuild 1.x.
# After migration, please check the file _/opt/quickbuild2/migrate/migrate-log.html_ for all settings that can not be migrated and needs to be re-configured.
h2. Important changes that affect 1.x users
# Full name of configuration is now separated by character '/', instead of '.'. For example, to refer to configuration _project1_ defined under _root_, the name _root/project1_ should be used instead of _root.project1_.
# Everything defined in the configuration is now inheritable except for _name_ and _description_.
# Configuration settings such as build necessary condition, variables definitions, promote settings, build clean up strategies are placed into advanced settings tab.
# Expressions have been changed a lot. Due to complexity of expressions, we can only migrate default expressions that have not been changed by users. For customized expressions, please rewrite them based on the scripting help, which can be accessed by poining mouse to the help icon when edit related properties.
# By default only one promote destination can be defined now. However multiple promote destinations can be enabled by using variables and scripts as explained in help of property _configuration_ when defined the promotion setting.
# Promotion mechanism is simplified and a QuickBuild repository is no longer necessary in order to fetch files from promotion source. Instead, promotion files are specified when define the promotion settings of related configurations.
# The step type _Send Notification_ is now removed. To specify receivers and conditions of build notifications, please edit advanced settings of related configurations, and enable proper notifications.
# By default, configuration workspaces (previously named _configuration checkout_ directory) are created under the workspace sub directory under the configuration directory. However workspace directories of different configurations can be organized to match the configuration hierarchy with the help of scripting. To demonstrate this, assume we have below configuration hierarchy:
{code}
root
projectA
componentA1
componentA2
projectB
componentB1
componentB2
{code}
Now we need to place workspace of _root_ ocnfiguration under the directory _/workspaces/root_, and workspaces of other configuations should be created under directory _workspace/root_ matching the configuration hierarchy, that is, workspace of configuration _root/projectA_ should be _workspaces/root/projectA_, and workspace of configuration _root/projectA/componentA1_ should be _workspaces/root/projectA/componentA1_, and so on. To do this, just define workspace property of the root configuration as below:
{code}
${current.parent!=null?(current.parent.workspaceDir.absolutePath+"/"+name):"/workspace/root"}
{code}
# The _build cleanly_ option of configuration is removed since it is not flexible. Instead, each step can be configured to clean up the workspace conditionally (through the property _workspace cleanup condition_), and this gives user the flexibility of defining custom behavior of clean build. For example, if you have a checkout step checking out code at agent1, and deliver code to agent2 to build with a build step. You may want to define two build type:
*clean build*: workspace of agent running the build step needs to be cleaned up before running the step, while workspace of the agent running checkout step should remain untouched.
*increment build*: workspaces of both agents should remain untouched.
For scheduled builds, the increment build type should be used; for manual builds, a dialog should be presented to give user a chance to decide whether or not perform a clean build.
To accomplish this, define a configuration variable named _buildCleanly_ with the value being _false_, and set the _prompt setting_ of the variable as _checkbox_. Then define property _workspace cleanup condition_ of checkout step as _false_, and define the same property of build step as _vars.get("buildCleanly").booleanValue_.
In this way, you've defined your own notion of clean/increment build. You can even define three or more build types by using the _selection box_ prompt setting.
# By default QuickBuild does not prompt for build version when manually triggering a build. To get build version prompted, define a variable with prompt setting being _text input_, and reference value of this variable in _next build version_ property of the configuration like below:
{code}
vars.get("buildVersion")
{code}
Here _buildVersion_ refers to name of the variable defined above. Further more, value of the variable can be specified as:
{code}
version-prefix-${vars.get("nameOfBuildNumberVariable").increase()}
{code}
Then version of the build will be auto-increasing if user has not specified value of the variable or if the build is triggered by a scheduler.
# By default QuickBuild does not prompt for build version when promoting a build. However, version of resulting build can be controlled using almost the same techinque as specifying build version when manually triggers a build mentioned above, with the exception that the variable should be defined as a promotion variable in promotion setting section of the configuration. Specifically if you want to have the resulting build always has the same version as the promoted build, just set the variable as not prompted and specify value of the promote variable as:
{code}
${build.version}
{code}