fix(clients): add generation banner to generated files (#816)

Author: shortcuts

generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java

@@ -30,6 +30,9 @@ public void processOpts() {
 
     super.processOpts();
 
+    // Generation notice, added on every generated files
+    Utils.setGenerationBanner(additionalProperties);
+
     // Prevent all useless file to generate
     apiTestTemplateFiles.clear();
     modelTestTemplateFiles.clear();

generators/src/main/java/com/algolia/codegen/AlgoliaJavaScriptGenerator.java

@@ -32,6 +32,9 @@ public void processOpts() {
     setModelPropertyNaming("original");
     setApiPackage("src");
 
+    // Generation notice, added on every generated files
+    Utils.setGenerationBanner(additionalProperties);
+
     languageSpecificPrimitives.add("Record");
     instantiationTypes.put("map", "Record");
     // clear all supported files to avoid unwanted ones

generators/src/main/java/com/algolia/codegen/AlgoliaPhpGenerator.java

@@ -31,6 +31,9 @@ public void processOpts() {
 
     super.processOpts();
 
+    // Generation notice, added on every generated files
+    Utils.setGenerationBanner(additionalProperties);
+
     // Remove base template as we want to change its path
     supportingFiles.removeIf(file -> file.getTemplateFile().equals("Configuration.mustache"));
 

generators/src/main/java/com/algolia/codegen/Utils.java

@@ -179,4 +179,15 @@ public static JsonNode readJsonFile(String filePath) throws ConfigException {
   public static boolean shouldUseExplicitOneOfName(Collection<String> oneOf) {
     return oneOf.stream().filter(type -> type != null && type.startsWith("List")).count() >= 2;
   }
+
+  /**
+   * Sets a `generationBanner` variable on the mustache templates, to display the generation banner
+   * on generated files.
+   */
+  public static void setGenerationBanner(Map<String, Object> additionalProperties) {
+    additionalProperties.put(
+      "generationBanner",
+      "This file is generated, manual changes will be lost - read more on" + " https://github.com/algolia/api-clients-automation."
+    );
+  }
 }

templates/java/api.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 package {{package}};
 
 import {{invokerPackage}}.ApiClient;

templates/java/model.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 package {{package}};
 
 import java.util.Objects;

templates/javascript/clients/algoliasearch/builds/browser.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 import {
   createMemoryCache,
   createFallbackableCache,

templates/javascript/clients/algoliasearch/builds/models.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 import type {
   Host,
   Requester,

templates/javascript/clients/algoliasearch/builds/node.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 import {
   DEFAULT_CONNECT_TIMEOUT_NODE,
   DEFAULT_READ_TIMEOUT_NODE,

templates/javascript/clients/api-single.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 {{> client/api/imports}}
 
 export const apiClientVersion = '{{packageVersion}}';

templates/javascript/clients/client/builds/browser.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 import { createXhrRequester } from '{{{npmNamespace}}}/requester-browser-xhr';
 import { DEFAULT_CONNECT_TIMEOUT_BROWSER, DEFAULT_READ_TIMEOUT_BROWSER, DEFAULT_WRITE_TIMEOUT_BROWSER } from '{{{npmNamespace}}}/client-common';
 {{> client/builds/imports}}

templates/javascript/clients/client/builds/node.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 import { createHttpRequester } from '{{{npmNamespace}}}/requester-node-http';
 import { DEFAULT_CONNECT_TIMEOUT_NODE, DEFAULT_READ_TIMEOUT_NODE, DEFAULT_WRITE_TIMEOUT_NODE } from '{{{npmNamespace}}}/client-common';
 {{> client/builds/imports}}

templates/javascript/clients/client/model/clientMethodProps.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 {{#apiInfo.apis.0}}
 
 {{#imports}}

templates/javascript/clients/client/model/modelBarrel.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 {{#models}}
 {{#model}}
 export * from '{{{ classFilename }}}';

templates/javascript/clients/model.mustache

@@ -1,3 +1,5 @@
+// {{{generationBanner}}}
+
 {{#models}}{{#model}}
 {{#tsImports}}
 import { {{classname}} } from '{{filename}}';

templates/php/ApiException.mustache

@@ -1,3 +1,4 @@
+// {{{generationBanner}}}
 <?php
 
 namespace {{invokerPackage}};

templates/php/ConfigWithRegion.mustache

@@ -1,4 +1,5 @@
 <?php
+// {{{generationBanner}}}
 
 namespace {{invokerPackage}}\Configuration;
 

templates/php/Configuration.mustache

@@ -1,4 +1,5 @@
 <?php
+// {{{generationBanner}}}
 
 namespace {{invokerPackage}}\Configuration;
 

templates/php/ModelInterface.mustache

@@ -1,4 +1,5 @@
 <?php
+// {{{generationBanner}}}
 
 namespace {{modelPackage}};
 

templates/php/ObjectSerializer.mustache

@@ -1,4 +1,5 @@
 <?php
+// {{{generationBanner}}}
 
 namespace {{invokerPackage}};
 

templates/php/api.mustache

@@ -1,4 +1,5 @@
 <?php
+// {{{generationBanner}}}
 
 namespace {{apiPackage}};
 

templates/php/client_config.mustache

@@ -1,4 +1,5 @@
 <?php
+// {{{generationBanner}}}
 
 namespace {{invokerPackage}}\Configuration;
 

templates/php/model.mustache

@@ -1,4 +1,6 @@
 <?php
+// {{{generationBanner}}}
+
 {{#models}}
 {{#model}}
 

website/docs/contributing/add-new-language.md

@@ -93,12 +93,12 @@ The resulting User Agent is the concatenation of `base`, then `client` and all t
 
 For example, if we have:
 
- - base: `Algolia for Java (4.0.0)`
- - client: `; Search (4.0.0)`
- - segment: 
-    - `; JVM (11.0.14)`
-    - `; experimental`
-    - `; test (8.0.0-beta)`
+- base: `Algolia for Java (4.0.0)`
+- client: `; Search (4.0.0)`
+- segment:
+  - `; JVM (11.0.14)`
+  - `; experimental`
+  - `; test (8.0.0-beta)`
 
 Then the resulting User Agent is (the order is arbitrary):
 
@@ -109,6 +109,7 @@ Algolia for Java (4.0.0); JVM (11.0.14); Search (4.0.0); experimental ; test (8.
 You can take a look at the Java implementation [here](https://github.com/algolia/api-clients-automation/pull/347).
 
 The `User-Agent` MUST match the following regular expression:
+
 ```regex
 ^Algolia for <LANGUAGE> \\(\\d+\\.\\d+\\.\\d+(-.*)?\\)(; [a-zA-Z. ]+ (\\(\\d+((\\.\\d+)?\\.\\d+)?(-.*)?\\))?)*(; <CLIENT> (\\(\\d+\\.\\d+\\.\\d+(-.*)?\\)))(; [a-zA-Z. ]+ (\\(\\d+((\\.\\d+)?\\.\\d+)?(-.*)?\\))?)*$
 ```
@@ -140,13 +141,19 @@ You can take a look at the implementation over all clients, [in this pull reques
 
 Every methods of every clients provide a parameter that does not exist in the REST API, called `requestOptions`.
 
-This parameter **must** be the last parameter of a method, and allow a user to override/merge additional `query parameters` or `headers` with the transporter ones.
+This parameter MUST be the last parameter of a method, and allow a user to override/merge additional `query parameters` or `headers` with the transporter ones.
 
 ### Requesters
 
-The requester needs to be configurable and capable to be overwriten to use a user defined requester.
+The requester needs to be configurable and capable to be overwritten to use a user defined requester.
 The default requester must be the classic HTTP requester, and it's possible to provide other alternatives like an [Echo Requester](https://github.com/algolia/api-clients-automation/blob/main/clients/algoliasearch-client-javascript/packages/client-common/src/createEchoRequester.ts) that just send the request back.
 
 ### Logger
 
-> TODO: informations
+> TODO: information
+
+### Generated file banner
+
+The banner SHOULD be added at the very top of every generated files, to avoid confusion for our users, but also redirect them to the `api-clients-automation` monorepo, where the contribution happens.
+
+To do so, a `generationBanner` variable is available on every `mustache` templates, see [the initial implementation](https://github.com/algolia/api-clients-automation/pull/816) for more context.