Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-01-20 00:08:02 +01:00
Code Issues Projects Releases Wiki Activity

docs: add migration guide entry for v4 -> v5 (#3650)

Browse Source 
This lists the breaking changes between the versions to make it easier
(and safer) for users to upgrade
This commit is contained in:
Thomas Heartman 2023-04-28 13:10:30 +02:00 committed by GitHub
parent 178f4ff292
commit b815fa1a9d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 73 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/docs/reference/api/legacy/unleash/admin/features.md
View File

@ -3,7 +3,9 @@ title: /api/admin/features
--- ---
:::caution Deprecation notice :::caution Deprecation notice
Most of this API was deprecated as part of the v4.3 release and will be removed in v5.0. You should use [the project-based API (/api/admin/projects/:projectId)](/reference/api/legacy/unleash/admin/features-v2.md) instead. The deprecated endpoints are marked as such in the document below.
Most of this API was removed in Unleash v5 (after being deprecated since Unleash v4.3). You should use [the project-based API (/api/admin/projects/:projectId)](/reference/api/legacy/unleash/admin/features-v2.md) instead.
::: :::
@ -15,7 +17,9 @@ In order to access the admin API endpoints you need to identify yourself. Unless
## Fetching Feature Toggles {#fetching-feature-toggles} ## Fetching Feature Toggles {#fetching-feature-toggles}
:::caution Deprecation notice :::caution Deprecation notice
This endpoint is deprecated. Please use the [project-based endpoint to fetch all toggles](/reference/api/legacy/unleash/admin/features-v2.md#fetching-toggles) instead.
This endpoint was removed in Unleash v5. Please use the [project-based endpoint to fetch all toggles](/reference/api/legacy/unleash/admin/features-v2.md#fetching-toggles) instead.
::: :::
`GET: http://unleash.host.com/api/admin/features` `GET: http://unleash.host.com/api/admin/features`

67
website/docs/reference/deploy/migration-guide.md
View File

@ -4,6 +4,73 @@ title: Migration Guide
Generally, the intention is that `unleash-server` should always provide support for clients one major version lower than the current one. This should make it possible to upgrade `unleash` gradually. Generally, the intention is that `unleash-server` should always provide support for clients one major version lower than the current one. This should make it possible to upgrade `unleash` gradually.
## Upgrading from v4.x to v5.x {#upgrading-from-v4x-to-v5x}
Unleash v5 was released on April 27th, 2023. It contains a few breaking changes.
### Requires Node.js version 18+
Unleash v5 drops support Node.js versions below 18, which is the current active LTS at the time of release. Unleash v4 officially supported Node.js v14 and v16, but both of these will reach end of life in 2023.
### The Google Authenticator provider for SSO has been removed
The Google Authenticator provider is now hidden by default. We recommend using [OpenID Connect](../../how-to/how-to-add-sso-open-id-connect.md) instead.
However, if you are running a self hosted version of Unleash and you need to temporarily re-enable Google SSO, you can do so by setting the `GOOGLE_AUTH_ENABLED` environment variable to `true`. If you're running a hosted version of Unleash, you'll need to reach out to us and ask us to re-enable the flag. However, the ability to do this will be removed in a future release and this is not safe to depend on.
This provider was deprecated in v4.
### Default database password
The Unleash default database password is now `password` instead of `passord`. Turns out that the Norwegian word for password is too similar to the English word, and that people would think it was a typo.
This should only impact dev builds and initial setup. You should never use the default password in any production environments.
### The /api/admin/features API is gone
Most of the old features API was deprecated in v4.3 and superseded by the project API instead. In v5, the deprecated parts have been completely removed. The only operations on that API that are still active are the operations to add or remove a tag from a feature toggle.
### Error message structure
Some of Unleash's API error messages have changed their structure. Specifically, this applies to error messages generated by our OpenAPI validation layer. However, only their structure has changed (and they now contain more human-friendly messages); the error codes should still be the same.
Previously, they would look like this:
``` json
{
"error": "Request validation failed",
"validation": [
{
"keyword": "type",
"dataPath": ".body.parameters",
"schemaPath": "#/components/schemas/addonCreateUpdateSchema/properties/parameters/type",
"params": {
"type": "object"
},
"message": "should be object"
}
]
}
```
Now they look like this instead, and are more in line with the rest of Unleash's error messages.
```json
{
"id": "37a1765f-a5a0-4371-8aa2-341f331579f9",
"name": "ValidationError",
"message": "Request validation failed: the payload you provided doesn't conform to the schema. Check the `details` property for a list of errors that we found.",
"details": [
{
"description": "The .parameters property should be object. You sent [].",
"path": "parameters"
}
]
}
```
As such, if you're relying on the specifics of the error structure for those API errors, you might need to update your handling.
## Upgrading from v3.x to v4.x {#upgrading-from-v3x-to-v4x} ## Upgrading from v3.x to v4.x {#upgrading-from-v3x-to-v4x}
Before you upgrade we strongly recommend that you take a full [database backup](/deploy/database_backup), to make sure you can downgrade to version 3. Before you upgrade we strongly recommend that you take a full [database backup](/deploy/database_backup), to make sure you can downgrade to version 3.