Document config.ini

docs/car.rst

@@ -57,6 +57,7 @@ The default car definitions of Rally are stored in ``~/.rally/benchmarks/teams/d
         │           └── jvm.options
         ├── ea.ini
         └── vanilla
+            ├── config.ini
             └── templates
                 └── config
                     ├── elasticsearch.yml
@@ -68,8 +69,12 @@ The top-level directory "v1" denotes the configuration format in version 1. Belo
     [variables]
     clean_command=./gradlew clean
 
-This defines the variable ``clean_command`` for all cars that reference this configuration.
+This defines the variable ``clean_command`` for all cars that reference this configuration. Rally will treat the following variable names specially:
 
+* `clean_command`: The command to clean the Elasticsearch project directory.
+* `build_command`: The command to build an Elasticsearch source distribution.
+* `artifact_path_pattern`: A glob pattern to find a previously built source distribution within the project directory.
+* `release_url`: A download URL for Elasticsearch distributions. The placeholder ``{{VERSION}}`` is replaced by Rally with the actual Elasticsearch version.
 
 Let's have a look at the ``1gheap`` car by inspecting ``1gheap.ini``::
 

docs/migrate.rst

@@ -64,6 +64,41 @@ Starting with Rally 0.11.0, Rally will look for a directory "v1" within ``cars``
                 │           └── elasticsearch.yml
                 └── transport.ini
 
+It is also required that you create a file ``variables.ini`` for all your car config bases (optional for mixins). Therefore, the full directory structure is::
+
+    .
+    ├── cars
+    │   └── v1
+    │       ├── 1gheap.ini
+    │       ├── 2gheap.ini
+    │       ├── defaults.ini
+    │       ├── ea
+    │       │   └── templates
+    │       │       └── config
+    │       │           └── jvm.options
+    │       ├── ea.ini
+    │       └── vanilla
+    │           ├── config.ini
+    │           └── templates
+    │               └── config
+    │                   ├── elasticsearch.yml
+    │                   ├── jvm.options
+    │                   └── log4j2.properties
+    └── plugins
+        └── v1
+            ├── core-plugins.txt
+            └── transport_nio
+                ├── default
+                │   └── templates
+                │       └── config
+                │           └── elasticsearch.yml
+                └── transport.ini
+
+For distribution-based builds, ``config.ini`` file needs to contain a section ``variables`` and a ``release_url`` property::
+
+    [variables]
+    release_url=https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-{{VERSION}}.tar.gz
+
 
 Migrating to Rally 0.10.0
 -------------------------