chore: update README (#818)

Co-authored-by: Pierre Millot <[email protected]>

Author: shortcuts

README.md

@@ -1,50 +1,78 @@
-# api-clients-automation
+<div align="center">
 
-**Make sure to have Docker installed so you don't have to install the tooling for every API clients.**
+# API Clients Automation
 
-## Setup repository tooling
+The Algolia API clients are generated from [OpenAPI specs](https://swagger.io/specification/), leveraging the open-source [openapi-generator](https://openapi-generator.tech/) tool.
+
+[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](./LICENSE)
+
+<p align="center">
+  <strong>
+  <a href="https://api-clients-automation.netlify.app/">API clients automation documentation</a> •
+  <a href="https://www.algolia.com/doc/">Algolia documentation</a>
+  </strong>
+</p>
+
+</div>
+
+**Migration note from current API clients**
+
+> In July 2022, we released an alpha version generated API clients for the JavaScript, Java and PHP languages. If you are using the latest stable of those clients and looking to upgrade, read the [migration guide](https://api-clients-automation.netlify.app/docs/clients/migration-guides/). You can still browse the documentation of the stable clients on [the Algolia documentation](https://www.algolia.com/doc/).
+
+## 💡 Getting Started with the clients
+
+You can read `getting started` guides and how to use the API clients on [our documentation](https://api-clients-automation.netlify.app/docs/clients/installation).
+
+## ✨ Contributing
+
+> Looking to add a new client, or fix a bug? Make sure to take a look at [our contribution guides](https://api-clients-automation.netlify.app/docs/contributing/introduction).
+
+### Setup repository tooling
 
 ```bash
 nvm use && yarn
 ```
 
-## Setup dev environment
+### Setup dev environment
+
+> **Make sure to have Docker installed so you don't have to install the tooling for every API clients.**
 
 ```bash
 yarn docker:setup
 ```
 
 [Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/setup-repository)
 
-## Contributing
+### CLI
 
-You can make changes locally and run commands through the docker container.
+The CLI allows you to make changes locally and run commands through the docker container.
 
-[Specs CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/specs-commands) • [Clients CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/clients-commands) • [CTS CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/cts-commands)
+- [Specs CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/specs-commands)
+- [Clients CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/clients-commands)
+- [CTS CLI commands](https://api-clients-automation.netlify.app/docs/contributing/CLI/cts-commands)
 
-### Build and validate specs
+### Guides and requirements
 
-#### Usage
+Read the guides and requirements to:
 
-```bash
-yarn docker build specs <client | all>
-```
+- [Add a new client](https://api-clients-automation.netlify.app/docs/contributing/add-new-api-client)
+- [Add a new language](https://api-clients-automation.netlify.app/docs/contributing/add-new-api-language)
 
-[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/add-new-api-client)
+### Tests
 
-### Generate clients based on the [`specs`](./specs/)
+Test the generated clients by running:
 
-#### Usage
+- The [`playground`](./playground) (see [documentation](https://api-clients-automation.netlify.app/docs/contributing/testing/playground.md))
+- The [`Common Test Suite`](./tests/) (see [documentation](https://api-clients-automation.netlify.app/docs/contributing/testing/common-test-suite.md)).
 
-```bash
-yarn docker generate <language | all> <client | all>
-```
+For full documentation, visit the **[online documentation](https://api-clients-automation.netlify.app/docs/contributing/introduction)**.
+
+## ❓ Troubleshooting
 
-[Read more on our documentation](https://api-clients-automation.netlify.app/docs/contributing/add-new-language)
+Encountering an issue with the API clients? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/javascript/) where you will find answers to the most common issues and gotchas with the client.
 
-## Testing clients
+You can also [open an issue on GitHub](https://github.com/algolia/api-clients-automation/issues/new/choose).
 
-You can test our generated clients by running:
+## 📄 License
 
-- The playground [`playground`](./playground) ([Playground](https://api-clients-automation.netlify.app/docs/contributing/testing/playground.md))
-- Tests with our [`Common Test Suite`](./tests/) ([Common Test Suite](https://api-clients-automation.netlify.app/docs/contributing/testing/common-test-suite.md)).
+Algolia API clients automation is an open-sourced software licensed under the [MIT license](LICENSE.md).

SECURITY.md

@@ -0,0 +1,3 @@
+## Reporting a Vulnerability
+
+To report a security vulnerability, please use the [Algolia security email]([email protected]). Algolia will coordinate the fix and disclosure.