mirror of
https://github.com/Unleash/unleash.git
synced 2025-07-21 13:47:39 +02:00
docs: Unleash v7 upgrade docs (#10097)
This contains updates to the docs based on the changes done for V7 --------- Co-authored-by: melindafekete <melinda.fekete@getunleash.io>
This commit is contained in:
Gastón Fournier
GitHub
parent
07998e5588
commit
d68f17bb1c
@ -15,8 +15,8 @@ We have created a set of ADRs to help guide the development of the backend:
|
||||
|
||||
Before developing on this project you will need two things:
|
||||
|
||||
- PostgreSQL 13.0+
|
||||
- Node.js v20.0+
|
||||
- PostgreSQL 14.0+
|
||||
- Node.js v22.0+
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
@ -26,9 +26,9 @@ yarn dev
|
||||
|
||||
## PostgreSQL {#postgresql}
|
||||
|
||||
To run and develop Unleash, you need to have PostgreSQL v13.0+ locally.
|
||||
To run and develop Unleash, you need to have PostgreSQL 14.0+ locally.
|
||||
|
||||
Unleash currently also works with PostgreSQL v13.0+, but this might change in a future feature release, and we have stopped running automatic integration tests below PostgreSQL v13. The current recommendation is to use a role with Owner privileges since Unleash uses Postgres functions to simplify our database usage.
|
||||
Unleash currently also works with PostgreSQL v14.0+, but this might change in a future feature release, and we have stopped running automatic integration tests below PostgreSQL 14. The current recommendation is to use a role with Owner privileges since Unleash uses Postgres functions to simplify our database usage.
|
||||
|
||||
### Create a local unleash databases in postgres {#create-a-local-unleash-databases-in-postgres}
|
||||
|
||||
@ -57,7 +57,7 @@ If you don't want to install PostgreSQL locally, you can spin up an Docker insta
|
||||
|
||||
## Start the application {#start-the-application}
|
||||
|
||||
In order to start the application you will need Node.js v14.x or newer installed locally.
|
||||
In order to start the application you will need Node.js v22.x or newer installed locally.
|
||||
|
||||
```
|
||||
// Install dependencies
|
||||
|
||||
@ -210,7 +210,7 @@ However, we recommend not deleting feature flags unless they are completely remo
|
||||
:::
|
||||
|
||||
|
||||
Tags can be used to group feature flags by any criteria, such as functionality, teams, or products, to make them easier to filter and manage. Tags are organized by type, which you can define in the Admin UI under **Configure > Tag types**.
|
||||
Tags can be used to group feature flags by any criteria, such as functionality, teams, or products, to make them easier to filter and manage. Tags are organized by type and color which you can define in the Admin UI under **Configure > Tag types**.
|
||||
|
||||
To assign tags to a feature flag, do the following:
|
||||
1. Open the feature flag and go to the **Tags for this feature flag** section.
|
||||
@ -219,3 +219,17 @@ To assign tags to a feature flag, do the following:
|
||||
4. Click **Save tags**.
|
||||
|
||||
For example, you can create a `slack` tag type and assign Slack channel names as tag values. This lets you configure a Slack integration to send updates about specific feature flags to the correct channels.
|
||||
|
||||
## External links
|
||||
|
||||
:::note Availability
|
||||
|
||||
**Version**: `7.0+`
|
||||
|
||||
:::
|
||||
|
||||
You can add external links to your feature flags, allowing you to connect them to related resources like key metrics, analytics, or issue trackers. You can add a link on the **Overview** page of any feature flag.
|
||||
|
||||
In addition, you can define link templates at the project level in **Settings > Project settings > Enterprise settings > Project link templates**. These templates automatically populate links for all new feature flags within that project. For example, you can create templates to find all usages of
|
||||
a feature flag in your repository or automatically link to a Jira issue when a flag is created from Jira.
|
||||
|
||||
|
||||
@ -11,6 +11,141 @@ Unleash aims to support client SDKs connecting to a server version that is one m
|
||||
|
||||
Before you begin any major version upgrade, we strongly recommend performing a [full backup of your PostgreSQL database](/using-unleash/deploy/configuring-unleash#back-up-and-restore-the-database). This ensures you can restore your instance if issues occur during the upgrade.
|
||||
|
||||
## Upgrading from v6 to v7
|
||||
Unleash v7, released in June 2025, introduced several key changes. Ensure you address the following before or during your upgrade to v7.
|
||||
|
||||
### ESM migration
|
||||
Unleash v7 has fully migrated to ECMAScript Modules (ESM). If you run Unleash from source or using a custom build environment, ensure your environment supports ESM. This change may require updates to your custom scripts or integrations.
|
||||
|
||||
### Requires Node.js version 22+
|
||||
If you run Unleash from source or using a custom build environment (not the official Docker image), you must ensure your environment uses Node.js version 22 or later. Unleash v7 drops support for Node.js versions below 22, which is [active LTS at the time of release](https://github.com/nodejs/Release/blob/cf57a9739438f7a46d8f49b18aa8c2de3f3ca756/README.md#release-schedule).
|
||||
|
||||
### Database requirement: PostgreSQL v14+
|
||||
Unleash v7 requires **PostgreSQL version 14 or later**. Running v7 with older PostgreSQL versions (10, 11, 12, 13) is unsupported, though the server might start with a warning message.
|
||||
|
||||
### API changes
|
||||
|
||||
As part of our commitment to maintaining a clean and robust codebase, several deprecated API endpoints and schema properties have been removed in Unleash v7.
|
||||
|
||||
<details>
|
||||
<summary>Removed API endpoints</summary>
|
||||
|
||||
- **GET `/api/admin/archive/features`**
|
||||
|
||||
Deprecated in: v4.10.0, use `/api/admin/search/features?archived=IS:true` instead.
|
||||
|
||||
---
|
||||
|
||||
- **GET `/api/admin/archive/features/{projectId}`**
|
||||
|
||||
Deprecated in: v4.11.0, use `/api/admin/search/features?project=IS:{projectId}&archived=IS:true` instead.
|
||||
|
||||
---
|
||||
|
||||
- **GET `/api/admin/projects/{projectId}/users`**
|
||||
|
||||
Deprecated in: v4.14.3, use `/api/admin/projects/{projectId}/access` instead.
|
||||
|
||||
---
|
||||
|
||||
- **GET, PATCH, and PUT `/api/admin/projects/{projectId}/features/{featureName}/variants`**
|
||||
|
||||
Deprecated in: v4.21.0, use [strategy variants](https://docs.getunleash.io/reference/strategy-variants) instead.
|
||||
You can create or update variants when creating or adding a strategy to a feature flag.
|
||||
For example: `/api/admin/projects/{projectId}/features/{featureName}/environments/{environment}/strategies`.
|
||||
|
||||
---
|
||||
|
||||
- **POST `/api/admin/projects/{projectId}/role/{roleId}/access`**
|
||||
|
||||
Deprecated in: v5.5.0, use `/api/admin/projects/{projectId}/access` instead.
|
||||
|
||||
---
|
||||
|
||||
- **PUT and DELETE `/api/admin/projects/{projectId}/groups/{groupId}/roles/{roleId}`**
|
||||
|
||||
Deprecated in: v5.5.0, use `/api/admin/projects/{projectId}/groups/{groupId}/roles` instead.
|
||||
|
||||
---
|
||||
|
||||
- **PUT, POST, and DELETE `/api/admin/projects/{projectId}/users/{userId}/roles/{roleId}`**
|
||||
|
||||
Deprecated in: v5.5.0, use `/api/admin/projects/{projectId}/users/{userId}/roles` instead.
|
||||
|
||||
---
|
||||
|
||||
- **GET `/api/admin/projects/{projectId}`**
|
||||
|
||||
Deprecated in: v5.8.0, use `/api/admin/projects/{projectId}/overview` instead.
|
||||
|
||||
---
|
||||
|
||||
- **GET `/api/admin/dashboard/executive`**
|
||||
|
||||
Deprecated in: v5.11.0, use `/api/admin/projects/{projectId}/overview` instead.
|
||||
|
||||
---
|
||||
|
||||
- **POST `/api/admin/events/search`**
|
||||
|
||||
Deprecated in: v6.1.0, use `/api/admin/search/events` instead.
|
||||
|
||||
---
|
||||
|
||||
- **GET `/api/admin/metrics/traffic/{period}`**
|
||||
|
||||
Deprecated in: v6.8.0, use `/api/admin/metrics/traffic` instead.
|
||||
|
||||
---
|
||||
|
||||
- **POST `/api/admin/ui-config`**
|
||||
|
||||
Deprecated in: v6.9.0, use `/api/admin/ui-config/cors` instead.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Removed schema properties</summary>
|
||||
|
||||
- **`username`**
|
||||
|
||||
Removed from `apiTokenSchema` and `createApiTokenSchema`.
|
||||
Deprecated in: v5.1.0 and v5.3.0
|
||||
Affected endpoints: `/api/admin/api-tokens`, `/api/admin/api-tokens/{name}`, and `/api/admin/projects/{projectId}/api-tokens`.
|
||||
|
||||
---
|
||||
|
||||
- **`environment`**
|
||||
|
||||
Removed from `sdkContextSchema`, `clientApplicationSchema`, `clientMetricsSchema`, and `clientFeaturesQuerySchema`.
|
||||
Deprecated in: v5.2.0
|
||||
Affected endpoints: Client API and Playground endpoints. Environment is now part of the API token.
|
||||
|
||||
---
|
||||
|
||||
- **`isAPI`**
|
||||
|
||||
Removed from `userSchema`.
|
||||
Deprecated in: v5.3.0
|
||||
Affected endpoints: `/api/admin/user`, `/api/admin/user-admin`, `/api/admin/user-admin/access`, `/api/admin/user-admin/search`, `/api/admin/user-admin/{id}`, `/api/admin/access/overview`,
|
||||
`/api/admin/projects/{projectId}/access`, `/api/admin/groups`, `/api/admin/groups/{groupId}`, `/api/admin/invite-link/tokens`, `/api/admin/user-admin/{id}/permissions`, `/auth/simple/login`,
|
||||
`api/admin/projects/{projectId}/access`, `/invite/{token}/signup`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Previously deprecated endpoints restored in v7</summary>
|
||||
- **GET `/api/admin/instance-admin/statistics`**
|
||||
|
||||
Deprecated in 4.17.0 - This was accidental and it has now been fully restored.
|
||||
|
||||
---
|
||||
|
||||
- **POST `/api/admin/strategies`**
|
||||
|
||||
Deprecated in v6.0.0 but, due to user feedback, it has been reintroduced in v7.0.0. It can be used to create custom strategies.
|
||||
</details>
|
||||
|
||||
## Upgrading from v5 to v6
|
||||
|
||||
[Unleash v6](https://github.com/Unleash/unleash/issues/4380), released in June 2024, introduced several key changes. Ensure you address the following before or during your upgrade to v6.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user