docs: add contribution guides

.github/workflows/pr-title.yml

@@ -16,4 +16,4 @@ jobs:
       - name: Pull Request title rules
         uses: deepakputhraya/[email protected]
         with:
-          regex: '^(?:(feat)|(fix)|(docs)|(style)|(refactor)|(perf)|(test)|(build)|(ci)|(chore)|(revert))\((?:(javascript)|(php)|(java)|(cts)|(spec)|(script)|(ci))\): .+'
+          regex: '^(docs)|((?:feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\((?:javascript|php|java|cts|spec|script|ci)\)): .+'

README.md

@@ -22,6 +22,8 @@ yarn docker:setup
 
 Build docker image from [Dockerfile](./Dockerfile)
 
+[How to add a new client](./docs/addNewClient.md) | [How to add a new language](./docs/addNewLanguage.md) | [Common Test Suite](./docs/CTS.md) | [Run the playground](./docs/playground.md)
+
 ```bash
 yarn docker:build
 ```
@@ -111,31 +113,10 @@ yarn docker build:clients java recommend
 
 ## Testing clients
 
-The clients can be tested inside the [`playground`](./playground) folder and with the [common test suite (CTS)](./doc/CTS.md)
-
-### Usage
-
-```bash
-yarn docker playground <language> <client>
-```
-
-### JavaScript
-
-```bash
-yarn docker playground javascript search
-```
-
-#### Browser
-
-```bash
-yarn playground:browser
-```
-
-### Java
+You can test our generated clients by running:
 
-```bash
-yarn docker playground java search
-```
+- The playground [`playground`](./playground) ([Playground README](./docs/playground.md))
+- Tests with our [`Common Test Suite`](./tests/) ([CTS README](./docs/CTS.md)).
 
 # Troubleshooting
 

docs/addNewClient.md

