1 files changed, 75 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..50934d8
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,75 @@
+Psycopg 3 -- PostgreSQL database adapter for Python
+===================================================
+
+Psycopg 3 is a modern implementation of a PostgreSQL adapter for Python.
+
+
+Installation
+------------
+
+Quick version::
+
+    pip install --upgrade pip               # upgrade pip to at least 20.3
+    pip install "psycopg[binary,pool]"      # install binary dependencies
+
+For further information about installation please check `the documentation`__.
+
+.. __: https://www.psycopg.org/psycopg3/docs/basic/install.html
+
+
+Hacking
+-------
+
+In order to work on the Psycopg source code you need to have the ``libpq``
+PostgreSQL client library installed in the system. For instance, on Debian
+systems, you can obtain it by running::
+
+    sudo apt install libpq5
+
+After which you can clone this repository::
+
+    git clone https://github.com/psycopg/psycopg.git
+    cd psycopg
+
+Please note that the repository contains the source code of several Python
+packages: that's why you don't see a ``setup.py`` here. The packages may have
+different requirements:
+
+- The ``psycopg`` directory contains the pure python implementation of
+  ``psycopg``. The package has only a runtime dependency on the ``libpq``, the
+  PostgreSQL client library, which should be installed in your system.
+
+- The ``psycopg_c`` directory contains an optimization module written in
+  C/Cython. In order to build it you will need a few development tools: please
+  look at `Local installation`__ in the docs for the details.
+
+  .. __: https://www.psycopg.org/psycopg3/docs/basic/install.html#local-installation
+
+- The ``psycopg_pool`` directory contains the `connection pools`__
+  implementations. This is kept as a separate package to allow a different
+  release cycle.
+
+  .. __: https://www.psycopg.org/psycopg3/docs/advanced/pool.html
+
+You can create a local virtualenv and install there the packages `in
+development mode`__, together with their development and testing
+requirements::
+
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install -e "./psycopg[dev,test]"    # for the base Python package
+    pip install -e ./psycopg_pool           # for the connection pool
+    pip install ./psycopg_c                 # for the C speedup module
+
+.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-editable
+
+Please add ``--config-settings editable_mode=strict`` to the ``pip install
+-e`` above if you experience `editable mode broken`__.
+
+.. __: https://github.com/pypa/setuptools/issues/3557
+
+Now hack away! You can run the tests using::
+
+    psql -c 'create database psycopg_test'
+    export PSYCOPG_TEST_DSN="dbname=psycopg_test"
+    pytest