Added MPRv2 explanation, limitations and conversion

content/en/docs/refguide/modeling/menus/file-menu/_index.md

@@ -27,6 +27,7 @@ The **File** menu items are described in the table below:
 | **Close All**              | Closes all document tabs. You will be asked to save or discard changes when needed. | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>W</kbd> |
 | **Close App**          | Closes the currently open App and returns to the home page. |                                                   |
 | **Export as Image**        | Exports the current document as an image in the *.png* format. The following document types can be exported as images: domain models, workflows, document templates. |                                                   |
+| **Upgrade app to split MPR format (v2)**        | Converts the file storage format of the current branch. The [MPRv2 storage format](/refguide/troubleshoot-repository-size/#mpr-format) results in increased performance over time. |                                                   |
 | **Export App Package** | Exports the current app to a package (*.mpk*) file. This is useful for example when you want to give someone the entire app, or when you need to provide a test app when submitting a ticket. For more information, see [Export App Package](/refguide/export-app-package-dialog/). |                                                   |
 | **Import App Package** | Imports a package that was created with the **Export App Package** menu item. For more information, see [Import App Package](/refguide/import-app-package-dialog/). |                                                   |
 | **Exit**                   | Closes Studio Pro                                            |                                                   |

content/en/docs/refguide/version-control/_index.md

@@ -94,10 +94,14 @@ A Tag is a way of identifying a commit in addition to the [revision](#revision)
 
 The Repository Service manages communication between Studio Pro and other supporting services (for example, Team Server). The developer will not generally be aware that they are communicating via the Repository Service.
 
-### Mendix MPR Storage  {#mpr-format}
+### Mendix MPR Storage {#mpr-format}
 
 An app modeled in Mendix is stored in an *.mpr* file, a database that contains data on all documents, such as microflows, workflows, pages. Studio Pro or the [mx Command-Line Tool](/refguide/mx-command-line-tool/) is required to inspect changes in the *.mpr*.
 
+{{% alert color="info" %}}
+Studio Pro 10.18 introduced a public beta to convert to the new [MPRv2 storage format](/refguide/troubleshoot-repository-size/#mpr-format), to slow down repository growth to prevent degrading performance.
+{{% /alert %}}
+
 {{% alert color="warning" %}}
 Manually modifying files belonging to the *.mpr* storage format such as the *.mpr* file or the *mprcontents* directory (for example, when resolving file conflicts through third-party tooling), will lead to a corrupted state. To recover from a corrupted state a previous commit will need to be restored.
 {{% /alert %}}

content/en/docs/refguide/version-control/version-control-troubleshooting/repository-size.md

@@ -30,11 +30,9 @@ Other places where you might encounter performance issues or timeouts are the fo
 
 ## Preventing and Mitigating a Large Repository Size
 
-### Preventing a Large Repository Size in the Future
+### MPR storage format {#mpr-format}
 
-The [*.mpr* storage format](/refguide/version-control/#mpr-format) will be changed to reduce the rapid repository growth. Switching to the new storage format will be done under the hood and does not result in functional changes inside Studio Pro.
-
-#### Traditional MPR Format
+#### Traditional MPRv1 Format
 
 An app modeled in Mendix is traditionally stored in a single *.mpr* file. This is essentially a database which contains data for all documents, such as microflows, workflows, pages. As the Mendix app is stored in a single file, your version control system only sees that a single file is changed. To show the exact documents that have changed inside the *.mpr* file a tool that comprehends the format is required, such as Studio Pro.
 
@@ -44,24 +42,37 @@ Version control systems like Git do not store a full copy of a document for ever
 
 #### MPRv2 Format
 
-Mendix will introduce a new version of the *.mpr* format: MPRv2. The key difference is that all documents, such as microflows, will no longer be stored as part of the *.mpr* file but as separate files in the *mprcontents* directory. The *.mpr* file will function as an index file pointing to all the different files on disk. 
+Mendix 10.18 introduced a public beta of the new version of the *.mpr* format: MPRv2. The key difference is that all documents, such as microflows, will no longer be stored as part of the *.mpr* file but as separate files in the *mprcontents* directory. The *.mpr* file will function as an index file pointing to all the different files on disk. 
+
+This means that when you change one document, for example a page, that only the small file representing that page will change on disk. This allows Git to calculate an efficient delta, which results in a more appropriate repository growth compared to MPRv1. Functionally there will be no differences between the split (v2) or the combined (v1) format inside Studio Pro. 
 
-This means that when you change one document, for example a page, that only the small file representing that page will change on disk. This allows Git to calculate an efficient delta, which results in a more appropriate repository growth. Functionally there will be no differences between the split (v2) or the combined (v1) format inside Studio Pro. 
+{{% alert color="info" %}}
+Collaborating within one app on MPRv1 and MPRv2 branches is possible. To limit repository growth as much as possible, we recommend migrating the branches with most activity to MPRv2 first.
+{{% /alert %}}
 
 {{% alert color="warning" %}}
-Manually modifying files belonging to the  [*.mpr* storage format](/refguide/version-control/#mpr-format) such as the *.mpr* file or the *mprcontents* directory (for example, when resolving file conflicts through third-party tooling), will lead to a corrupted state. To recover from a corrupted state a previous commit will need to be restored.
+[Merging and diffing commands](/refguide/mx-command-line-tool/#merging-and-diffing-commands) on the command line through *mx.exe* are not yet supported for MPRv2.
+{{% /alert %}}
+
+#### Converting MPR storage format
+
+Upgrading to the new format is opt-in and can be executed on a per-branch basis through the [File menu](/refguide/file-menu/). To upgrade to MPRv2, open your app and select **File > Upgrade app to split MPR format (v2)**. After confirmation the app will be converted and you will be prompted to commit.
+
+For branches already on MPRv2 you can choose to downgrade to MPRv1, by selecting **File > Downgrade app to combined MPR format (v1)**.
+
+{{% alert color="info" %}}
+Before converting the MPR format it is recommended to commit your local work to ensure there is an isolated commit with the conversion step for debugging, in case conversion failed.
 {{% /alert %}}
 
-#### Decreasing MPR File Size
+### Decreasing MPRv1 File Size
 
 When a file exceeds the Git compression threshold, 512 MB by default, Git will store a full copy of the file with each new revision instead of only storing the delta. This results in extremely rapid repository growth with both client and server-side consequences.
 
 As the Mendix model is stored in a single file, this threshold can be exceeded by the *.mpr* file. To decrease the MPR file size, you consider doing the following:
-
+* Convert to MPRv2 - By splitting the single binary file into multiple files, your files will drop below the compression threshold.
 * Remove [excluded and unused documents](/refguide/dev-best-practices/#excluded-and-unused-documents) – If you have a large number of unnecessary documents in your app model, this can significantly increase the size of the MPR file.
 * Decrease duplication in pages – If you have a number of pages featuring the same content, such as an advanced datagrid, consider extracting this piece of logic to a widget. Reusing a widget on multiple pages prevents the data from being saved several times and can have a large impact on the size of the MPR file.
-
-You can use [analyze-mpr](/refguide/analyze-mpr/) of the [mx Command-Line Tool](/refguide/mx-command-line-tool/) to analyze how your MPR file is built up. The output will show how many documents of a type (ie. number of pages) exist and how much disk space they represent within the MPR file. We recommend starting with a brief scan to see if there is an unexpected number of occurences (ie 1500 pages) or large number of bytes (over 50.000.000 bytes) for a unit type.
+* You can use [analyze-mpr](/refguide/analyze-mpr/) of the [mx Command-Line Tool](/refguide/mx-command-line-tool/) to analyze how your MPR file is built up. The output will show how many documents of a type (ie. number of pages) exist and how much disk space they represent within the MPR file. We recommend starting with a brief scan to see if there is an unexpected number of occurences (ie 1500 pages) or large number of bytes (over 50.000.000 bytes) for a unit type.
 
 ### Working with a Large Repository Size