[WIP][CCR-66] Ref guide for texutal compare revisions

content/en/docs/refguide/modeling/menus/version-control-menu/history-dialog.md

@@ -41,6 +41,14 @@ For each revision the following information is shown, more information about eac
 
 By selecting a revision in this grid, the tabs below the grid will be filled with information about this revision.
 
+### Comparing Revisions
+
+You can compare any revision to your current working state by right-clicking a revision and selecting **Compare to current state**. This opens the [Comparison Pane](/refguide/comparison-pane/), which shows all differences between the selected revision and your current state, including uncommitted changes.
+
+{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/history-right-click-menu.png" alt="Compare to current state in History pane right-click menu" class="no-border" >}}
+
+For more information, see [Comparing Revisions](/refguide/comparing-revisions/).
+
 #### Revision{#revision}
 
 A unique alphanumeric identifier of the revision in the repository. The revision identifier is the Git hash for the commit and is unique for a whole repository.
@@ -95,4 +103,6 @@ This tab shows a list of stories that are related to the changes.
 
 * [Version Control](/refguide/version-control/)
 * [Stories Pane](/refguide/stories-pane/)
-* [Using Version Control History](/refguide/version-control-using-history/)
+* [Using Version Control History](/refguide/version-control-using-history/)
+* [Comparison Pane](/refguide/comparison-pane/)
+* [Comparing Revisions](/refguide/comparing-revisions/)

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

@@ -68,6 +68,10 @@ This pane has two levels, so when you zoom into a changed document, you can revi
 
 <video width="640" height="360" controls src="/attachments/refguide/view-menu/changes.mp4">VIDEO</video>
 
+### Comparison
+
+The [Comparison](/refguide/comparison-pane/) pane shows the differences between a selected historical revision and your current working state, allowing you to see what documents, elements, and properties changed.
+
 ### History {#history-pane}
 
 The non-blocking History pane shows commits in your repository and allows you to search and navigate to modified documents without closing the history view.

content/en/docs/refguide/modeling/menus/view-menu/changes-pane.md

@@ -9,6 +9,10 @@ description: "Describes the Changes pane in Mendix Studio Pro."
 
 For version control enabled apps (apps with Team Server or other Git servers), the **Changes** pane shows the local changes to the app since the last commit. You can commit changes, update to the latest revision, and view the history from it. 
 
+{{% alert color="info" %}}
+The **Changes** pane shows your local changes since the last commit. To compare any historical revision to your current state, use the [Comparison Pane](/refguide/comparison-pane/) instead. For more information, see [Comparing Revisions](/refguide/comparing-revisions/).
+{{% /alert %}}
+
 This pane consists of the following:
 
 * The [top bar](#top-bar) contains various buttons, such as **Back**, **Go to**, **Tasks**. 
@@ -141,4 +145,6 @@ The left and right panes will contain the same information as in [Zoomed-In Leve
 ## Read More
 
 * [Studio Pro Overview](/refguide/studio-pro-overview/)
-* [Version Control](/refguide/version-control/) 
+* [Version Control](/refguide/version-control/)
+* [Comparison Pane](/refguide/comparison-pane/)
+* [Comparing Revisions](/refguide/comparing-revisions/) 

content/en/docs/refguide/modeling/menus/view-menu/comparison-pane.md

@@ -0,0 +1,166 @@
+---
+title: "Comparison Pane"
+url: /refguide/comparison-pane/
+weight: 25
+description: "Describes the Comparison Pane in Mendix Studio Pro for comparing a revision to the current state of a version-controlled app."
+---
+
+## Introduction
+
+The **Comparison Pane** shows the differences between a selected historical revision and your current working state in a version-controlled app. This pane displays three levels of detail: which documents changed, which elements within those documents changed, and which property values differ.
+
+This feature requires a version-controlled app. For apps without version control, the Comparison Pane is disabled.
+
+## Accessing the Comparison Pane
+
+To compare a revision to your current state:
+
+1. Open the History pane by clicking **View** > **History**.
+2. Right-click any revision in the list.
+3. Select **Compare to current state**.
+
+{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/history-right-click-menu.png" alt="Compare to current state option in History pane right-click menu" class="no-border" >}}
+
+The Comparison Pane opens and shows all differences between the selected revision and your current working state, including any uncommitted changes.
+
+## Version Compatibility
+
+{{% alert color="warning" %}}
+When comparing revisions created in older versions of Studio Pro, the models are converted on-the-fly to the current Studio Pro version format. Due to this automatic conversion, the displayed older revision may not be 100% identical to the original model. This is a normal part of the version upgrade process and does not affect your actual stored revisions.
+{{% /alert %}}
+
+## Comparison Pane Structure
+
+The Comparison Pane shows information at three levels:
+
+* **Level 1** – A list of all documents that differ between the two revisions
+* **Level 2** – All elements within a selected document that have changed
+* **Level 3** – The specific property values that differ for a selected element
+
+You can navigate between levels by double-clicking a row or using the **Go to** button. Press <kbd>Backspace</kbd> or click **Back** to return to the previous level.
+
+## Unversioned App State
+
+If your app does not have version control enabled, all buttons in the Comparison Pane are disabled and a message indicates that version control is required.
+
+## Loading State
+
+When starting a comparison or performing other operations that take more than a few seconds, a spinner is displayed to indicate the comparison is loading.
+
+## Level 1: Document List
+
+Level 1 displays all documents that differ between the selected revision and your current state.
+
+{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level1.png" alt="Comparison Pane Level 1 showing document list" class="no-border" >}}
+
+### Task Bar
+
+The task bar contains the following buttons:
+
+| Button | Action | When Enabled |
+|--------|--------|--------------|
+| **Back** | Returns to the previous level | Always disabled at Level 1 (kept to prevent layout shift) |
+| **Go to** | Opens the selected document and navigates to Level 2/3 | Enabled when a document is selected |
+| **Stop comparison** | Closes the comparison and returns to the blank state | Always enabled during an active comparison |
+
+### Context Menu
+
+Right-click any cell in the grid to access the **Copy** option, which copies the cell value to your clipboard.
+
+### Grid Columns
+
+The document list grid contains the following columns:
+
+| Column | Description | What It Shows |
+|--------|-------------|---------------|
+| **Status** | The type of change | An icon and label indicating whether the document was Added, Modified, or Deleted |
+| **Item** | The document name | The name of the changed document (for example, a page, microflow, or domain model) |
+| **Module** | The module location | The module that contains the document |
+
+All columns are sortable by clicking the column header. Column widths can be adjusted by dragging the column divider. Hover over any cell to see the full value in a tooltip.
+
+### Status Types
+
+The Status column shows one of the following types:
+
+| Status | Icon | Meaning | When It Appears |
+|--------|------|---------|-----------------|
+| **Added** | Green circle | A new document was created | The document exists in the current state but not in the selected revision |
+| **Modified** | Yellow circle | Changes were made to an existing document | The document exists in both revisions but has differences |
+| **Deleted** | Red circle with minus | A document was removed | The document existed in the selected revision but not in the current state |
+
+The icon and text spacing is consistent with the History Pane style.
+
+## Level 2 and 3: Element and Property Diffs
+
+Double-clicking a document in Level 1 navigates to Level 2 and Level 3, which appear side by side. Level 2 shows changed elements, and Level 3 shows the property differences for the selected element.
+
+{{< figure src="/attachments/refguide/modeling/menus/view-menu/comparison-pane/comparison-pane-level2-3.png" alt="Comparison Pane Level 2 and Level 3 showing element and property differences" class="no-border" >}}
+
+### Task Bar
+
+The task bar at Level 2/3 contains the following buttons:
+
+| Button | Action | When Enabled |
+|--------|--------|--------------|
+| **Back** | Returns to Level 1 | Always enabled |
+| **Go to** | Focuses on the selected element in the document | Enabled when an element is selected; remains active even for deleted elements to support cross-tab navigation |
+| **Expand all** | Expands all collapsed property tree rows in Level 3 | Always enabled when viewing Level 3 |
+| **Collapse all** | Collapses all expanded property tree rows in Level 3 | Always enabled when viewing Level 3 |
+| **Stop comparison** | Closes the comparison and returns to the blank state | Always enabled during an active comparison |
+
+### Context Menu
+
+Right-click any cell in either the Level 2 or Level 3 grid to access the **Copy** option.
+
+### Level 2 Grid
+
+The Level 2 grid shows all changed elements within the selected document:
+
+| Column | Description | What It Shows |
+|--------|-------------|---------------|
+| **Status** | The type of change | An icon and label indicating whether the element was Added, Modified, or Deleted |
+| **Item** | The element name | The name of the changed element (for example, a widget, entity, or activity) |
+
+Hover over any cell to see the full value in a tooltip.
+
+### Level 3 Grid
+
+The Level 3 grid shows the property-level differences for the element selected in Level 2:
+
+| Column | Description | What It Shows |
+|--------|-------------|---------------|
+| **Property** | The property name | The name of the property that changed, shown as a tree structure |
+| **Older** | The value in the selected revision | The property value as it was in the historical revision |
+| **Newer** | The value in the current state | The property value as it is in your current working state |
+
+Property paths are consolidated into a tree view. Grey rows represent intermediate path levels that do not have a direct value. The row order reflects the top-to-bottom, left-to-right order that the corresponding components appear in their dialog boxes.
+
+### Splitter
+
+A draggable splitter separates Level 2 and Level 3. Drag the splitter to adjust the space allocated to each level. By default, Level 3 (property differences) is given more space than Level 2 (element list).
+
+## Opening Documents
+
+When you click **Go to** or double-click a document entry in Level 1, the document opens as it currently exists in your project. If the document no longer exists in your current state, Level 2/3 is shown but nothing opens in the editor.
+
+{{% alert color="info" %}}
+In a future release (Mendix 11.18), both versions of the document will be opened side by side for visual comparison. For now, only the current version opens.
+{{% /alert %}}
+
+## Refresh Behavior
+
+When you are comparing a revision to your current state and you save changes to your app, a **Refresh** button appears in the Comparison Pane. Click **Refresh** to update the comparison with your latest saved changes.
+
+## Stopping a Comparison
+
+Click the **Stop comparison** button to close the comparison. This action closes the Comparison Pane and returns it to a blank state. Any documents that were opened as part of the comparison remain open in the editor.
+
+In the blank state, the Comparison Pane displays a message with a link to start a new comparison. The **Go to** and **Stop comparison** buttons are disabled until a new comparison is started.
+
+## Read More
+
+* [History](/refguide/history-dialog/)
+* [Changes Pane](/refguide/changes-pane/)
+* [Comparing Revisions](/refguide/comparing-revisions/)
+* [Version Control](/refguide/version-control/)

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

@@ -31,6 +31,12 @@ Currently, Mendix does not support pull or merge requests through the Team Serve
 * code for Java and JavaScript actions
 * HTML/CSS for theming
 
+## Comparing Revisions
+
+Use the [Comparison Pane](/refguide/comparison-pane/) to compare any historical revision to your current working state. This helps you understand what has changed since a specific revision, see the impact of your recent edits, or review what would be affected if you reverted to a past revision.
+
+For more information, see [Comparing Revisions](/refguide/comparing-revisions/).
+
 ## Frequently Asked Questions
 
 ### What Version Control System Is Team Server Built On? {#which-team-server}