docs(web modeler): Milestones and process application changelist

docs/components/modeler/web-modeler/milestones.md

@@ -1,50 +1,141 @@
 ---
 id: milestones
 title: Milestones
-description: Working with milestones in Web Modeler
+description: Work with milestones in Web Modeler
 ---
 
 <span class="badge badge--cloud">Camunda 8 only</span>
 
-## Milestones
+You can create a milestone at any time to save a snapshot of your BPMN or DMN diagram.
 
-You can save a snapshot of your diagram as a milestone any time.
+You can restore a milestone to revert to a previous snapshot of your diagram, for example if you make a mistake while modeling. You can also compare two milestones to see the differences between them.
 
-If you make any mistakes while modeling, you can always go back to previously saved snapshots. You can also identify and compare the differences between two milestones.
+## Milestone history
 
-Find your milestones by opening the actions menu, and clicking on **History**.
-![milestones](img/milestones/web-modeler-milestone-action-menu-item.png)
+You can use the milestone history to view, compare, and manage your diagram milestones.
 
-### Creating milestones
+To view the milestone history, either:
 
-In the milestone history view, the latest version can be saved as a new milestone.
-![milestones create via icon](img/milestones/web-modeler-milestone-create-via-icon.png)
+- Select **History** from the actions menu.
 
-Alternatively, you can create a new milestone via the breadcrumb menu in the diagram view.
-![milestones create via icon](img/milestones/web-modeler-milestone-create-via-breadcrumb.png)
+  ![Milestone history screen showing the History button](img/milestones/web-modeler-milestone-action-menu-item-highlight.png)
 
-When dragging and dropping a file into the diagram view, or when using the **Replace via upload** option under the breadcrumb menu, a new milestone is created automatically.
+- Select **Show milestone history** from the breadcrumb menu.
 
-#### Bulk milestone creation
+  ![Milestone history screen showing the History button](img/milestones/web-modeler-milestone-show-history-via-breadcrumb-highlight.png)
 
