docs/UPGRADE.md

Upgrade

All instructions to upgrade this project from one release to the next will be documented in this file. Upgrades must be run sequentially, meaning you should not skip minor/major releases while upgrading (fix releases can be skipped).

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

For most upgrades, you just need to run the django migrations with the following command inside your docker container:

python manage.py migrate

(Note : in your development environment, you can make migrate.)

[Unreleased]

[5.0.0] - 2026-04-30

We made several changes around document content management leading to several breaking changes in the API.

• The endpoint /api/v1.0/documents/{document_id}/content/ has been renamed in /api/v1.0/documents/{document_id}/formatted-content/
• There is no more content attribute in the response of /api/v1.0/documents/{document_id}/, two new endpoints have been added to retrieve or update the document content.
• A new GET /api/v1.0/documents/{document_id}/content/ endpoint has been implemented to fetch the document content ; this endpoint streams the whole content with a text/plain content-type response.
• A new PATCH /api/v1.0/documents/{document_id}/content/ endpoint has been added to update the document content ; expected payload is:

{
  "content": "document content in base64",
}

Other changes:

• The deprecated endpoint /api/v1.0/documents/<document_id>/descendants is removed. The search endpoint should be used instead.
• Upgrade docspec dependency to version >= 3.0.0 The docspec service has changed since version 3.0.0, we ware now compatible with this version and not with version 2.x.x anymore
• It is now possible to use the Mistral SDK instead of the OpenAI for the AI features. If your provider is compatible with the mistral API, we encourage you to use it.
• AI_API_KEY settings is renamed in OPENAI_SDK_API_KEY and is only used to congiure the OpenAi sdk
• AI_BASE_URL settings is renamed in OPENAI_SDK_BASE_URL and is only used to congiure the OpenAi sdk

[4.6.0] - 2026-02-27

• ⚠️ Some setup have changed to offer a bigger flexibility and consistency, overriding the favicon and logo are now from the theme configuration. f24b047a7c/src/backend/impress/configuration/theme/default.json (L129-L161)

[4.0.0] - 2025-11-26

• ⚠️ We updated @gouvfr-lasuite/ui-kit to 0.18.0, so if you are customizing Docs with a css layer or with a custom template, you need to update your customization to follow the new design system structure.
  More information about the changes in the design system can be found here:

  • https://suitenumerique.github.io/cunningham/storybook/?path=/docs/migrating-from-v3-to-v4--docs
  • https://github.com/suitenumerique/docs/pull/1605
  • https://github.com/suitenumerique/docs/blob/main/docs/theming.md

• If you were using the THEME_CUSTOMIZATION_FILE_PATH and have overridden the header logo, you need to update your customization file to follow the new structure of the header, it is now:

  {
    ...,
    "header": {
      "icon": {
        "src": "your_logo_src",
        "width": "your_logo_width",
        "height": "your_logo_height"
      }
    }
  }
  

[3.3.0] - 2025-05-22

⚠️ For some advanced features (ex: Export as PDF) Docs relies on XL packages from BlockNote. These are licenced under AGPL-3.0 and are not MIT compatible. You can perfectly use Docs without these packages by setting the environment variable PUBLISH_AS_MIT to true. That way you'll build an image of the application without the features that are not MIT compatible. Read the environment variables documentation for more information.

The footer is now configurable from a customization file. To override the default one, you can use the THEME_CUSTOMIZATION_FILE_PATH environment variable to point to your customization file. The customization file must be a JSON file and must follow the rules described in the theming documentation.

[3.0.0] - 2025-03-28

We are not using the nginx auth request anymore to access the collaboration server (yProvider) The authentication is now managed directly from the yProvider server. You must remove the annotation nginx.ingress.kubernetes.io/auth-url from the ingressCollaborationWS.

This means as well that the yProvider server must be able to access the Django server. To do so, you must set the COLLABORATION_BACKEND_BASE_URL environment variable to the yProvider service.

[2.2.0] - 2025-02-10

• AI features are now limited to users who are authenticated. Before this release, even anonymous users who gained editor access on a document with link reach used to get AI feature. If you want anonymous users to keep access on AI features, you must now define the AI_ALLOW_REACH_FROM setting to "public".