Adjust upgrade note (#646)

* adjust upgrade notes

* adjust upgrade note

* adjust upgrade notes

* fix grammar issue

docs/GettingStarted/DockerComposeSetup.md

@@ -25,7 +25,7 @@ sidebar_position: 1
    - Method 1: In the docker-compose.yml, set an environment variable ENCRYPTION_SECRET: "copied string"
    - Method 2: Alternatively, you can set the ENCRYPTION_SECRET environment variable in the .env file: ENCRYPTION_SECRET="copied string"
 
-     If you set the ENCRYPTION_SECRET environment variable in both the terminal session and the .env file, the value set in the terminal session takes precedence.
+     If you set the ENCRYPTION_SECRET environment variable in both docker-compose.yml and the .env file, the value set in docker-compose.yml takes precedence.
 
    **Please make sure to keep the ENCRYPTION_SECRET safe as it is used to encrypt sensitive information in the database, such as personal access tokens and passwords. If ENCRYPTION_SECRET is lost, it may not be possible to decrypt this sensitive information.**
 
@@ -44,16 +44,17 @@ sidebar_position: 1
 
 ## Upgrade to a newer version
 
-Please notes:
+Please note:
 
-Note 1: **Back up your Grafana dashboards** before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+Note 1: **Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
 Note 2: **If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or later versions**, you need to find the ENCODE_KEY value in the .env file of devlake container, and assign the value to ENCRYPTION_SECRET via .env file or environment variable in docker-compose.yml
 
 1. Run `docker-compose down` to stop services;
-2. Open file "docker-compose.yml". Change the image tags of "grafana", "devlake" and "config-ui" to the new version, and save; 
-3. If upgrading from earlier versions to v0.18.0+, set ENCRYPTION_SECRET environment variable in docker-compose.yml or .env file, refer to above Note 2.
-4. Run `docker-compose up -d` to start DevLake services.
+2. Download `docker-compose.yml` and `env.example` from the [latest release](https://github.com/apache/incubator-devlake/releases/tag/v0.19.0-beta1).
+3. Use the new `docker-compose.yml` and `env.example` to replace the old `docker-compose.yml` and `.env`; Or if you have modified/customized values in the old files, compare the new files with the old ones, adjust the old files according to the new ones.
+4. If upgrading from earlier versions to v0.18.0+, set the ENCRYPTION_SECRET environment variable in docker-compose.yml or .env file, refer to above Note 2.
+5. Run `docker-compose up -d` to start DevLake services.
 
 ## FAQ
 

docs/GettingStarted/HelmSetup.md

@@ -70,6 +70,8 @@ grafana by url `http://YOUR-NODE-IP:30091`
 
 **Note:**
 
+**Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+
 **If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or later versions:**
 
 1. Copy the ENCODE_KEY value from /app/config/.env of the lake pod (e.g. devlake-lake-0), and replace the <ENCRYPTION_SECRET> in the upgrade command below.

docs/GettingStarted/Upgrade.md

@@ -8,7 +8,7 @@ description: How to upgrade your Apache DevLake to a newer version
 
 1. ENCRYPTION_SECRET: It is important to keep the ENCRYPTION_SECRET safe as it is used to encrypt sensitive information in the database, such as personal access tokens and passwords. Losing the ENCRYPTION_SECRET may result in the inability to decrypt this sensitive information.
 
-2. .env file: The .env file is now optional. You can choose to store your variables in the environment instead. Remember to consider critical variables such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and .env file exist, the values in the environment variables will take precedence. However, make sure that these variables are defined in either one of them to avoid any issues with DevLake.
+2. .env file: The .env file is now optional. You can choose to store your variables in the environment instead. Remember to consider important variables such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and the .env file exist, the values in the environment variables will take precedence. However, make sure that these variables are defined in either one of them to avoid any issues with DevLake.
 
 3. Back up your Grafana dashboards before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
@@ -18,5 +18,6 @@ description: How to upgrade your Apache DevLake to a newer version
 
 > Error: UPGRADE FAILED: cannot patch "devlake-grafana" with kind Deployment: Deployment.apps "devlake-grafana" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/instance":"devlake", "app.kubernetes.io/name":"grafana"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
 
+6. When upgrading via docker-compose.yml, please download the new docker-compose.yml and env.example from [release assets](https://github.com/apache/incubator-devlake/releases) to do the upgrade, please refer to [docker compose upgrade notes](./DockerComposeSetup.md)
 
 These notes provide guidance on upgrading your Apache DevLake to a newer version. Ensure you follow them carefully to avoid any issues during the upgrade process.

versioned_docs/version-v0.16/GettingStarted/DockerComposeSetup.md

@@ -27,7 +27,7 @@ sidebar_position: 1
 
 ## Upgrade to a newer version
 
-Please note: **Back up your Grafana dashboards** before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+Please note: **Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
 1. Run `docker-compose down` to stop services;
 2. Open file "docker-compose.yml". Change the image tags of "grafana", "devlake" and "config-ui" to the new version, and save;

versioned_docs/version-v0.17/GettingStarted/DockerComposeSetup.md

@@ -27,7 +27,7 @@ sidebar_position: 1
 
 ## Upgrade to a newer version
 
-Please note: **Back up your Grafana dashboards** before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+Please note: **Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
 1. Run `docker-compose down` to stop services;
 2. Open file "docker-compose.yml". Change the image tags of "grafana", "devlake" and "config-ui" to the new version, and save;

versioned_docs/version-v0.18/GettingStarted/DockerComposeSetup.md

@@ -25,7 +25,7 @@ sidebar_position: 1
    - Method 1: In the docker-compose.yml, set an environment variable ENCRYPTION_SECRET: "copied string"
    - Method 2: Alternatively, you can set the ENCRYPTION_SECRET environment variable in the .env file: ENCRYPTION_SECRET="copied string"
 
-     If you set the ENCRYPTION_SECRET environment variable in both the terminal session and the .env file, the value set in the terminal session takes precedence.
+     If you set the ENCRYPTION_SECRET environment variable in both docker-compose.yml and the .env file, the value set in docker-compose.yml takes precedence.
 
    **Please make sure to keep the ENCRYPTION_SECRET safe as it is used to encrypt sensitive information in the database, such as personal access tokens and passwords. If ENCRYPTION_SECRET is lost, it may not be possible to decrypt this sensitive information.**
 
@@ -44,16 +44,17 @@ sidebar_position: 1
 
 ## Upgrade to a newer version
 
-Please notes:
+Please note:
 
-Note 1: **Back up your Grafana dashboards** before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+Note 1: **Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
 Note 2: **If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or later versions**, you need to find the ENCODE_KEY value in the .env file of devlake container, and assign the value to ENCRYPTION_SECRET via .env file or environment variable in docker-compose.yml
 
 1. Run `docker-compose down` to stop services;
-2. Open file "docker-compose.yml". Change the image tags of "grafana", "devlake" and "config-ui" to the new version, and save; 
-3. If upgrading from earlier versions to v0.18.0+, set ENCRYPTION_SECRET environment variable in docker-compose.yml or .env file, refer to above Note 2.
-4. Run `docker-compose up -d` to start DevLake services.
+2. Download `docker-compose.yml` and `env.example` from the [latest release](https://github.com/apache/incubator-devlake/releases/tag/v0.18.0).
+3. Use the new `docker-compose.yml` and `env.example` to replace the old `docker-compose.yml` and `.env`; Or if you have modified/customized values in the old files, compare the new files with the old ones, adjust the old files according to the new ones.
+4. If upgrading from earlier versions to v0.18.0+, set the ENCRYPTION_SECRET environment variable in docker-compose.yml or .env file, refer to above Note 2.
+5. Run `docker-compose up -d` to start DevLake services.
 
 ## FAQ
 

versioned_docs/version-v0.18/GettingStarted/HelmSetup.md

@@ -70,6 +70,8 @@ grafana by url `http://YOUR-NODE-IP:30091`
 
 **Note:**
 
+**Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+
 **If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or later versions:**
 
 1. Copy the ENCODE_KEY value from /app/config/.env of the lake pod (e.g. devlake-lake-0), and replace the <ENCRYPTION_SECRET> in the upgrade command below.

versioned_docs/version-v0.18/GettingStarted/Upgrade.md

@@ -8,7 +8,7 @@ description: How to upgrade your Apache DevLake to a newer version
 
 1. ENCRYPTION_SECRET: It is important to keep the ENCRYPTION_SECRET safe as it is used to encrypt sensitive information in the database, such as personal access tokens and passwords. Losing the ENCRYPTION_SECRET may result in the inability to decrypt this sensitive information.
 
-2. .env file: The .env file is now optional. You can choose to store your variables in the environment instead. Remember to consider critical variables such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and .env file exist, the values in the environment variables will take precedence. However, make sure that these variables are defined in either one of them to avoid any issues with DevLake.
+2. .env file: The .env file is now optional. You can choose to store your variables in the environment instead. Remember to consider important variables such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and the .env file exist, the values in the environment variables will take precedence. However, make sure that these variables are defined in either one of them to avoid any issues with DevLake.
 
 3. Back up your Grafana dashboards before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
@@ -18,5 +18,6 @@ description: How to upgrade your Apache DevLake to a newer version
 
 > Error: UPGRADE FAILED: cannot patch "devlake-grafana" with kind Deployment: Deployment.apps "devlake-grafana" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/instance":"devlake", "app.kubernetes.io/name":"grafana"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
 
+6. When upgrading via docker-compose.yml, please download the new docker-compose.yml and env.example from [release assets](https://github.com/apache/incubator-devlake/releases) to do the upgrade, please refer to [docker compose upgrade notes](./DockerComposeSetup.md)
 
 These notes provide guidance on upgrading your Apache DevLake to a newer version. Ensure you follow them carefully to avoid any issues during the upgrade process.

versioned_docs/version-v0.19/GettingStarted/DockerComposeSetup.md

@@ -25,7 +25,7 @@ sidebar_position: 1
    - Method 1: In the docker-compose.yml, set an environment variable ENCRYPTION_SECRET: "copied string"
    - Method 2: Alternatively, you can set the ENCRYPTION_SECRET environment variable in the .env file: ENCRYPTION_SECRET="copied string"
 
-     If you set the ENCRYPTION_SECRET environment variable in both the terminal session and the .env file, the value set in the terminal session takes precedence.
+     If you set the ENCRYPTION_SECRET environment variable in both docker-compose.yml and the .env file, the value set in docker-compose.yml takes precedence.
 
    **Please make sure to keep the ENCRYPTION_SECRET safe as it is used to encrypt sensitive information in the database, such as personal access tokens and passwords. If ENCRYPTION_SECRET is lost, it may not be possible to decrypt this sensitive information.**
 
@@ -44,16 +44,17 @@ sidebar_position: 1
 
 ## Upgrade to a newer version
 
-Please notes:
+Please note:
 
-Note 1: **Back up your Grafana dashboards** before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+Note 1: **Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
 Note 2: **If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or later versions**, you need to find the ENCODE_KEY value in the .env file of devlake container, and assign the value to ENCRYPTION_SECRET via .env file or environment variable in docker-compose.yml
 
 1. Run `docker-compose down` to stop services;
-2. Open file "docker-compose.yml". Change the image tags of "grafana", "devlake" and "config-ui" to the new version, and save; 
-3. If upgrading from earlier versions to v0.18.0+, set ENCRYPTION_SECRET environment variable in docker-compose.yml or .env file, refer to above Note 2.
-4. Run `docker-compose up -d` to start DevLake services.
+2. Download `docker-compose.yml` and `env.example` from the [latest release](https://github.com/apache/incubator-devlake/releases/tag/v0.19.0-beta1).
+3. Use the new `docker-compose.yml` and `env.example` to replace the old `docker-compose.yml` and `.env`; Or if you have modified/customized values in the old files, compare the new files with the old ones, adjust the old files according to the new ones.
+4. If upgrading from earlier versions to v0.18.0+, set the ENCRYPTION_SECRET environment variable in docker-compose.yml or .env file, refer to above Note 2.
+5. Run `docker-compose up -d` to start DevLake services.
 
 ## FAQ
 

versioned_docs/version-v0.19/GettingStarted/HelmSetup.md

@@ -70,6 +70,8 @@ grafana by url `http://YOUR-NODE-IP:30091`
 
 **Note:**
 
+**Back up your Grafana dashboards** before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
+
 **If you're upgrading from DevLake v0.17.x or earlier versions to v0.18.x or later versions:**
 
 1. Copy the ENCODE_KEY value from /app/config/.env of the lake pod (e.g. devlake-lake-0), and replace the <ENCRYPTION_SECRET> in the upgrade command below.

versioned_docs/version-v0.19/GettingStarted/Upgrade.md

@@ -8,7 +8,7 @@ description: How to upgrade your Apache DevLake to a newer version
 
 1. ENCRYPTION_SECRET: It is important to keep the ENCRYPTION_SECRET safe as it is used to encrypt sensitive information in the database, such as personal access tokens and passwords. Losing the ENCRYPTION_SECRET may result in the inability to decrypt this sensitive information.
 
-2. .env file: The .env file is now optional. You can choose to store your variables in the environment instead. Remember to consider critical variables such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and .env file exist, the values in the environment variables will take precedence. However, make sure that these variables are defined in either one of them to avoid any issues with DevLake.
+2. .env file: The .env file is now optional. You can choose to store your variables in the environment instead. Remember to consider important variables such as ENCRYPTION_SECRET and DB_URL. If both the environment variables and the .env file exist, the values in the environment variables will take precedence. However, make sure that these variables are defined in either one of them to avoid any issues with DevLake.
 
 3. Back up your Grafana dashboards before upgrade if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.
 
@@ -18,5 +18,6 @@ description: How to upgrade your Apache DevLake to a newer version
 
 > Error: UPGRADE FAILED: cannot patch "devlake-grafana" with kind Deployment: Deployment.apps "devlake-grafana" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/instance":"devlake", "app.kubernetes.io/name":"grafana"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable
 
+6. When upgrading via docker-compose.yml, please download the new docker-compose.yml and env.example from [release assets](https://github.com/apache/incubator-devlake/releases) to do the upgrade, please refer to [docker compose upgrade notes](./DockerComposeSetup.md)
 
 These notes provide guidance on upgrading your Apache DevLake to a newer version. Ensure you follow them carefully to avoid any issues during the upgrade process.