diff --git a/.github/workflows/stack-kafka-flink.yml b/.github/workflows/stack-kafka-flink.yml
index 69f8abff..f468dd49 100644
--- a/.github/workflows/stack-kafka-flink.yml
+++ b/.github/workflows/stack-kafka-flink.yml
@@ -1,4 +1,4 @@
-name: Apache Kafka, Apache Flink, and CrateDB
+name: Apache Kafka, Apache Flink
on:
pull_request:
diff --git a/README.md b/README.md
index 267f42ad..5299b593 100644
--- a/README.md
+++ b/README.md
@@ -1,45 +1,87 @@
+
+
# CrateDB Examples
-## About
+A collection of clear and concise examples how to work with [CrateDB].
+
+Quick links:
+[Dataframe](./by-dataframe) •
+[Language](./by-language) •
+[Framework](./framework) •
+[Stack](./stacks) •
+[Testing](./testing) •
+[Topic](./topic)
+
+More information:
+[Drivers and Integrations](https://cratedb.com/docs/clients/) •
+[Integration Tutorials](https://community.cratedb.com/t/overview-of-cratedb-integration-tutorials/1015) •
+[Reference Documentation](https://cratedb.com/docs/crate/reference/)
+
+
+
+
+## 👨💻 Usage
+
+- You can explore the content by browsing folders within the repository.
+ Main sections can be explored by using the quick links in the header
+ area.
-This repository contains a collection of clear and concise examples
-how to work with [CrateDB](https://github.com/crate/crate). You can
-use them for educational purposes, or as blueprints for your own
-projects.
+- If you are looking for something specific, please use GitHub search, for
+ example, [searching for "jdbc"].
-## Layout
+- You can use the code snippets for educational and knowledge base purposes,
+ or as blueprints within your own projects.
-- The `by-dataframe` folder contains example code snippets how
+- The repository is also used to support QA processes. Each example is
+ designed to be invoked as an integration test case, accompanied by a
+ corresponding CI validation job.
+
+
+## 🧐 What's inside
+
+This section gives you an overview about what's inside the relevant
+folders.
+
+- **by-dataframe** contains example code snippets how
to work with dataframe libraries like pandas, Polars, Dask,
Spark, and friends.
-- The `by-language` folder contains demo programs / technical
+- **by-language** contains demo programs / technical
investigations outlining how to get started quickly with CrateDB
using different programming languages and frameworks.
-- The `framework` folder contains integration scenarios with
+- **framework** contains integration scenarios with
full-fledged applications or software frameworks.
-- The `stacks` folder contains more grown-up, complete usage scenarios
+- **stacks** contains more grown-up, complete usage scenarios
where CrateDB is part of a larger software stack. Those resources
- may also be used within \"reference architecture\" types of
+ may also be used within "reference architecture" types of
documentation.
-- The `testing` folder contains reference implementations about how to
+- **testing** contains reference implementations about how to
use different kinds of test layers for testing your applications
with CrateDB.
-## Testing
-The repository uses an universal test runner to invoke test suites of
-different languages and environments.
+## 🏕️ Testing
+
+### Prerequisites
+
+Before running the software integration tests on your workstation, make sure
+to supply an instance of CrateDB. In order to use the most recent available
+code, this Docker commands selects the `crate/crate:nightly` OCI image.
-Before running the examples on your workstation, make sure you are using
-an up-to-date version of CrateDB:
+```shell
+docker run --rm -it --pull=always \
+ --name=cratedb --publish=4200:4200 --publish=5432:5432 \
+ --env=CRATE_HEAP_SIZE=4g \
+ crate/crate:nightly -Cdiscovery.type=single-node
+```
- docker pull crate/crate:nightly
+### Test Runner `ngr`
-### Introducing `ngr`
+The repository uses a universal test runner to invoke test suites of
+different languages and environments, called `ngr`.
In order to run specific sets of test cases, you do not need to leave
the top-level directory, or run any kind of environment setup procedures.
@@ -54,19 +96,139 @@ If all goes well, just select one of the folders of interest, and invoke
ngr test testing/testcontainers/java
ngr test topic/machine-learning/llm-langchain
-The authors recommend to invoke `ngr` from within a Python virtualenv,
-in order to isolate its installation from the system Python.
+> [!NOTE]
+> It is recommended to invoke `ngr` from within a Python virtualenv,
+> in order to isolate its installation from the system Python.
+> Installing `ngr` works like this:
+> ```shell
+> git clone https://github.com/crate/cratedb-examples
+> cd cratedb-examples
+> python3 -m venv .venv
+> source .venv/bin/activate
+> pip install -r requirements.txt
+> ```
-### Running a Test Matrix
+### Test Matrix Support
Some examples optionally obtain parameters on invocation time.
-An example are the test cases for Npgsql, which accept the version number of
+One example is the test suite for Npgsql, which accepts the version number of
the Npgsql driver release to be obtained from the environment at runtime,
overriding any internally specified versions. Example:
ngr test by-language/csharp-npgsql --npgsql-version=6.0.9
-This feature is handy if you are running a test matrix, which is
-responsible for driving the version numbers, instead of using any
-versions nailed within local specification files of any sort.
+> [!TIP]
+> This feature is handy if you are running a test matrix, which is
+> responsible for driving the version numbers, instead of using the
+> version numbers nailed within local specification files of any sort.
+
+
+### CI Status
+
+This section outlines the status of integration tests on CI/GHA.
+
+
+
+
+ |
+Status |
+
+
+
+
+
+
+|
+Dataframe
+ |
+
+
+ 
+
+ 
+ |
+
+
+
+|
+Language
+ |
+
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+ |
+
+
+
+|
+Framework
+ |
+
+
+ 
+
+ 
+ |
+
+
+
+|
+Testing
+ |
+
+
+ 
+ |
+
+
+
+|
+Topic
+ |
+
+Machine Learning
+
+
+ 
+
+ 
+
+ 
+ |
+
+
+
+
+
+
+## 💁 Contributing
+
+Interested in contributing to this project? Thanks so much for your interest!
+
+As an open-source project, we are always looking for improvements in form of
+contributions, whether it be in the form of a new feature, improved
+infrastructure, or better documentation.
+
+Your bug reports, feature requests, and patches are greatly appreciated.
+
+
+## 🌟 Contributors
+
+[](https://github.com/crate/cratedb-examples/graphs/contributors)
+
+
+[CrateDB]: https://github.com/crate/crate
+[searching for "jdbc"]: https://github.com/search?q=repo%3Acrate%2Fcratedb-examples+jdbc