adjust upgrade notes (#603)

* adjust upgrade notes

* add newline between two notes

docs/GettingStarted/DockerComposeSetup.md

@@ -22,7 +22,7 @@ sidebar_position: 1
 
    Copy the generated string. Set the value of the ENCRYPTION_SECRET environment variable:
 
-   - Method 1: In a terminal session, run the following command: export ENCRYPTION_SECRET="copied string"
+   - 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.
@@ -42,11 +42,16 @@ 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 notes:
+
+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 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. Run `docker-compose up -d` to start DevLake 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.
 
 ## FAQ
 

docs/GettingStarted/Upgrade.md

@@ -10,6 +10,13 @@ description: How to upgrade your Apache DevLake to a newer version
 
 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.
 
-3. Upgrade to v0.18.0+: When upgrading from a previous version of DevLake, you can find the ENCRYPTION_SECRET in the .env file. Note that in versions prior to v0.18, the ENCRYPTION_SECRET was referred to as ENCODE_KEY. Please assign its value to the ENCRYPTION_SECRET environment variable. This will ensure that the encryption process continues to work as expected.
+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.
+
+4. Upgrade to v0.18.0+: When upgrading from a previous version of DevLake, you need to find the ENCODE_KEY value in the .env file of devlake container, and assign the value to ENCRYPTION_SECRET according to the upgrade steps, see [helm setup](https://devlake.apache.org/docs/next/GettingStarted/HelmSetup) or [docker compose setup](https://devlake.apache.org/docs/next/GettingStarted/DockerComposeSetup). This will ensure that the encryption process continues to work as expected.
+
+5. Upgrade to v0.18.0+: When upgrading from a previous version of DevLake, You may encounter the below error when upgrading because the built-in grafana has been replaced by the official grafana dependency. So you may need to delete the grafana deployment first, please also take care of Note 3 before deleting.
+
+> 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
+
 
 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.