As apps are developed, newer metadata versions can be created each time the application inputs 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.
Upgrade macros are used to upgrade Rose apps to newer metadata versions. They are intended to keep application configurations in sync with changes to application inputs e.g. from new code releases.
This part tutorial walks you through upgrading applications.
Create a new Rose application called
mkdir -p ~/rose-tutorial/garden cd ~/rose-tutorial/garden
Create within it a
rose-app.conf file that looks like this:
meta=rose-demo-upgrade/garden0.1 [env] FOREST=true [namelist:features] rose_bushes=2
meta=... line references a category (
rose-demo-upgrade) at a
particular version (
garden0.1). It’s the version that we want to
Change directory to your new application directory. You can see the available upgrade versions for your new app config by running:
This gives you a list of versions to upgrade to - see the help for more
rose help app-upgrade).
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
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
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
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.
We can upgrade over many versions at once - for example, directly
garden0.9 - and the changes between each version will be
aggregated into a single list of changes.
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
If you run Rose rose app-upgrade with no arguments, you can see that you’re using the latest version.
Some versions may support downgrading - the reverse operation to upgrading. You can see if this is supported by running:
rose app-upgrade --downgrade
You can then use it to downgrade by running:
rose app-upgrade --downgrade <VERSION>
VERSION is a lower supported version. This time, some settings
may be removed.