Samples-folder.md

@@ -5,9 +5,17 @@ Output: `samples/`
 
 TODO:
 
-* document and explain `samples.ci/`
 * explain `ensure-up-to-date` script [#80](https://github.com/OpenAPITools/openapi-generator/issues/80)
 
+### samples.ci folder
+
+In an ideal world, we consider that contributors always can remove a specific output in the `samples/` folder and re-generate it from the corresponding `bin/*.sh` script.
+
+This is not always the case, as our CI-Jobs sometimes need additional items that are not generated by the generator. For example maven is used to orchestrate the execution of the tests in each samples. As a consequence, a `pom.xml` file is requested in the generated sample. The generator does not create it, because this is uncommon to use maven to compile and test a sample in an other language (ruby, typescript, ...).
+
+The idea to solve this project is to have an other folder [`samples.ci/`](https://github.com/OpenAPITools/openapi-generator/tree/master/CI/samples.ci) that contains the manually written items that are copied to the `samples/` folder after generation of the example project.
+
+
 ## Scripts
 
 Table to find the script corresponding to an output folder in the `samples/` folder (this help to (re)generate one of the example):