docs: updated

.github/workflows/dump-github-variables.yml

@@ -1,3 +1,4 @@
+# this workflow is just for debugging/development purposes and not needed for the actual workflow
 name: dump github variables
 on:
   workflow_dispatch:

README.md

@@ -1,28 +1,61 @@
-# devcontainer-boilerplate
+# About
 
-# development
+This project is a template for WordPress projects using Dev Containers.
 
-## prerequisites
+> Dev Containers are a standardized way to define and describe development environments. They are based on Docker containers and can be used with any editor or IDE. Dev Containers are a great way to __ensure that all developers on a project have the same development environment__, regardless of their operating system. The same Dev Container can be used for local development, CI/CD, and more.
+
+It shows how to use [Development Containers](https://containers.dev/) for WordPress plugins/theme development.
+
+_The WordPress plugin in this project is a very rudimentary plugin stub only for showcasing that Dev Containers *just work* for WordPress development (including usage of `wp-scripts` and friends)_
+
+## Features
+
+- [x] Dev Container definition (`./.devcontainer`) providing
+    - [x] `pnpm`
+    - [x] `composer`
+    - [x] `wp-env`
+    - [x] `php` including out of the box `xdebug` support
+    - [x] SSH access
+    - [x] configurable environment (`./.devcontainer/devcontainer.env`)
+- [x] Automatic provisioning of the Dev Container for CI using a GitHub Action
+  - [x] including caching of the Dev Container image
+- [x] VSCode Dev Container integration
+
+Docker in Docker works smoothly in the Dev Container (`wp-env` makes usage of this feature).
+
+Additional Software can easily be installed/configured into the Dev Container by editing `./.devcontainer/Dockerfile` and or `./.devcontainer/devcontainer.json`.
+
+## GitHub actions
+
+GitHub action `./.github/workflows/build-devcontainer.yml` is used to build the Dev Container image and push it to the GitHub Container Registry.
+
+The image is then used in the CI pipeline to run the tests (`./.github/workflows/test-devcontainer.yml`).
+
+# Development
+
+## Prerequisites
 
 - docker
 
 - (optional) vscode
 
-## setup
+## Setup
 
 - `pnpm install`
 
 - `pnpm start`
 
-## setup using dev container
+### VS Code
+
+setup using dev container :
 
 - install vscode
 
 - install vscode extension `ms-vscode-remote.remote-containers`
 
 - open vscode and follow the directions or open the devcontainer in vscode
 
-## snippets
+## Snippets
 
 - execute `composer --version` in dev container : `pnpm exec devcontainer exec --workspace-folder $(pwd) composer --version`
 
@@ -34,6 +67,22 @@
 
 If you want to use Git hooks for your codespace, then you should set up hooks using the devcontainer.json lifecycle scripts, such as postCreateCommand
 
+# GitLab CI
+
+Dev Container can also be used in GitLab CI. Usage is straightforward and similar to GitHub CI : https://containers.dev/guide/gitlab-ci
+
+# PHPStorm
+
+Dev Container can also be used in PHPStorm : https://www.jetbrains.com/help/phpstorm/connect-to-devcontainer.html
+
+# CLI
+
+Dev Containers can be used in any environment as long as the `docker` prereqisite exists.
+
+There is a NPM package `@devcontainers/cli` managing the usage of Dev Containers in a terminal right at your fingertips : https://containers.dev/guide/cli
+
+As a consequence of the above almost any editing environment can be used with Dev Containers.
+
 # Links
 
 - https://github.com/devcontainers/ci
@@ -43,3 +92,4 @@ If you want to use Git hooks for your codespace, then you should set up hooks us
 - https://github.com/devcontainers/cli
 
   A reference implementation for the specification that can create and configure a dev container from a devcontainer.json.
+