Add explanations of Tonel format versions

General/ExportFormats.md

@@ -12,6 +12,7 @@ This page will present formats from the most recommended for new projects to the
 - [Tonel](#tonel)
   * [Tonel Pros and Cons](#tonel-pros-and-cons)
   * [Tonel supported Pharo versions](#tonel-supported-pharo-versions)
+  * [Tonel versions](#tonel-versions)
 - [FileTree metadata less](#filetree-metadata-less)
   * [FileTree metadata less Pros and Cons](#filetree-metadata-less-pros-and-cons)
   * [FileTree metadata less supported Pharo versions](#filetree-metadata-less-supported-pharo-versions)
@@ -85,6 +86,34 @@ Metacello new
 	load.
 ```
 
+### Tonel versions
+
+Tonel got multiple versions over the years, each tweaking the export format:
+- version 1.0: original tonel export format
+- version 2.0: this version ensure that in the metadatas the keys are symbols and the values are strings. This change happened in order to be compatible with Gemstone. Note that this format was never used as a default export format of Pharo
+- version 3.0: this version has the changes of the 2.0 but it also adds the properties `package` and `tag` to replace the `category` property for class definitions. This is to remove same ambiguity in the class definitions. The `category` property is kept by default for backward compatibility, but the TonelWriter can be configured to not export this property. This format can also be improved to export more metadata. For example, it is planned to export a property `deprecatedAliases` to manage some class deprecations in the future.
+
+If you want to change you export format and convert all the files of a repository at once to avoid to have multiple PR with format changes you can use this script and commit the resulting files:
+
+```st
+| projectName |
+projectName := 'ProjectNameInIceberg'.
+repository := IceRepository repositories detect: [ :repo | repo name = projectName ].
+repository workingCopy packages do: [ :pkg |
+IceLibgitTonelWriter forInternalStoreFileOut: pkg latestVersion mcVersion on: repository ]
+```
+
+Since Pharo 12, it is also possible to indicate in a Tonel project which version of Tonel to use to export some code. The file to update is the `.properties` file that is in the source folder and it should look like this:
+
+```
+{
+    #format : #tonel,
+    #version: #'1.0' //could be 2.0 or 3.0
+}
+```
+
+This is useful for example if a project has contributors on P11 using v1 format and contributors in P12 using v3 format since P11 is unable to export Tonel v3 format. 
+
 ## FileTree metadata less 
 
 FileTree ([https://github.com/dalehenrich/filetree](https://github.com/dalehenrich/filetree)) is the first export format that was integrated in the goal to use Pharo with Git. The first version had a lot of metadata (see section Filetree metadata full), the second was a new version with metadata less format.