HACKING

---How to install molecule on Debian

First ensure you have podman and python3-venv installed:

    $ apt install podman python3-venv

Then install molecule using pip in a Python virtual environment
(venv):

    $ python3 -m venv venv
    $ source venv/bin/activate
    $ pip install molecule molecule-podman

Using a Python virtual environment in this way means that venv/bin is
added to your PATH environment variable (the "activate" script does
that for you), and all packages installed by pip are also installed in
the venv directory. You can then run tests using molecule as described
below. (If you then want to cleanup then just exit your shell and
remove the venv directory.)

---How to run all molecule tests

    $ molecule test
    $ molecule test -s golang
    $ molecule test -s sigsum_agent
    $ molecule test -s yubihsm_connector
    $ molecule test -s litewitness
    $ molecule test -s litebastion

If a test fails, molecule gives a nonzero return code. This means that
you can use a script like the following to run all mulecule tests,
where the "All tests passed successfully" echo line is reached only if
all tests passed:

    #!/bin/bash
    set -e
    molecule test
    molecule test -s golang
    molecule test -s sigsum_agent
    molecule test -s yubihsm_connector
    molecule test -s litewitness
    molecule test -s litebastion
    echo All tests passed successfully

---What to expect in the output from the molecule tests

The warning "WARNING  Driver podman does not provide a schema" is to be
expected, that warning can be ignored.

The "molecule test -s golang" test gives red-colored output indicating
a failure for the "Require the minimum Go version" task, but that is
an expected failure intentionally triggered by the test to verify that
the version number check works, so that red output can be safely
ignored.

Apart from the exceptions above, the output from the molecule tests
should include no other error or warning messages.

---How to develop with molecule

Think of "molecule converge" as running ansible on a host. Multiple
invocations of converge results in multiple runs of ansible on the
host.

Use "molecule login" to get a shell on the host.  This is, e.g.,
helpful for debugging and interactive testing (editing a file,
converge again, etc).

Use "molecule destroy" to clean up the host.  If any container is
lingering (podman container ls --all), use "molecule destroy --all"
instead.

Use "molecule test" to run an automated test.  Add "--destroy never"
to keep the container in case of failure (which permits "molecule
login").

Interactive deploy, debug, deploy again, verify, and clean-up session:

    $ molecule converge
    $ molecule login --host sigsum-primary
    $ molecule login --host sigsum-primary-ssh-agent
    $ molecule converge
    $ molecule verify
    $ molecule destroy

To work with a different scenario like ./molecule/golang, use "-s golang".

Each test scenario can have its own configuration in a "scenario:"
section in the corresponding molecule.yml file, as in for example the
molecule/litebastion/molecule.yml file. See
https://ansible.readthedocs.io/projects/molecule/configuration/#scenario

---How to make a release

Ensure that all molecule tests pass.

Update docs/docsite/rst/CHANGELOG.rst.

Update galaxy.yml 'version'.

Create a signed tag:

    $ git tag --sign v${VERSION} -m "Release ${VERSION}"
    $ git push --tags