docs: add contribution guides (#150)

algolia · Feb 23, 2022 · c5d423b · c5d423b
1 parent 48571bb
commit c5d423b
Show file tree

Hide file tree

Showing 12 changed files with 209 additions and 93 deletions.
diff --git a/.github/workflows/pr-title.yml b/.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)\)): .+'
diff --git a/README.md b/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
 

diff --git a/doc/contribution_addNewClient.md b/doc/contribution_addNewClient.md
diff --git a/doc/CTS.md → docs/CTS.md b/doc/CTS.md → docs/CTS.md
diff --git a/docs/addNewClient.md b/docs/addNewClient.md
@@ -0,0 +1,96 @@
+# How to add a new client
+
+Adding a client requires a few manual steps in order to setup the tooling, generation scripts and properly generate the code. We recommend getting inspirations from existing clients such as `javascript-recommend`.
+
+> See [README](../README.md) to [`setup the repository tooling`](../README.md#setup-repository-tooling) and [`setup dev environment`](../README.md#setup-dev-environment).
+
+## 1. 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
+
+> Example with the [search client spec](../specs/search/)
+
+#### `spec.yml` file
+
+This file is the entry point of the client spec, it contains `servers`, `paths` and other specific imformations of the API. We recommend to copy an existing [`spec.yml` file](../specs/search/spec.yml) to get started.
+
+#### `<clientName>`/common folder
+
+Properties that are common to the client.
+
+#### `<clientName>`/paths folder
+
+Path definition of the paths defined in the [spec file](#specyml-file)
+
+#### Guidelines
+
+- **Endpoints**: Each file should contain `operationId`s for a single endpoint, but multiple methods are allowed.
+- **Name**: If the path file only contain one method, we name the file same as the `operationId`, but we try to make it less specific if there is multiple.
+- **Description/Summary**: `operationId`s must have both description and summary.
+- **Tags**: The `tags` must match the `<clientName>` spec folder.
+- **Complex objects**: Complex objects (nested arrays, nested objects, etc.) must be referenced (`$ref`) in the `operantionId` file and not inlined. This is required to provide a great naming.
+
+## 2. Configuring the environment
+
+After setting up the dev environment from [README](../README.md) and [writing your spec files](#1-writing-specs), you need to update the configuration files to properly generate clients that are maintainable.
+
+### Generation config
+
+[openapitools.json](../openapitools.json) hosts the configuration of all of the 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 the client.                                                                                                                  |
+| glob               | string  |   Common   |   `path/to/spec/sources.yml`    | The path of the 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
+
+The built clients are cached with the [Cache GitHub Action](../.github/actions/cache/action.yml) to avoid unnecessary 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') }}
+```
+
+## 3. Generate new client
+
+> You can find more commands in the [README](../README.md#generate-all-clients).
+
+```bash
+yarn docker generate <languageName> <clientName>
+```
+
+## 4. Implementing the Common Test Suite
+
+See [CTS.md](./CTS.md) for more informations.
diff --git a/docs/addNewLanguage.md b/docs/addNewLanguage.md
@@ -0,0 +1,77 @@
+# How to add support of a new language
+
+This repository leverages [openapi-generator](https://openapi-generator.tech/) to generate API clients.
+
+> See [README](../README.md) to [`setup the repository tooling`](../README.md#setup-repository-tooling) and [`setup dev environment`](../README.md#setup-dev-environment).
+
+> If not done already, [install openapi-generator](https://openapi-generator.tech/docs/installation/)
+
+## 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)
+
+### 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
+
+### Strip code
+
+The generator includes a lot of features that won't be used with the Algolia engine:
+
+- Multiple authentication methods: `appId`/`apiKey` are the only authentication methods, located in the requests headers.
+- Built-in transporters: A [retry strategy](#retry-strategy) is required to target the DSNs of an `appId`, along with other transporter details listed below.
+- File support, payload format etc.: Requests only require `JSON` support 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 the 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 a 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`).
+
+As the generator does not support reading `servers` in a spec file, hosts methods and variables are extracted with a custom script and create variables for you to use in the mustache templates, [read more here](./addNewClient.md#generators).
+
+### Requesters
+
+> TODO: informations
+
+### Logger
+
+> TODO: informations
+
+### **DX**
+
+We require the generated API clients to have an up-to-date usage with their ecosystem, make sure to provide correct tooling to lint and format generated code.
diff --git a/doc/changelogs/java.md → docs/changelogs/java.md b/doc/changelogs/java.md → docs/changelogs/java.md
diff --git a/doc/changelogs/javascript.md → docs/changelogs/javascript.md b/doc/changelogs/javascript.md → docs/changelogs/javascript.md
diff --git a/doc/changelogs/php.md → docs/changelogs/php.md b/doc/changelogs/php.md → docs/changelogs/php.md
diff --git a/docs/playground.md b/docs/playground.md
@@ -0,0 +1,28 @@
+# 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 <languageName> <clientName>
+```
+
+### JavaScript
+
+```bash
+yarn docker playground javascript search
+```
+
+### Java
+
+```bash
+yarn docker playground java search
+```
+
+## Add new playground
+
+To add a new supported language to the playground, you need to:
+
+- Create a new folder with your `<languageName>` in [the playground folder](../playground/)
+- Edit the [playground script](../scripts/playground.sh) with the command to run it.
diff --git a/openapitools.json b/openapitools.json
@@ -395,4 +395,4 @@
       }
     }
   }
-}
+}
diff --git a/scripts/release/process-release.ts b/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]}`;
-Original file line number
+Diff line change
@@ Expand Up / @@ -395,4 +395,4 @@ @@
           }
         }
       }
-    }
+    }