Add initial README.md

Add a proper readme with getting started info, license and a few more
pointers.

README.md

@@ -1,48 +1,140 @@
-# pg-roll
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Linux Build](https://github.com/xataio/pg-roll/actions/workflows/build.yml/badge.svg)](https://github.com/xataio/pg-roll/actions?query=branch%3Amain)
+[![Release](https://img.shields.io/github/release/xataio/pg-roll.svg?label=Release)](https://github.com/xataio/pg-roll/releases)
 
-:warning: Under development :warning:
+# pg-roll - Zero-downtime schema migrations for PostgreSQL
 
-PostgreSQL zero-downtime migrations made easy.
+`pg-roll` is a command-line tool that radically simplifies schema migrations in PostgreSQL. It takes care of the complex migration operations to ensure that client applications continue working while the database schema is being updated. This includes ensuring changes are applied without locking the database, and that both old and new schema versions work simultaneously (even when breaking changes are being made!). This removes risks related to schema migrations, and greatly simplifies client application rollout, also allowing for instant rollbacks.
 
-## Getting started (development)
+Written in Go, pg-roll is a single binary with no external dependencies. It is designed to be simple to use and work across platforms.
 
-* Bring a development PostgreSQL up:
+## How pg-roll works
 
-    ```sh
-    docker compose up
-    ```
+TODO
 
-* Initialize pg-roll (first time only):
+## Features
 
-    ```sh
-    go run . init
-    ```
+- Simple to use, single binary with no external dependencies.
+- Zero-downtime migrations (no database locking, no breaking changes).
+- Keep old and new schema versions working simultaneously.
+- Instant rollback in case of issues during migration.
+- Works with PostgreSQL 14.0 or later.
 
-* Start a migration:
+## Table of Contents
 
-    ```sh
-    go run . start examples/01_create_tables.json
-    ```
+- [Installation](#installation)
+- [Usage](#usage)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
 
-* Inspect the results:
+## Installation
 
-    ```sh
-    psql postgres://localhost -U postgres
-    ```
+### Binaries
 
-    ```sql
-    \d+ public.*
-    \d+ 01_create_tables.*
-    ```
+Binaries are available for Linux, macOS & Windows, check our [Releases](releases).
 
-* (Optional) Rollback the migration (undo):
+### From source
 
-    ```sh
-    go run . rollback
-    ```
+To install pg-roll from source, run the following command (requires Go 1.21 or later):
 
-* Complete the migration:
+```sh
+go install github.com/xataio/pg-roll
+```
 
-    ```sh
-    go run . complete
-    ```
+## Usage
+
+To perform a schema migration using pg-roll, follow these steps:
+
+### Prepare the database
+
+pg-roll needs to store some state in the database. A table is created to track the current schema versions and store version history. To prepare the database, run the following command:
+
+```sh
+pg-roll init postgres://user:password@host:port/dbname
+```
+
+### Start a migration
+
+Create a migration file, check the [examples](examples) folder for some examples. For instance, to create a new `customers` table:
+
+<details>
+  <summary>initial_migration.json</summary>
+
+```json
+{
+  "name": "initial_migration",
+  "operations": [
+    {
+      "create_table": {
+        "name": "customers",
+        "columns": [
+          {
+            "name": "id",
+            "type": "integer",
+            "pk": true
+          },
+          {
+            "name": "name",
+            "type": "varchar(255)",
+            "unique": true
+          },
+          {
+            "name": "bio",
+            "type": "text",
+            "nullable": true
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+</details>
+
+Then run the following command to start the migration:
+
+```sh
+pg-roll --postgres-url postgres://user:password@host:port/dbname start initial_migration.json
+```
+
+### Complete the migration
+
+TODO
+
+### Complete the migration
+
+TODO
+
+### Rolling back a migration
+
+TODO
+
+### Advanced Usage
+
+For more advanced usage and detailed options, refer to the [Documentation](docs).
+
+## Contributing
+
+We welcome contributions from the community! If you'd like to contribute to pg-roll, please follow these guidelines:
+
+* Use [issues](https://github.com/xataio/pg-roll/issues) for any questions, bug reports, or feature requests.
+* Check the documentation and [existing issues](https://github.com/xataio/pg-roll/issues) before opening a new issue.
+
+### Contributing Code
+* Fork the repository.
+* Create a new branch for your feature or bug fix.
+* Make your changes and write tests if applicable.
+* Ensure your code passes linting and tests.
+* Submit a pull request.
+[TODO]:* Please see our Contribution Guidelines for more details.
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+If you have any questions, encounter issues, or need assistance, please feel free to open an issue on this repository, and our community will be happy to help.
+
+
+<br>
+<p align="center">Made with :heart: by <a href="https://xata.io">Xata</a></p>