---
title: Recipe config upgrade checklist
---

!!! warning "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 :heart: 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](/intro/contact)!

## 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](https://git.coopcloud.tech/coop-cloud/traefik)
recipe, we have the following in
[`compose.yml`](https://git.coopcloud.tech/coop-cloud/traefik/src/branch/master/compose.yml#L104-L108):

```yaml
configs:
  traefik_yml:
    name: ${STACK_NAME}_traefik_yml_${TRAEFIK_YML_VERSION}
    file: traefik.yml.tmpl
    template_driver: golang
```
And in the [`abra.sh`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/9a46c85735701780dc8f0717a4e6cab4969420fc/abra.sh#L1), we have:

```bash
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).

```yaml
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](/maintainers/handbook/#how-do-i-write-version-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!