lasuite-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](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

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]

- The endpoint `/api/v1.0/documents/{document_id}/content/`, added in 5.0.0, is
  removed, both its `GET` and its `PATCH`. The content of a document is now
  saved and served by the collaboration server, the editor exchanging it over
  the websocket, so nothing reads or writes it through the API anymore. If you
  integrate with Docs, stop calling this endpoint: the `content_patch` and
  `content_retrieve` abilities disappear from the document payload along with
  it. `/api/v1.0/documents/{document_id}/formatted-content/` is not affected.
  The `CONTENT_METADATA_CACHE_TIMEOUT` setting only tuned the cache of the
  removed `GET` and is no longer read, you can drop it from your configuration.
- The JWKS of the resource server moved from `/api/{version}/jwks` to
  `/external_api/{version}/jwks`, alongside the rest of the resource server
  endpoints. `/api/{version}/jwks` now publishes the public key validating the
  tokens Docs issues to call external services. If you enabled the resource
  server (`OIDC_RESOURCE_SERVER_ENABLED`), update the JWKS URI declared to your
  OIDC provider accordingly.
- ⚠️ The collaboration server now calls the backend on its own, to declare that
  a document was edited, and signs those calls: **it needs an RSA private key
  of its own**, which it had not before. Generate one and give it to the
  collaboration server in `YHUB_JWT_PRIVATE_KEY`, or in a file
  `YHUB_JWT_PRIVATE_KEY_FILE` points at:

  ```bash
  openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out yhub-private.pem
  ```

  There is nothing to configure on the backend side: it reads the public half
  from the JWKS the collaboration server publishes on `/collaboration/jwks/v1`,
  which it fetches over `YHUB_API_BASE_URL` — so the two only need to reach
  each other, and this key can be rolled without the backend being touched.
  Do not share the backend key (`JWT_PRIVATE_KEY`) with it: each service signs
  with a key of its own.

  Without this key the collaboration server keeps serving documents, and warns
  at startup that it will not notify the backend: the `updated_at` of a document
  then stops following the edits made in the editor, and the lists ordered by it
  drift out of date. In a development environment,
  `make generate-secret-keys` creates the key in `data/jwt/`.

### [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:
```json
{
  "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.
https://github.com/suitenumerique/docs/blob/f24b047a7cc146411412bf759b5b5248a45c3d99/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: 
  ```json
  {
    ...,
    "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](/docs/env.md) 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](docs/theming.md).

## [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".