[deployment] improve breaking changes documentation

docs/deployment/breaking-changes.md

@@ -4,53 +4,49 @@ This section lists breaking changes introduced in OpenCTI, per version starting
 
 Please follow the migration guides if you need to upgrade your platform. 
 
-## OpenCTI 6.2
-
-### Change to the observable "promote"  
-
-The API calls that promote an Observable to Indicator now return the created Indicator instead of the original Observable.
+## Breakdown per version
 
-**GraphQL API**
+This table regroups all the breaking changes introduced, with the corresponding version in which the change was implemented.
 
-* Mutation `StixCyberObservableEditMutations.promote` is now deprecated
-* New Mutation `StixCyberObservableEditMutations.promoteToIndicator` introduced
+| Change                                                           | Deprecated in | Changed in |
+|:-----------------------------------------------------------------|:--------------|:-----------|
+| [Promote Observable API](#change-to-the-observable-promote-API)  | 6.2           | 6.5        |
+| [SAML authentication parameters](#change-to-SAML-authentication) |               | 6.2        |
+| [Major changes to Filtering API](#new-filtering-API)             |               | 5.12       |
 
 
-**Client-Python API**
-
-* Client-python method `client.stix_cyber_observable.promote_to_indicator` is now deprecated
-* New Client-python method `client.stix_cyber_observable.promote_to_indicator_v2` introduced
-
+## OpenCTI 6.2
 
-!!! warning "Discontinued Support"
+### Deprecation
 
-    Please note that the deprecated methods will be permanently removed in OpenCTI 6.5.
+<a id="change-to-the-observable-promote-API"></a>
+#### Change to the observable promote API  
 
-#### How to migrate
-
-If you are using custom scripts that make use of the deprecated API methods, please update these scripts.
+The API calls that promote an Observable to Indicator now return the created Indicator instead of the original Observable.
 
-The changes are straightforward: if you are using the return value of the method, you should now expect the new Indicator 
-instead of the Observable being promoted; adapt your code accordingly.
+For more details, see [this migration guide](./breaking-changes/6.2-promote-to-indicator.md).
 
+### Breaking Changes
 
+<a id="change-to-SAML-authentication"></a>
 ### Change to SAML authentication
 
-When `want_assertions_signed` and `want_authn_response_signed` SAML parameter are not present in OpenCTI configuration, 
-the default is now set to `true` by the underlying library (passport-saml) when previously it was `false` by default.
+Upgrading `passport-saml` library introduced a breaking change with respect to the default SAML parameters regarding signing responses and assertions. 
+
+For more details, see [this migration guide](./breaking-changes/6.2-saml-authentication.md).
 
 #### How to migrate
 
 If you have issues after upgrade, you can try with both parameters set to `false`.
 
 ## OpenCTI 5.12
 
-### Major changes to the filtering APi
+### Breaking changes
 
-OpenCTI 5.12 introduces a major rework of the **filter engine** with breaking changes to the model.
+<a id="new-filtering-API"></a>
+#### Major changes to the filtering API
 
+OpenCTI 5.12 introduces a major rework of the **filter engine** with breaking changes to the model.
 A [dedicated blog post](https://blog.filigran.io/introducing-advanced-filtering-possibilities-in-opencti-552147565faf) describes the reasons behind these changes.
 
-#### How to migrate
-
-Please read the dedicated [migration guide](../reference/filters-migration.md).
+Please read the dedicated [migration guide](./breaking-changes/5.12-filters.md).

docs/reference/filters-migration.md → docs/deployment/breaking-changes/5.12-filters.md

@@ -1,6 +1,10 @@
-# Filters format migration for OpenCTI 5.12
+# Change to filter model and API
 
-The version 5.12 of OpenCTI introduces breaking changes to the [filters format](./filters.md) used in the API. This documentation describes how you can migrate your scripts or programs that call the OpenCTI API, when updating from a version of OpenCTI inferior to 5.12.
+!!! info ""
+
+    * **Changed in**: `OpenCTI 5.12`
+
+The version 5.12 of OpenCTI introduces breaking changes to the [filters format](../../reference/filters.md) used in the API. This documentation describes how you can migrate your scripts or programs that call the OpenCTI API, when updating from a version of OpenCTI inferior to 5.12.
 
 
 ## Why this migration?
@@ -103,15 +107,15 @@ The new filter implementation bring major changes in the way filters are process
 
 ## How to migrate your own filters
 
-We wrote a migration script to convert all [stored filters](filters.md#stored-filter-section) created prior to version 5.12. These filters will thus be migrated automatically when starting your updated platform.
+We wrote a migration script to convert all [stored filters](../../reference/filters.md#stored-filter-section) created prior to version 5.12. These filters will thus be migrated automatically when starting your updated platform.
 
 However, you might have your own connectors, queries, or python scripts that use the graphql API or the python client. If this is the case, you must change the filter format if you want to run the code against OpenCTI >= 5.12.
 
 ### Filter conversion
 
 To convert filters prior to version 5.12 in the new format:
 
-1. update the `key` field if it has been changed in 5.12 (see the [conversion table](filters-migration.md#conversion-table-section) below),
+1. update the `key` field if it has been changed in 5.12 (see the [conversion table](#conversion-table-section) below),
 2. rename the field `filterMode` in `mode`
 3. if `values` contains `null`, see below for conversion.
 
@@ -323,4 +327,4 @@ These filters are not migrated automatically and are lost when moving to 5.12. T
 
 Also, when going to an url with filters in the old format, OpenCTI will display a warning and remove the filter parameters. Only URLs built by OpenCTI 5.12 are compatible with it, so you will need to reconstruct the filters by hand and save / share your updated links.
 
-![URL warning](./assets/filters-migration-url-warning.png)
+![URL warning](../../reference/assets/filters-migration-url-warning.png)

docs/deployment/breaking-changes/6.2-promote-to-indicator.md

@@ -0,0 +1,29 @@
+# Change to the observable "promote" API
+
+!!! info ""
+
+    * **Deprecated in**: `OpenCTI 6.2`
+    * **Removed in**: `OpenCTI 6.5`
+
+## Description of changes
+
+The API calls that promote an Observable to Indicator now return the created Indicator instead of the original Observable.
+
+**GraphQL API**
+
+* Mutation `StixCyberObservableEditMutations.promote` is now deprecated
+* New Mutation `StixCyberObservableEditMutations.promoteToIndicator` introduced
+
+
+**Client-Python API**
+
+* Client-python method `client.stix_cyber_observable.promote_to_indicator` is now deprecated
+* New Client-python method `client.stix_cyber_observable.promote_to_indicator_v2` introduced
+
+
+## Migration guide
+
+If you are using custom scripts that make use of the deprecated API methods, please update these scripts.
+
+The changes are straightforward: if you are using the return value of the method, you should now expect the new Indicator
+instead of the Observable being promoted; adapt your code accordingly.

docs/deployment/breaking-changes/6.2-saml-authentication.md

@@ -0,0 +1,16 @@
+# Change to SAML authentication default parameters
+
+!!! info ""
+
+    * **Changed in**: `OpenCTI 6.2`
+
+## Description of changes
+
+Upgrading `passport-saml` library introduced a breaking change with respect to the default SAML parameters regarding signing responses and assertions.
+
+When `want_assertions_signed` and `want_authn_response_signed` SAML parameter are not present in OpenCTI configuration,
+the default is now set to `true` by `passport-saml` library when previously it was `false` by default.
+
+## Migrate guide
+
+If you have issues after upgrade, you can try with both parameters set to `false`.

docs/usage/export.md

@@ -24,7 +24,7 @@ This opens the export settings panel, where you can customize your export accord
 
 - desired export format (text/csv, application/pdf, application/vnd.oasis.stix+json, text/plain)
 - export type (simple or full),
-- the max marking definition levels of the elements to be included in the export (a TLP level, for instance). The list of the available max markings is limited by the user allowed markings and its maximum shareable markings (more details about maximum shareable marking definitions in [data segregation](segregation.md)). For a marking definition type to be taken into account here, a marking definition from this type must be provided. For example, if you select TLP:GREEN for this field, AMBER and RED elements will be excluded but it will not take into account any PAP markings unless one is elected too.
+- the max marking definition levels of the elements to be included in the export (a TLP level, for instance). The list of the available max markings is limited by the user allowed markings and its maximum shareable markings (more details about maximum shareable marking definitions in [data segregation](../administration/segregation.md)). For a marking definition type to be taken into account here, a marking definition from this type must be provided. For example, if you select TLP:GREEN for this field, AMBER and RED elements will be excluded but it will not take into account any PAP markings unless one is elected too.
 - the file marking definition levels of the export (a TLP level, for instance). This marking on the file itself will then restrain the access to it in accordance with users' marking definition levels. For example, if a file has the marking TLP:RED and INTERNAL, a user will need to have these marking to see and access the file in the platform.```
 
 ![customize your export](assets/customize_your_export.png)

mkdocs.yml

@@ -117,7 +117,12 @@ nav:
       - Configuration: deployment/configuration.md
       - Authentication: deployment/authentication.md
       - Upgrade: deployment/upgrade.md
-      - Breaking changes: deployment/breaking-changes.md
+      - Breaking changes:
+        - Index: deployment/breaking-changes.md
+        - Migration guides:
+          - Promote to Indicator: deployment/breaking-changes/6.2-promote-to-indicator.md
+          - SAML authentication: deployment/breaking-changes/6.2-saml-authentication.md
+          - New filter API: deployment/breaking-changes/5.12-filters.md
     - Ecosystem:
       - Connectors: deployment/connectors.md
       - Integrations: deployment/integrations.md
@@ -216,7 +221,6 @@ nav:
       - GraphQL API: reference/api.md
       - Filters:
         - Filters knowledge: reference/filters.md
-        - Filter migration for 5.12: reference/filters-migration.md
       - Data Streaming: reference/streaming.md
     - Deployment and stack:
         - Usage telemetry: reference/usage-telemetry.md