diff --git a/content/en/docs/refguide/modeling/menus/file-menu/_index.md b/content/en/docs/refguide/modeling/menus/file-menu/_index.md
index 016d670997c..7c1d0fafab1 100644
--- a/content/en/docs/refguide/modeling/menus/file-menu/_index.md
+++ b/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. | Ctrl + Shift + W |
| **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 reduced repository growth to ensure good 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 | |
diff --git a/content/en/docs/refguide/version-control/_index.md b/content/en/docs/refguide/version-control/_index.md
index a3e904c61a4..aa997c3980f 100644
--- a/content/en/docs/refguide/version-control/_index.md
+++ b/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 *.mpr* to a new [MPRv2 storage format](/refguide/troubleshoot-repository-size/#mpr-format) to slow down the repository growth and 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 %}}
diff --git a/content/en/docs/refguide/version-control/version-control-troubleshooting/repository-size.md b/content/en/docs/refguide/version-control/version-control-troubleshooting/repository-size.md
index fa257aebb67..30c9b8f032e 100644
--- a/content/en/docs/refguide/version-control/version-control-troubleshooting/repository-size.md
+++ b/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,29 +42,43 @@ 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.
+Studio Pro 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, are no longer stored as part of the *.mpr* file but as separate files in the *mprcontents* directory. The *.mpr* file functions as an index file pointing to all the different files on disk.
+
+This means that when you change one document, for example, a page, only a small file representing that page will change on disk. This allows Git to calculate an efficient delta and results in a more appropriate repository growth compared to MPRv1. Functionally there is 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, Mendix recommends migrating the most active branches to MPRv2 the 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 using the command line with `git merge` or by using third-party tools is not yet supported for MPRv2.
{{% /alert %}}
-#### Decreasing MPR File Size
+#### Converting MPR Storage Format {#convert}
-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.
+Upgrading to the new format is optional and can be done per branch via the [File menu](/refguide/file-menu/). To upgrade to MPRv2, open your app and select **File > Upgrade app to split MPR format (v2)**. After a confirmation the app will be converted and you will be prompted to commit.
-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:
+You can also downgrade branches that are already on MPRv2 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 fails.
+{{% /alert %}}
+
+### 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, consider doing the following:
+* [Convert to MPRv2](#convert) – By splitting the single binary file into multiple files, your file size 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/mx-command-line-tool/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/mx-command-line-tool/analyze-mpr/) of the [mx Command-Line Tool](/refguide/mx-command-line-tool/) to analyze how your MPR file builds up. The output shows how many documents of a certain type (for example, the number of pages) exist and how much disk space they represent within the MPR file. Mendix recommends starting with a quick scan to see whether there is an unexpected number of occurrences (for example, 1500 pages) or a large number of bytes (over 50 000 000 bytes) for a unit type.
### Working with a Large Repository Size
When cloning an app, the default behavior of Git is to download the full history. As Mendix uses different folders on disk for different branches, downloading full history is done for each branch. To mitigate that, Mendix uses local cloning for subsequent branch downloads. When cloning a new branch, data from a local branch you already have is used to reduce data that needs to be downloaded.
-As of Mendix 10.12 it is possible to prevent downloading the full history, by changing the [Clone type](/refguide/clone-type/) to use partial clones. A partial clone downloads all data for a specific revision without downloading the contents of all historical commits.
+Starting from Studio Pro 10.12 it is possible to prevent downloading the full history, by changing the [Clone type](/refguide/clone-type/) to use partial clones. A partial clone downloads all data for a specific revision without downloading the contents of all historical commits.
### Mitigating Large Repository Size
@@ -107,6 +119,7 @@ To conclude whether the situation is acceptable for you, follow these steps:
* Ensure the Git app you are downloading is not yet on your machine
* Download the branch through Studio Pro, while manually measuring how long the download takes
+
The first download of a branch on a device is a good indication of the maximum waiting time you or your team member can experience. Subsequent branch downloads use data that is already available locally and will, therefore, be a lot faster.
If the download time was acceptable, or if you have a process where team members do not change often and they do not have to download an app for the first time, you can skip the cleanup.
@@ -202,6 +215,7 @@ We recommend doing the following:
* Check your git config settings, especially any setting that involves encoding or text conversions: run `git config --list --show-origin`.
* Consider moving your local repo, so that its folder has a shorter name
+
When reaching out to Mendix Support, please include:
* App/Projects ID for your app
diff --git a/static/attachments/refguide/modeling/menus/file-menu/file-menu.png b/static/attachments/refguide/modeling/menus/file-menu/file-menu.png
index 2a13a8a5fef..3559e0fcac7 100644
Binary files a/static/attachments/refguide/modeling/menus/file-menu/file-menu.png and b/static/attachments/refguide/modeling/menus/file-menu/file-menu.png differ