=========
Upgrading
=========

Generally batou tries to be *very* friendly when upgrading from version to
version so you don't have to unnecessarily change your deployments. We try to
introduce new features without breaking existing semantics.

Upgrading to the separated appenv bootstrap file
================================================

`appenv` is a small, separate utility that batou uses to bootstrap and
update itself, introduced in batou 2.

Initially we placed this file directly as `./batou` but this turned out to be
hard to deal with due to its "meta argument parser". New versions of batou will
automatically bootstrap this into two separate files: `./appenv` and a symlink
`batou -> appenv`.

To upgrade your project to this schema, follow those steps:

.. code-block:: console


  $ curl -sL https://raw.githubusercontent.com/flyingcircusio/batou/main/appenv.py -o appenv
  $ chmod +x appenv
  $ rm batou
  $ ln -sf appenv batou

You can now use the appenv meta commands by calling the appenv utility itself:

.. code-block:: console

  $ ./appenv --help
  usage: appenv [-h] {update-lockfile,init,reset,python,run} ...

  positional arguments:
    {update-lockfile,init,reset,python,run}
      update-lockfile     Update the lock file.
      init                Create a new appenv project.
      reset               Reset the environment.
      python              Spawn the embedded Python interpreter REPL
      run                 Run a script from the bin/ directory of the virtual env.

  optional arguments:
    -h, --help            show this help message and exit


batou 1.x to batou 2.x
======================

This upgrade mainly consists of a switch from Python 2 to Python 3 but it also
does include a few details about how things are handled.

Major changes
-------------

* batou requires at least Python 3.5, anything newer is fine, too.

* File changes now show (expected) diffs.

* You can deploy to multiple hosts at once using the `-j` option or the `jobs`
  option in the environment configuration.

* Secrets can now also override `data-` sections for hosts.

* You can now use `assert` instead of `raise UpdateNeeded` in the `verify`
  methods.

* The embedded supervisor has been updated.

Updating your deployment
------------------------

The following steps assume that you have cloned and checked out your deployment
and it is your current working directory.

.. code-block:: console

	$ curl -sL https://raw.githubusercontent.com/flyingcircusio/batou/main/bootstrap | sh

The generated lockfile `requirements.lock` might not pick up all versions of all
packages correctly (for example packages taken directly from source control will
fail) so you might want to doublecheck those and massage the lockfile in case
that this fails with something like:

.. code-block:: console

	ERROR: No matching distribution found for batou-ext==0.1.dev0 (from -r .batou/16f85f2d/requirements.lock (line 3))

.. note:: `batou_ext` will be updated automatically to a proper Python 3 version
  and syntax.

At this point you can now update your projects' component code to Python 3:

.. code-block:: console

	$ 2to3 -w components

After this you need to run batou in your development environment to see whether
any further changes may be needed.

Things you may have to change in your deployment
------------------------------------------------

* Add `sensitive_data=True` to files that may contain sensitive data and whose
  content you do not want to see in any logs. This suppresses diff generation.

* The default hash function has been changed to `sha512` and thus existing
  hashes relying on the default being md5 will fail.


Updating to a newer batou 2.x version
=====================================

After having switched from batou 1.x to 2.x you might update to the latest
``batou`` release once in a while. This requires the following steps:

* Edit ``requirements.txt`` and enter the desired version: ``batou==2.x``.

    - If you want to use an unreleased version use a git URL like this:
      ``-e git+https://github.com/flyingcircusio/batou.git#egg=batou`` instead
      of the ``batou==2.x`` requirement.
* Run ``./appenv update-lockfile`` to update ``requirements.lock``.
* Commit the changes and run ``batou`` so it can update itself to the new
  version.

Updating from 2.2 to 2.3
========================

To define ``Attribute``\s more explicitly the default value has to be passed in
one of two ways.

* ``default`` allows to pass a final python value or use a `ConfigString` value
  to trigger the conversion of the ``Attribute`` on a default value. This can
  be used for more concise code (e.g. ``Address``) or for documentation of the
  format for ``environment.cfg``. This way ``expand`` and ``map`` of the string
  will also be done.