docs(web-modeler): announce milestone to version renaming (#4901)

* docs(web-modeler): announce milestone to version renaming

* chore: reviewdog suggestions

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* style(formatting): technical review

* add note for change

* Update docs/reference/announcements/870.md

Co-authored-by: Mark Sellings <mark.sellings@camunda.com>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Christina Ausley <christina.ausley@camunda.com>
Co-authored-by: Mark Sellings <mark.sellings@camunda.com>

Author: 4 people

docs/components/modeler/web-modeler/process-application-versioning.md

@@ -4,6 +4,10 @@ title: Process application versioning
 description: Process applications allow you to deploy multiple related files together in a single bundle.
 ---
 
+:::note
+With 8.7, "milestone" has been renamed to "version". To learn more about this change, see [the related announcement](/reference/announcements/870.md##web-modeler-milestones-renamed-to-versions).
+:::
+
 Although you cannot version a process application itself, you can use [bulk version creation](versions.md#bulk-version-creation) and version tags to save a single snapshot of all the process application files in one action, instead of having to create separate versions for every file.
 
 - When you create a version in any process application file, a version is also created with the same name (version tag) for all files currently available in the process application.

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

@@ -6,6 +6,10 @@ description: Work with versions in Web Modeler.
 
 <span class="badge badge--cloud">Camunda 8 only</span>
 
+:::note
+With 8.7, "milestone" has been renamed to "version". To learn more about this change, see [the related announcement](/reference/announcements/870.md##web-modeler-milestones-renamed-to-versions).
+:::
+
 You can create a version at any time to save a snapshot of your BPMN or DMN diagram.
 
 You can restore a version to revert to a previous snapshot of your diagram, for example if you make a mistake while modeling. You can also compare two versions to see the differences between them.

docs/reference/announcements/870.md

@@ -18,10 +18,14 @@ Important changes and updates for the Camunda 8.7 release are summarized below.
   - [Fetch RPA resource API](#)
   - [deployResourceAPI for RPA](#) -->
 
-- [Web Modeler Deploy diagram change](#web-modeler-deploy-diagram-change)
-- [Southwest Asia for SaaS region](#southeast-asia-region-for-saas-customers-saas)
+- [Web Modeler](#web-modeler)
+  - [Deploy diagram change Self-Managed {#web-modeler-deploy-diagram-change}](#deploy-diagram-change-self-managed-web-modeler-deploy-diagram-change)
+  - [Milestones renamed to versions {#web-modeler-milestones-renamed-to-versions}](#milestones-renamed-to-versions-web-modeler-milestones-renamed-to-versions)
+- [Southeast Asia region for SaaS customers SaaS](#southeast-asia-region-for-saas-customers-saas)
 
-## Web Modeler Deploy diagram change <span class="badge badge--long" title="This feature affects Self-Managed">Self-Managed</span>
+## Web Modeler
+
+### Deploy diagram change <span class="badge badge--long" title="This feature affects Self-Managed">Self-Managed</span> {#web-modeler-deploy-diagram-change}
 
 With this version, we ship a breaking change to how Web Modeler **Deploy diagram** modals work. Clusters must now be proactively [configured](/docs/self-managed/modeler/web-modeler/configuration/configuration.md#clusters) to be able to deploy from Web Modeler.
 
@@ -31,6 +35,17 @@ With this version, we ship a breaking change to how Web Modeler **Deploy diagram
 - In 8.7, you can no longer configure cluster details on the **Deploy diagram** modal. You must [configure the cluster](/docs/self-managed/modeler/web-modeler/configuration/configuration.md#clusters) to be able to deploy from this modal.
 - Note that you must also be assigned the `Zeebe` [Identity role](/docs/self-managed/identity/user-guide/roles/add-assign-role.md) to be able to deploy.
 
+### Milestones renamed to versions {#web-modeler-milestones-renamed-to-versions}
+
+The term "milestones" has been renamed to ["versions"](/components/modeler/web-modeler/versions.md) in Web Modeler for clarity and consistency with other Camunda 8 components. The renaming is implemented across the Web Modeler user interface and the API.
+
+In [the API](/apis-tools/web-modeler-api/index.md), new endpoints starting with `/api/v1/versions` have been introduced, while the previous `/api/v1/milestones` endpoints are now deprecated.
+Further details can be found in [Web Modeler's OpenAPI documentation](https://modeler.camunda.io/swagger-ui/index.html).
+
+:::note
+This is a nominal update and the functionality of versions and milestones is equivalent.
+:::
+
 ## Southeast Asia region for SaaS customers <span class="badge badge--long" title="This feature affects SaaS">SaaS</span>
 
 SaaS customers can now create orchestration clusters in the [Singapore (asia-southeast1) region](/reference/regions.md), ensuring lower latency and improved processing speed for organizations operating in southeast Asian countries.