1 files changed, 64 insertions, 0 deletions
diff --git a/subplot.md b/subplot.md
new file mode 100644
index 0000000..a56e15b
--- /dev/null
+++ b/subplot.md
@@ -0,0 +1,64 @@
+# Introduction
+
+`debian-ansible` is a collection of Ansible roles for managing Debian
+systems. The roles are re-usable and parameterised so that they can be
+adapted to some variations.
+
+This document describes the roles and also acts as an acceptance test
+suite for them. The [Subplot][] program can generate a test program
+based on this document, and the test program tests that the roles work
+as intended.
+
+[Subplot]: https://subplot.liw.fi/
+
+## Using these roles
+
+Eventually, all the roles included with `debian-ansible` will follow
+the same principles:
+
+* the playbook using a role defines which version of each role they
+  expect to use by defining a variable such as `unix_users_version`
+  - the role checks that it's defined to the right value and fails if
+    it isn't
+* the role is parameterized via variables, with names prefixed with
+  the role name
+  - the role `unix_users` expects a variable `unix_users` that lists
+    all the users to create
+* any variables used by role have "empty" default values, unless the
+  variable must be defined by the playbook using the role
+  - the role will check that the necessary variables are defined,
+    before doing anything
+
+# Implementation and testing of these roles
+
+If you're just using the roles, you don't need to care about this chapter.
+
+## Source files
+
+At the root of the `debian-ansible` source tree is a `subplot.md`, and
+the subdirectory `subplot` with some other files used by the main
+file. Each role directory should have a `subplot.md`, and may also
+have `subplot.yaml` and `subplot.py`. The files in role directories
+get combined with the main ones the the `./check` script.
+
+## Scenario structure
+
+Each `subplot.md` file is meant to contain at least one scenario. All
+scenarios have the same structure:
+
+* create a new VM
+* construct an Ansible playbook that uses the role in a specific way
+* run the playbook against the VM
+* examine the VM to verify it has been changed in the expected way
+
+The VM is created using a base image, which the user must specify to
+the test program by setting the `BASEIMAGE` environment variable.
+
+## Sanity check
+
+Verify that everything looks OK and that other scenarios can be run.
+
+~~~scenario
+given a host running Debian
+then I can run /bin/true on the host
+~~~