Update documentation (#989)

.github/CODEOWNERS

@@ -1,4 +1,4 @@
 # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 # Order is important; the last matching pattern takes the most precedence.
 
-*                    @FerretDB/specops
+*  @AlekSi

CONTRIBUTING.md

@@ -1,85 +1,73 @@
 # Contributing
 
-The dance tool and tests run on the host; macOS, Linux, and Windows are expected to work.
-Databases under test (FerretDB and MongoDB) may be running on the host or inside Docker;
-Docker Compose configuration is provided for convenience but not required.
-In particular, the FerretDB development cycle (fix-compile-run-dance) is faster with it running on the host
-as it does not involve Docker image building or PostgreSQL restarts.
-Running FerretDB on the host is recommended for that reason.
+## Concepts
 
-## Cloning repository
-
-```sh
-git clone --recursive
-```
+There are *projects* that use MongoDB and could work with FerretDB.
+Those projects have some kind of integration tests and/or benchmarks (we will call them *tests* for simplicity); sometimes, a project is only a set of tests.
+Names uniquely identify both projects and tests within the project.
 
-Remember to use that command to clone this repository with all submodules included.
+Tests are run against a *database* identified by name.
+Each database has a single canonical MongoDB URI and configuration.
+Different configurations should be represented as different named databases.
+Databases may be run locally (for example, with Docker Compose) or remotely.
 
-```sh
-git submodule update --init
-```
+Project tests a run against a database by a *runner* that returns *test results*.
+In the simplest case, the test result contains only name, status, and unparsed output; other runner types may include additional properties like numerical measurements for benchmarks.
+Different *runner types* accept different *parameters*; sometimes, they may include test names, and sometimes, names are parsed from the output.
 
-If you've already cloned it without submodules you can use that command
-to include required submodules.
+*Project configuration* is a YAML file with a name matching the project name, containing a runner type, runner parameters, and expected test results per database name.
+Multiple MongoDB URIs (canonical form, URI with invalid credentials, etc) are available in runner parameters via template variables.
+Project configuration can not contain database-specific tests; instead, some tests may be expected to fail for some databases.
 
-## Running tests
+The dance tool runs tests described by project configuration and compares actual and expected results.
+The dance tool itself does not start and stop databases, but the repository provides `docker-compose.yml` and `Taskfile.yml`, which do that.
 
-```sh
-bin/task dance DB=ferretdb-postgresql TEST=mongo-go-driver
-```
-
-That command will run `mongo-go-driver` tests against FerretDB with PostgreSQL backend.
-`DB` environment variable should have the value `ferretdb-postgresql`, `ferretdb-sqlite`, or `mongodb`.
-It defines what tests are expected to pass and fail.
-For example, see [mongo-go-driver tests configuration](https://github.com/FerretDB/dance/blob/main/tests/mongo-go-driver.yml).
-`TEST` environment variable should have the value matching a YAML file in the `tests` directory, or be empty.
-It defines what test configuration to run; empty value runs all configurations.
+## Cloning repository
 
-## Starting environment with Docker Compose
+Projects are included in the repository as git submodules.
 
 ```sh
-bin/task env-up DB=mongodb
+git clone --recursive
 ```
 
-That command will start MongoDB in Docker container.
-Please note that running `bin/task dance DB=ferretdb-postgresql` after that would run tests against that MongoDB,
-but results would be compared against results expected for FerretDB.
-In short, that would be wrong.
+The existing working copy can be updated with:
 
 ```sh
-bin/task env-up DB=ferretdb-postgresql
+git submodule update --init
 ```
 
-or
+## Starting environment
 
 ```sh
-bin/task env-up DB=ferretdb-sqlite
+export FERRETDB_IMAGE=ghcr.io/ferretdb/ferretdb-dev:main
+export POSTGRES_IMAGE=postgres:16
+
+bin/task env-up
+bin/task DB=ferretdb-postgresql
 ```
 
-That command will start FerretDB with a specified backend from `ferretdb-local` Docker image.
+The first command starts all databases defined in `docker-compose.yml`.
+The second form may be used to start a single database by name (Docker Compose services use the same names) to save resources.
+All databases use different ports, so running them all should be possible.
 
-To build a local image use the `bin/task docker-local` command in the [FerretDB](https://github.com/FerretDB/FerretDB) repository.
-To use a pre-built image you must set the `FERRETDB_IMAGE` environment variable,
-e.g. `export FERRETDB_IMAGE=ghcr.io/ferretdb/ferretdb-dev:main`.
+During FerretDB development, it is recommended to run it on the host with the same listening port as the matching Docker Compose service instead of using the above commands.
+This way, the fix-build-test development cycle will be faster as it does not involve Docker image building.
 
-As mentioned above, this approach is not recommended.
+Alternatively, the Docker image with the name `ferretdb-local` can be built by `task docker-local` in the FerretDB repository.
+In this case, `FERRETDB_IMAGE` must be unset to use that default image name.
 
-### Adding tests
+## Running tests
 
-In order add your tests to dance CI you must use the `command` runner and add your repository as a submodule.
-The `command` runner will invoke any command and CLI arguments.
+```sh
+bin/task dance
+bin/task dance DB=ferretdb-postgresql,mongodb CONFIG=python.yml
+```
 
-For example if you wanted to add your Java application to dance, you would do the following:
+The first command runs all project configurations.
+The second form can be used to run a single project configuration for some databases.
+Both parameters are optional.
 
-1. Add the submodule to the `tests` directory `git submodule add -b main https://github.com/my-org/my-app.git`.
-2. Create a shell script in the `tests` directory called `my-app.sh` with the required logic needed to run your test.
-3. Create a YAML file called `my-app.yml` in the `tests` directory
-   and provide the `args` field with the shell script so that the runner can invoke it.
-4. Start the environment and test it locally before submitting a PR to ensure that it works correctly.
-   Refer to the above [section](#starting-environment-with-docker-compose)
-   on how to start the environment.
-5. Run the test locally to verify the output `bin/task dance DB=ferretdb-postgresql TEST=my-app`.
-6. Submit a PR to with a title of the form "Add MyApp tests".
+## Conventions
 
-See an example [shell script](https://github.com/FerretDB/dance/blob/main/tests/java-example.sh)
-and [YAML](https://github.com/FerretDB/dance/blob/main/tests/java-example.yml) files.
+We expect most or all tests to pass when run against MongoDB; a few exceptions should have comments explaining why.
+Tests failing against FerretDB should have issue links in the comments.

README.md

@@ -1,16 +1,10 @@
 # dance
 
+[![Go](https://github.com/FerretDB/dance/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/FerretDB/dance/actions/workflows/go.yml)
 [![Dance](https://github.com/FerretDB/dance/actions/workflows/dance.yml/badge.svg?branch=main)](https://github.com/FerretDB/dance/actions/workflows/dance.yml)
 
 FerretDB integration testing tool named after [Ferret war dance](https://en.wikipedia.org/wiki/Weasel_war_dance).
-It runs integration tests of various software that uses MongoDB
-(such as [MongoDB Go driver](https://github.com/mongodb/mongo-go-driver))
-against both MongoDB and FerretDB with various backends,
-and compares results with ones expected by tests configurations.
-It is expected that most or all tests pass when run against MongoDB,
-so we mark a few or none tests as expected failures or skips in configuration.
-More tests fail (and are marked as expected failures in tests configuration) when run against FerretDB,
-but their number goes down over time.
-All failing or skipping tests should have comments with explanation, typically a GitHub issue URL.
+It runs integration tests of various projects that use MongoDB against both MongoDB and FerretDB,
+and compares results with ones expected by configurations.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for running instructions.

internal/config/config.go

@@ -18,7 +18,7 @@ package config
 // Status represents the status of a single test.
 type Status string
 
-// Constants representing different expected or actual  test statuses.
+// Constants representing different expected or actual test statuses.
 const (
 	Fail    Status = "fail"
 	Skip    Status = "skip"