Recipe config upgrade checklist

The recipe config commons is people!

This documentation is all about helping you make recipe configuration changes that won't break other peoples upgrade deployments There are some specific maintainer responsibilities which are not exactly obvious. This page is all about making them simple and clear to understand. We hope it's clear and if not, please send documentation patches and/or get in touch!

Updating versions in the abra.sh

If you update a config in a recipe, you also need to update the associated config version.

For example, in the Traefik recipe, we have the following in compose.yml:

configs:
  traefik_yml:
    name: ${STACK_NAME}_traefik_yml_${TRAEFIK_YML_VERSION}
    file: traefik.yml.tmpl
    template_driver: golang

And in the abra.sh, we have:

export TRAEFIK_YML_VERSION=v29

If you update the traefik.yml.tmpl with new changes, you must increment TRAEFIK_YML_VERSION. Otherwise, other Co-op Cloud operators will see an obscure error message when they try to deploy your new version.

Backwards compatible environment variable changes

If you add a new environment variable to the .env.sample then you can potentially create manual upgrade work for other Co-op Cloud operators.

Depending on the functionality that the environment variable enables or how the recipe is already configured, it is possible to provide a default which maintains backwards compatibility. There is no hard and fast rule for this and it depends on the recipe and context.

A typical way to do this, is to provide a default in the environment stanza. For example, providing a default of false for a new fictitous environment variable called NEW_ENV_VAR so other Co-op Cloud operators do not need to set NEW_ENV_VAR=false in their app .env file (unless they want to change it).

environment:
    - NEW_ENV_VAR=${NEW_ENV_VAR:-false}

Another approach is to set this default within the configuration where you reference the environment variable. In .tmpl files, this generally works out something like this:

my_config_option = {{ or (env "NEW_ENV_VAR") "false" }}

Sometimes it is not appropriate to provide a default and it is important that other Co-op Cloud operators make an informed choice about the setting of an environment variable. In this case, please consider leaving a note about your new environment variables in the release notes (see below). The release of this change should then be considered a breaking change and require a major release version.

abra will also warn Co-op Cloud operators about missing environment variables that are present in the recipe .env.sample but not in their app .env file.

Creating new release notes

Help other Co-op Cloud operators understand what they need to take care of when doing an upgrade deployment by creating some release notes about your specific changes.

This is crucial when there are breaking changes, data migrations, work-arounds, hacks etc. present in the new changes. abra will show what you write when others run abra app upgrade.

Good release notes are proven to save hours of pain and misery, so put solidarity into practice and write some excellent release notes for your fellow Co-op Cloud operators!