adds docu on getting started and contributing

README.md

@@ -1,3 +1,222 @@
-# Ansible Collection - theliberatededge.test_linux_containers
+# Overview
 
-Documentation for the collection.
+The Ansible collection `theliberatededge.test_linux_containers`
+helps with automating various scenarios based on
+[Linux containers](https://linuxcontainers.org/).
+
+# Getting started
+
+This section describes the ways in which engineers could benefit from utilising
+the Ansible collection `theliberatededge.test_linux_containers`.
+
+## Prerequisites
+
+1. You have access to a machine running a Linux distribution of your
+choice.
+2. [LXD](https://ubuntu.com/lxd) has been installed and initialised on this
+machine, so that containers can be launched. It will effectively be used as
+a container hypervisor.
+3. Your user has been granted permissions to manage Linux containers.
+4. Python 3 has been set up correctly on the machine.
+5. [Ansible](https://pypi.org/project/ansible/) has been installed.
+
+# Install the Ansible collection theliberatededge.test_linux_containers
+
+Install or update `theliberatededge.test_linux_containers` on your
+Linux machine using `ansible-galaxy`.
+
+```
+ansible-galaxy collection install -U --force \
+    git+https://git.theliberatededge.org/the-liberated-edge/test_linux_containers.git,i-1-test-linux-container
+```
+
+## Run the launch_linux_container playbook
+
+Substitute the missing variable valuess and run the playbook
+for launching Debian Bookworm linux containers.
+
+Variables
+- `lte_container_name` stands for the desired container name that
+will be visible when running `lxc ls`.
+- `lte_container_root_pwd` is the password that will be set for
+the `root` user in the container named `lte_container_name`.
+
+```
+LC_ALL=C.UTF-8 ansible-playbook \
+    theliberatededge.test_linux_containers.launch_linux_container \
+        -e "lte_container_name=<container name> lte_container_root_pwd=<password>"
+```
+
+Once the playbook finishes execution, you should be able to
+connect to the newly launched container as user `root` via
+ssh.
+
+## Include playbook or role from the collection
+
+Reusing Ansible roles and playbooks is quite straight
+forward and follows the practices established by Ansible. Below
+you will find a sample playbook.
+
+Similarly to executing the playbook via CLI, one needs to
+assign values to the missing variables.
+
+```
+---
+- name: Launch Linux Container
+  hosts: all
+  gather_facts: false
+- name: imports and executes the playbook under test
+  ansible.builtin.import_playbook:
+    theliberatededge.test_linux_containers.launch_linux_container.yml
+  vars:
+    lte_debian_version: bookworm
+    lte_container_name: <container name>
+    lte_container_root_pwd: <password>
+```
+
+# How to contribute
+
+This section describes what you need to do in order to contribute to this
+project if you want to work on our code base. It is all about setting up your
+local development environment and the ways of working that we have
+established.
+
+## Development workflow
+
+Our team uses [Github flow](https://docs.github.com/en/get-started/quickstart/github-flow)
+to release changes.
+
+## Definition of Done
+
+We are a small team and for us squeezing and saving any second is key. This
+is the way we could manage better our scarce resources. Therefore, we have
+been experimenting with and adopting industry practices which help us
+do more with less.
+
+Every change that we merge in the `main` branch complies to the following
+list of requirements or checklist.
+
+1. Every change request is represented as a git pull request. Merging changes
+directly in the `main` branch is prohibited and guarded by a branch protection
+rule in our source control system.
+2. Every git pull request has been linked to exactly one project issue. The
+issue number prefixes the pull request title, e.g. `i-1 <issue title>`.
+3. The change has been thoroughly reviewed and all discovered issues have
+been resolved. Merging without a code review approval is only acceptable
+when reviewers are not available.
+4. The change has been tested by Ansible Molecule scenarios. Our team adopted
+an approach resembling Test Driven Development for the sake of automated
+regression testing and avoidance. 
+5. All automated tests have been passing successfully consistently. We have
+zero tolerance on test flakiness.
+6. Source code has been linted with `yamllint` and `ansible-lint`. Any issues
+have been resolved.
+7. YAML documents have been formated with `yamlfix`.
+8. User facing changes have been documented appropriately.
+
+## Development environment setup
+
+### Prerequisites
+
+Before you could set up your local development environment you will need to
+make sure that the list of prerequisites below has been satisfied.
+
+1. You have access to a machine running a Linux distribution of your
+choice.
+2. [LXD](https://ubuntu.com/lxd) has been installed and initialised on this
+machine, so that containers can be launched. It will effectively be used as
+a container hypervisor.
+3. Your user has been granted permissions to manage Linux containers.
+4. Python 3 has been set up correctly on the machine.
+5. [Pipenv](https://github.com/pypa/pipenv) has been installed on the machine.
+6. [git](https://git-scm.com/) has been installed on the machine.
+
+### Initialize collection project locally
+
+All dependencies and dev dependencies will be installed in a Python 3 virtual
+environment, which will be activated for you.
+```
+git clone \
+    https://git.theliberatededge.org/the-liberated-edge/test_linux_containers.git
+```
+
+```
+cd test_linux_containers
+```
+
+```
+pipenv install
+```
+
+```
+pipenv install --dev
+```
+
+```
+pipenv shell
+```
+
+### Lint Ansible artifacts
+
+Navigate to the root folder of the local copy of this git repository.
+
+```
+cd test_linux_containers
+```
+
+Lint all YAML documents.
+
+```
+yamllint .
+```
+
+Use `ansible-lint` to verify good practices relevant to Ansible.
+
+```
+LC_ALL=C.UTF-8 ansible-lint .
+```
+
+### YAML code formatting
+
+Navigate to the root folder of the local copy of this git repository.
+
+```
+cd test_linux_containers
+```
+
+Format all YAML documents.
+
+```
+yamlfix .
+```
+
+### Execute Ansible Molecule scenarios
+
+In order to run all existing Ansible Molecule scenarios, one needs to
+follow the steps below.
+
+Navigate to the root folder of the local copy of this git repository.
+
+```
+cd test_linux_containers
+```
+
+Install locally a snapshot version of `theliberatededge.test_linux_containers`
+that will be used as the foundation for automated testing.
+
+```
+LC_ALL=C.UTF-8 ansible-galaxy install -r requirements-test.yml --force
+```
+
+Execute all existing Ansible Molecule scenarios.
+
+```
+cd extensions
+```
+
+```
+LC_ALL=C.UTF-8 \
+LTE_CONTAINER_NAME=<container name> \
+LTE_CONTAINER_ROOT_PWD=<password> \
+    molecule test --all
+```