Rose Advanced Tutorial: Upgrade Usage

Upgrade Usage

Introduction

This part of the Rose user guide walks you through upgrading application configurations to newer metadata versions.

This is intended to automatically keep application configurations in sync with changes to application inputs e.g. from new code releases.

Purpose

Newer metadata versions can be created each time the inputs to the parent code are changed, or just between major releases.

This may mean, for example, that a new compulsory option is added or an old one is removed.

Upgrade macros may be written to automatically apply these changes.

Example

Create a new directory:

mkdir ~/garden/

containing a rose-app.conf file that looks like this:

meta=rose-demo-upgrade/garden0.1

[env]
FOREST=true

[namelist:features]
rose_bushes=2

Example Explanation

The meta=... line references a category (rose-demo-upgrade) at a particular version (garden0.1). It's the version that we want to change.

rose app-upgrade

Change directory to your new application directory. You can see the available upgrade versions for your new app config by running:

rose app-upgrade

This gives you a list of versions to upgrade to - see the help for more information (run rose help app-upgrade).

Upgrading to non-named versions

There can often be more versions than you can see by just running rose app-upgrade. They will not have formal metadata, and represent intermediary steps along the way between proper named versions. You can see all the possible versions by running:

rose app-upgrade --all-versions

Upgrading with rose app-upgrade

You can upgrade directly to the latest (garden0.9) or to other versions - let's choose garden0.2 to start with. Run:

rose app-upgrade garden0.2

Upgrade Changes

This will give you a list of changes that the upgrade will apply to your configuration. Accept it, and your application configuration will be upgraded, with a new option (shrubberies) and a new meta=... version of the metadata to point to. Have a look at the changed rose-app.conf if you like.

Try repeating this by upgrading to garden0.3 in the same way. This time, you'll get a warning - warnings are used to point out problems such as deprecated options when you upgrade.

Many-Version Upgrades

We can upgrade over many versions at once - for example, directly to garden0.9 - and the changes between each version will be aggregated into a single list of changes.

Try running:

rose app-upgrade garden0.9

If you accept the changes, your app config will be upgraded through all the intermediary versions to the new one. Have a look at the rose-app.conf file.

Checking the Version

If you run rose app-upgrade with no arguments, you can see that you're at the latest version.

Downgrading

Some versions may support downgrading - the reverse operation to upgrading. You can see if this is supported by running:

rose app-upgrade --downgrade

Downgrading to a Version

You can then use it to downgrade by running:

rose app-upgrade --downgrade VERSION

where VERSION is a lower supported version. This time, some settings may be removed.