-A [process application](/components/modeler/web-modeler/process-applications.md) is a special type of folder in Web Modeler that allows you to work on a set of related files and
-[deploy](/components/modeler/web-modeler/process-applications.md#deploy-and-run-a-process-application) them together in a single bundle with just one click. This reduces the risk of having a broken deployment at runtime and makes it more convenient to deploy related files.
+## Create a milestone
 
-When creating a milestone on a main process of a process application, milestones are created for all other assets in the application to make it easier to track or roll back changes.
+You can create a new milestone either from your diagram or the milestone history.
+
+- From your diagram, select **Create milestone** from the breadcrumb menu.
+
+  ![milestones create via icon](img/milestones/web-modeler-milestone-create-via-breadcrumb-highlight.png)
+
+- From the milestone history, hover over the the latest version in the **Milestones** panel and select **Create a new milestone**.
+
+  ![milestones create via icon](img/milestones/web-modeler-milestone-create-via-icon-highlight.png)
+
+:::note
+
+A new milestone is also automatically created when dragging and dropping a file into the diagram view, or when you select the **Replace via upload** option from the breadcrumb menu.
+
+:::
+
+### Bulk milestone creation
+
+A [process application](/components/modeler/web-modeler/process-applications.md) is a special type of Web Modeler folder that allows you to work on a set of related files and
+[deploy](/components/modeler/web-modeler/process-applications.md#deploy-and-run-a-process-application) them as a single bundle with just one click. This reduces the risk of having a broken deployment at runtime, and makes it more convenient to deploy related files.
+
+If you create a milestone on the main process of a process application, milestones are created for all other assets in the application, to make it easier to track or revert changes. See [create a bulk milestone](process-applications.md#create-a-bulk-milestone).
 
 :::note
 Milestones of resources belonging to a process application are tied to the main process and cannot be modified.
 :::
 
-### Restoring milestones
+## Compare milestones
 
-Hover over a milestone, click on the three vertical dots, and expand for more options.
-![milestones restore](img/milestones/web-modeler-milestone-restore.png)
-![milestones restore](img/milestones/web-modeler-milestone-restore-complete.png)
+You can compare the change history between two milestones, either visually as a diagram or as code in an XML diff layout.
 
-### Comparing milestones
+1. Open the milestone history for your diagram.
+1. Ensure that the sidebar **Show changes** toggle is turned on.
+1. Select the milestone that you want to compare. The previous milestone is automatically selected for comparison.
 
-Milestones can be compared visually. By enabling the diffing feature, the currently selected milestone is compared to its predecessor.
+:::note
+
+Turn off the sidebar **Show changes** toggle to view individual milestones without comparison to the previous milestone.
+
+:::
+
+### Compare milestones in visual view
+
+To view BPMN diagram changes visually, select the **Visual view** tab.
 
-The differences that are highlighted are only those that affect the execution of the BPMN process. Pure visual changes like position changes are not highlighted.
-![milestones diffing](img/milestones/web-modeler-milestone-diffing.png)
+![milestones diffing](img/milestones/web-modeler-milestone-visual-diffing.png)
+
+- Differences between the milestones are highlighted visually on the diagram. For example, if an element was added, this change is highlighted in green with a plus symbol. Hover over a change to view more details.
+- Only differences that affect the execution of the BPMN process are highlighted.
+- The sidebar **Changes** list shows the details of each change, including the type and identifier. Select a change to highlight it.
+
+:::note
+
+You can only use the **Code view** to compare changes in a DMN diagram. The **Visual view** only shows a view of the milestone.
+
+:::
+
+### Compare milestones in code view
+
+To view BPMN and DMN diagram changes as code in an XML diff layout, select the **Code view** tab.
+
+![milestones diffing](img/milestones/web-modeler-milestone-code-diffing.png)
+
+- The XML for the previous milestone is shown on the left, with the currently selected milestone shown on the right.
+- Differences between the milestones are highlighted in the XML. For example, if an element was added, this change is highlighted in green.
+
+## Restore a milestone
+
+You can restore a milestone to revert to a previous snapshot of your diagram.
+
+1. In the sidebar **Milestones** list, hover over the milestone you want to restore.
+1. Select the three vertical dots to open the actions menu.
+1. Select **Restore as latest**.
+
+![milestones restore](img/milestones/web-modeler-milestone-restore-highlight.png)
+
+The diagram reverts to the restored milestone. A new milestone is created with "(restored)" appended to the name.
+
+![milestones restore](img/milestones/web-modeler-milestone-restore-complete-highlight.png)
+
+## Copy a diagram milestone
+
+You can create a new diagram by copying a specific milestone.
+
+1. In the sidebar **Milestones** list, hover over the diagram milestone you want to copy.
+1. Select the three vertical dots to open the actions menu.
+1. Select **Copy to...**.
+1. Choose a project/folder and select **Copy here** to create the new diagram in the chosen folder.
+
+## Rename a milestone
+
+You can rename a milestone at any time.
+
+1. In the sidebar **Milestones** list, hover over the milestone you want to rename.
+1. Select the three vertical dots to open the actions menu.
+1. Select **Edit name** and enter a new name for the milestone.
+
+## Delete a milestone
+
+You can _permanently_ delete a milestone.
+
+1. In the sidebar **Milestones** list, hover over the milestone you want to rename.
+1. Select the three vertical dots to open the actions menu.
+1. Select **Delete**.
+1. You are prompted to confirm the deletion.
+   - Select **Delete milestone** to permanently delete the milestone.
+   - Select **Cancel** to cancel the deletion and return to the milestone history.
+
+:::caution
+
+Deleting a milestone is permanent. You cannot access a deleted milestone, and it is removed from the milestone history.
+
+:::

docs/components/modeler/web-modeler/process-applications.md

@@ -108,9 +108,37 @@ Note that when you deploy the process application:
 
 ## Versioning
 
-You can also add version tags to [milestones](/components/modeler/web-modeler/milestones.md), and create milestones for all resources of given process applications.
+Although you cannot version a process application itself, you can use [bulk milestone creation](milestones.md#bulk-milestone-creation) and version tags to save a single 'versioned' snapshot of all the files in a process application in one action, instead of having to create separate milestones for each file. This allows you to track a process application through the development lifecycle and ensure the correct version is called.
 
-When creating a milestone, name your milestone with a version tag to track it through the development lifecycle and ensure the correct version is called. To do this, enter a **Version tag** within the **Create a milestone** modal and click **Create**.
+When you create a milestone in a process application file, a milestone is also created with the same name (version tag) for all files currently available in the process application.
+
+### A worked example
+
+In this example, you have a process application that contains multiple files as well as the main process.
+
+- You create a new milestone for the main process and enter "1.2" as the version tag.
+- When you create this new milestone, a milestone is also then created for each of the other files with a "1.2" version tag.
+- After the creation process completes, all files in the process application now have a "version 1.2" milestone.
+
+### Create a bulk milestone
+
+To create a bulk milestone for a process application:
+
+1. Open any file in a process application and [create a milestone](milestones.md#create-a-milestone).
+1. Enter a **Version tag**.
+1. Select **Create** to create a matching version milestone for each file in the process application.
+
+![milestones diffing](img/milestones/web-modeler-milestone-create-versioned-milestone-highlight.png)
+
+Now when you open the milestone history for any file in the process application, you can use the file navigation header buttons to switch between files, and view their individual milestone history.
+
+![milestones restore](img/milestones/web-modeler-milestone-compare-process-application-files-highlight.png)
+
+:::note
+
+When naming your milestone with a version tag, you cannot edit or delete the created versions.
+
+:::
 
 ## Limitations
 
@@ -119,9 +147,8 @@ Be aware of the following limitations when working with process applications:
 - You cannot create subfolders inside a process application.
 - Process applications can only be deployed to a Zeebe cluster in version 8.4.0 or higher.
 - It is not possible to deploy individual files that are part of a process application; the application will always be deployed as a whole.
-- When you deploy a process application, only the main process will be checked for missing [Connector secrets](../../console/manage-clusters/manage-secrets.md).
+- When you deploy a process application, only the main process is checked for missing [Connector secrets](../../console/manage-clusters/manage-secrets.md).
 - The overall size of the deployment bundle is limited due to a maximum [record](../../zeebe/technical-concepts/internal-processing.md) size of 4 MB in Zeebe.
   Effectively, the limit is between 2 and 3 MB as Zeebe writes more data to the log stream than just the raw deployment.
-  - If you exceed the limit, you will see the following [error message](#deployment-errors):  
+  - If you exceed the limit, you are shown the following [error message](#deployment-errors):  
     `Command 'CREATE' rejected with code 'EXCEEDED_BATCH_RECORD_SIZE'`
-- When naming your milestone with a version tag, users are unable to modify and delete the created versions.