From 62a2d21d0101be08fd4b418a4a6f62bb10fdc88f Mon Sep 17 00:00:00 2001
From: Guillaume <guillaume@1kb.software>
Date: Wed, 20 Nov 2024 10:22:10 +0100
Subject: [PATCH] Add breaking changes docs and update roadmap

---
 content/docs/latest/about.md                  | 22 +++++++++++++++++++
 .../sharing-mock-api-files.md                 |  2 +-
 pages/public-roadmap.tsx                      | 11 ++++++++++
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/content/docs/latest/about.md b/content/docs/latest/about.md
index ffabb5ca..15d4238e 100644
--- a/content/docs/latest/about.md
+++ b/content/docs/latest/about.md
@@ -37,3 +37,25 @@ While the desktop application can easily **migrate from one version to another**
 Every time we introduce a **breaking change** in the data file schema (e.g. new feature) we release a **new major version**. We recommend that you always migrate simultaneously to the same major version for all the desktop applications and packages you are using.
 
 > 📝 Note to our Cloud users: the same recommendation applies when you are using our **Cloud features**. Please have a look at the [team collaboration](docs:mockoon-cloud/data-synchronization-team-collaboration#major-versions-migrations) and [cloud deployments](docs:mockoon-cloud/api-mock-cloud-deployments#major-versions-migrations) documentations for more information.
+
+### Breaking changes
+
+When building libraries, the definition of a **breaking change** is usually straightforward. However, when building desktop applications, it's harder to define what a breaking change is.
+
+Also, as we have **multiple components** (desktop application, CLI, serverless package), we have to consider the impact of a change on all these components while avoiding a too-strict definition of a breaking change that would mandate a new major version for every release.
+
+Our definition of a breaking change is a change impacting the [**data schema**](docs:mockoon-data-files/data-storage-location) and creating a **compatibility issue** between the applications and packages.
+
+Examples of **schema changes** that would require a **new major version**:
+
+- Adding a new feature requiring a new field.
+- Adding a new type in an enum field, like a new rule type.
+- Removing a feature that requires removing a field from the schema.
+
+The consequence of such a change is that the data file created with a recent version of the desktop application would not be compatible with an older version of the desktop application, CLI, serverless package, or a team Cloud workspace.
+
+What we do **not consider a breaking change**, even if it might impact the user experience and require a migration effort:
+
+- Changing the UI layout.
+- Changing the behavior of a feature (e.g. adding templating support to a field).
+- Changing the templating helpers' signatures or adding new ones.
diff --git a/content/docs/latest/mockoon-data-files/sharing-mock-api-files.md b/content/docs/latest/mockoon-data-files/sharing-mock-api-files.md
index 30d28a03..180c03d5 100644
--- a/content/docs/latest/mockoon-data-files/sharing-mock-api-files.md
+++ b/content/docs/latest/mockoon-data-files/sharing-mock-api-files.md
@@ -27,4 +27,4 @@ You can disable pretty printing in the settings:
 
 ### Use a mock API with the CLI
 
-The CLI is directly [compatible with environment files](https://github.com/mockoon/cli#use-your-mocks-in-the-cli). After locating your environment file, you run them with the CLI using the following command: `mockoon-cli start -d ./path-to-file/environment-data-file.json`.
+The CLI is directly [compatible with environment files](https://github.com/mockoon/mockoon/blob/main/packages/cli/README.md#use-your-mockoon-environment-file). After locating your environment file, you run them with the CLI using the following command: `mockoon-cli start -d ./path-to-file/environment-data-file.json`.
diff --git a/pages/public-roadmap.tsx b/pages/public-roadmap.tsx
index a1ad176c..1dcf63fc 100644
--- a/pages/public-roadmap.tsx
+++ b/pages/public-roadmap.tsx
@@ -122,6 +122,12 @@ const tasks: {
     }
   ],
   inProgress: [
+    {
+      link: 'https://github.com/mockoon/mockoon/issues/1581',
+      title: 'Improved data buckets state reporting',
+      cloud: false,
+      target: '_blank'
+    },
     {
       link: 'https://github.com/mockoon/mockoon/issues/1045',
       title: 'Export logs as HAR',
@@ -136,6 +142,11 @@ const tasks: {
     }
   ],
   comingSoon: [
+    {
+      title: 'Custom sub domains in cloud deployments',
+      cloud: true,
+      target: null
+    },
     {
       title: 'Environment variables support in cloud deployments',
       cloud: true,