update README

README.md

@@ -1,28 +1,38 @@
 # Podman Compose
 
-An implementation of `docker-compose` with [Podman](https://podman.io/) backend.
-The main objective of this project is to be able to run `docker-compose.yml` unmodified and rootless.
-This project is aimed to provide drop-in replacement for `docker-compose`,
-and it's very useful for certain cases because:
+An implementation of [Compose Spec](https://compose-spec.io/) with [Podman](https://podman.io/) backend.
+This project focus on:
 
-- can run rootless
-- only depend on `podman` and Python3 and [PyYAML](https://pyyaml.org/)
-- no daemon, no setup.
-- can be used by developers to run single-machine containerized stacks using single familiar YAML file
+* rootless
+* daemon-less process model, we directly execute podman, no running daemon.
+
+This project only depend on `podman` and Python3 and [PyYAML](https://pyyaml.org/).
+And it's formed as a single python file script that you can drop into your PATH and run.
+
+## References:
+
+* [spec.md](https://github.com/compose-spec/compose-spec/blob/master/spec.md)
+* [docker-compose compose-file-v3](https://docs.docker.com/compose/compose-file/compose-file-v3/)
+* [docker-compose compose-file-v2](https://docs.docker.com/compose/compose-file/compose-file-v2/)
+
+## Alternatives
+
+As in [this article](https://fedoramagazine.org/use-docker-compose-with-podman-to-orchestrate-containers-on-fedora/) you can setup a `podman.socket` and use unmodified `docker-compose` that talks to that socket but in this case you lose the process-model (ex. `docker-compose build` will send a possibly large context tarball to the daemon)
 
 For production-like single-machine containerized environment consider
 
 - [k3s](https://k3s.io) | [k3s github](https://github.com/rancher/k3s)
 - [MiniKube](https://minikube.sigs.k8s.io/)
-- [MiniShift](https://www.okd.io/minishift/)
-
 
 For the real thing (multi-node clusters) check any production
-OpenShift/Kubernetes distribution like [OKD](https://www.okd.io/minishift/).
+OpenShift/Kubernetes distribution like [OKD](https://www.okd.io/).
 
-## NOTE
+## Versions
 
-This project is still under development.
+If you have legacy version of `podman` (before 3.x) you might need to stick with legacy `podman-compose` `0.1.x` branch.
+The legacy branch 0.1.x uses mappings and workarounds to compensate for rootless limitations.
+
+Modern podman versions (>=3.4) do not have those limitations and thus you can use latest and stable 1.x branch.
 
 ## Installation
 
@@ -47,7 +57,7 @@ curl -o /usr/local/bin/podman-compose https://raw.githubusercontent.com/containe
 chmod +x /usr/local/bin/podman-compose
 ```
 
-or 
+or inside your home
 
 ```
 curl -o ~/.local/bin/podman-compose https://raw.githubusercontent.com/containers/podman-compose/devel/podman_compose.py
@@ -91,11 +101,4 @@ When testing the `AWX3` example, if you got errors just wait for db migrations t
 Inside `tests/` directory we have many useless docker-compose stacks
 that are meant to test as much cases as we can to make sure we are compatible
 
-## How it works
-
-The default mapping `1podfw` creates a single pod and attach all containers to
-its network namespace so that all containers talk via localhost.
-For more information see [docs/Mappings.md](docs/Mappings.md).
-
-If you are running as root, you might use identity mapping.