@@ -0,0 +1,78 @@
+# How to add a new client
+
+> Adding a client requires a few manual steps in order to setup our tooling, generation scripts and properly generate the code. We recommend getting inspirations from existing clients such as `javascript-recommend`.
+
+> See [README](../README.md) for the repository commands
+
+## Configuring the environment
+
+After following the repository [README](../README.md), you need to update our configuration files to properly generate clients that are maintainable.
+
+### Generation config
+
+> [openapitools.json](../openapitools.json) hosts the configuration of all of our generated clients with their available languages.
+
+#### `generators`
+
+> Generators are referenced by key with the following pattern `<languageName>-<clientName>`.
+
+> TODO: Automate this step.
+
+You can copy an existing object of a client and replace the `<clientName>` value with the one you'd like to generate.
+
+| Option             |  Type   |  Language  |             Example             |                                                                   Definition                                                                    |
+| ------------------ | :-----: | :--------: | :-----------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------: |
+| output             | string  |   Common   | `path/to/client/client-sources` |                                                         The output path of your client.                                                         |
+| glob               | string  |   Common   |   `path/to/spec/sources.yml`    |                                                       The path of your bundled spec file.                                                       |
+| gitRepoId          | string  |   Common   |  `algoliasearch-client-java-2`  |                                                The name of the repository under the Algolia org.                                                |
+| apiName            | string  | JavaScript |            `search`             |                                                     The lowercase name of the exported API.                                                     |
+| capitalizedApiName | string  | JavaScript |            `Search`             |                                                    The capitalized name of the exported API.                                                    |
+| packageVersion     | string  | JavaScript |             `1.2.3`             |              The version you'd like to publish the first iteration of the generated client. It will be automatically incremented.               |
+| packageName        | string  |   common   |         `AlgoliaSearch`         |                                                Name of the API package, used in [CTS](./CTS.md).                                                |
+| hasRegionalHost    | boolean |   common   |             `false`             | Automatically guessed from `servers` in spec. `undefined` implies that hosts used will required the `appId`, regional hosts are used otherwise. |
+| isDeHost           | boolean |   common   |             `false`             |                Automatically guessed from `servers` in spec. `undefined` implies that `eu` is the regional host, `de` otherwise.                |
+| host               | string  |   common   |            `crawler`            |                                                  Automatically guessed from `servers` in spec.                                                  |
+| topLevelDomain     | string  |   common   |              `io`               |                                                  Automatically guessed from `servers` in spec.                                                  |
+
+### GitHub actions
+
+> We cache built clients with the [Cache GitHub Action](../.github/actions/cache/action.yml) to avoid useless CI tasks.
+
+> TODO: Automate this step
+
+You can copy [an existing client caching step](../.github/actions/cache/action.yml) or edit the following example:
+
+```yaml
+- name: Restore built <LANGUAGE> <CLIENT_NAME> client
+  if: ${{ inputs.job == 'cts' }}
+  uses: actions/cache@v2
+  with:
+    path: /home/runner/work/api-clients-automation/api-clients-automation/clients/<LANGUAGE_FOLDER>/<CLIENT_NAME>/<CLIENT_BUILD_PATH>
+    key: ${{ runner.os }}-${{ env.CACHE_VERSION }}-<LANGUAGE>-<CLIENT_NAME>-${{ hashFiles('clients/<LANGUAGE_FOLDER>/<CLIENT_NAME>/**') }}-${{ hashFiles('specs/bundled/<CLIENT_SPEC>.yml') }}
+```
+
+## Writing specs
+
+> We recommend to have a look at [existing spec files](../specs/).
+
+> The `bundled` folder is automatically generated, manual changes shouldn't be done in these files.
+
+### [common spec folder](../specs/common/)
+
+Properties that are common to Algolia or used in multiple clients.
+
+### [clientName spec folder](../specs/search)
+
+#### [spec file](../specs/search/spec.yml)
+
+> We recommend to copy an of existing [spec file](../specs/search/spec.yml) and edit the `paths` and `servers
+
+This file is the entry point of the spec, it contains `servers` and `paths` of your API spec.
+
+#### [spec common folder](../specs/search/common)
+
+Properties that are common to your client.
+
+#### [paths folder](../specs/search/paths)
+
+Path definition of the paths defined in your [spec file](../specs/search/spec.yml)

docs/addNewLanguage.md

@@ -0,0 +1,79 @@
+# How to add support of a new language
+
+> We use [openapi-generator](https://openapi-generator.tech/) to generate API clients.
+
+> See [README](../README.md) for the repository commands
+
+## Find a template to start with
+
+> Provided templates should be a good starting point to generate a client but make sure to implement the [Algolia requirements](#algolia-requirements) to make it work properly.
+
+You can pick a default template on the [openapi-generator's "generators" page](https://openapi-generator.tech/docs/generators)
+
+> [Install openapi-generator](https://openapi-generator.tech/docs/installation/)
+
+### Extract the template locally
+
+```bash
+openapi-generator author template -g <YOUR_TEMPLATE_NAME> -o templates/<YOUR_API_CLIENT_NAME>
+```
+
+Example for the JavaScript client with the `typescript-node` template:
+
+```bash
+openapi-generator author template -g typescript-node -o templates/javascript/
+```
+
+## Update the generator config
+
+Add each client in the file [`openapitools.json`](../openapitools.json), following the others client structure.
+
+> See [How to add a new client](./addNewClient.md) for informations regarding this file
+
+### Algolia requirements
+
+API clients require custom Algolia logic in order to work with our engine.
+
+### Strip code
+
+The generator includes a lot of useless features that we don't use:
+
+- Multiple authentication methods: We only use `appId`/`apiKey` authentication methods in headers.
+- Built-in transporters: The engine requires a [retry strategy](#retry-strategy) and a lot of other features, you need to implement it.
+- File support, payload format etc.: We only need to support JSON to communicate with the engine.
+
+**DX is key, make sure to provide a linter and formatting tools, with consistent method usage based on the language.**
+
+### Init method
+
+By default, OpenAPI will put the `AppId` and `ApiKey` in every method parameters, but our clients to be initialized with those values and put them in the header of every requests, with the right hosts.
+
+The constructor of the client can be edited (from the `.mustache` files) to accept and store those values.
+
+- [First implementation on the JavaScript client](https://github.com/algolia/api-clients-automation/pull/7)
+- [Current implementation on the JavaScript client](https://github.com/algolia/api-clients-automation/blob/main/clients/algoliasearch-client-javascript/packages/client-search/src/searchApi.ts#L110-L125)
+
+### Retry strategy
+
+The retry strategy cannot be generated and needs to be implemented outside of the generated client folder. You can achieve this by creating a `utils` (or any naming that you find relevant) folder and add your transporter and retry strategy logic to it.
+
+- [First implementation on the JavaScript client](https://github.com/algolia/api-clients-automation/pull/9)
+- [Current implementation on the PHP client](https://github.com/algolia/api-clients-automation/tree/main/clients/algoliasearch-client-php/lib/RetryStrategy)
+
+### Different client hosts
+
+Some Algolia clients (search and recommend) targets the default appId host (`${appId}-dsn.algolia.net`, `${appId}.algolia.net`, etc.), while clients like `personalization` have their own regional `host` (`eu` | `us` | `de`).
+
+We guess those hosts methods and variables by reading the `servers` in your spec file and create variables for you to use in your templates, [read more here](./addNewClient.md).
+
+### Requesters
+
+> TODO: informations
+
+### Logger
+
+> TODO: informations
+
+### **DX**
+
+We require our API clients to have an up-to-date usage with their ecosystem, make sure to provide correct tooling to lint and format your generate code.

docs/playground.md

@@ -0,0 +1,21 @@
+# Playground
+
+> All of the existing clients should have an active playground for you to test generated clients, if it's not the case, consider contributing or letting us know!
+
+## Usage
+
+```bash
+yarn docker playground <language> <client>
+```
+
+### JavaScript
+
+```bash
+yarn docker playground javascript search
+```
+
+### Java
+
+```bash
+yarn docker playground java search
+```

openapitools.json

@@ -395,4 +395,4 @@
       }
     }
   }
-}
+}

scripts/release/process-release.ts

@@ -92,7 +92,7 @@ fs.writeFileSync(
 // update changelogs
 new Set([...Object.keys(versionsToRelease), ...langsToUpdateRepo]).forEach(
   (lang) => {
-    const filePath = path.resolve(ROOT_DIR, `doc/changelogs/${lang}.md`);
+    const filePath = path.resolve(ROOT_DIR, `docs/changelogs/${lang}.md`);
     const header = versionsToRelease[lang!]
       ? `## ${versionsToRelease[lang!].next}`
       : `## ${new Date().toISOString().split('T')[0]}`;
@@ -112,7 +112,7 @@ new Set([...Object.keys(versionsToRelease), ...langsToUpdateRepo]).forEach(
 run('git config user.name "api-clients-bot"');
 run('git config user.email "[email protected]"');
 run('git add openapitools.json');
-run('git add doc/changelogs/*');
+run('git add docs/changelogs/*');
 execa.sync('git', ['commit', '-m', TEXT.commitMessage]);
 run(`git push origin ${MAIN_BRANCH}`);