From ca169c41a1af8f36be123fbbdf1481412b913eff Mon Sep 17 00:00:00 2001
From: Liuxiaozhen12 <82579298+Liuxiaozhen12@users.noreply.github.com>
Date: Wed, 29 Sep 2021 14:40:47 +0800
Subject: [PATCH] docs: update pd-configuration about upgrade (#6510)

---
 pd-configuration-file.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/pd-configuration-file.md b/pd-configuration-file.md
index b176f75e282f3..3e14a7a54b11f 100644
--- a/pd-configuration-file.md
+++ b/pd-configuration-file.md
@@ -268,11 +268,15 @@ Configuration items related to scheduling
 + Determines whether to enable the merging of cross-table Regions
 + Default value: `true`
 
-### `region-score-formula-version`
+### `region-score-formula-version` <span class="version-mark">New in v5.0</span> 
 
 + Controls the version of the Region score formula
 + Default value: `v2`
-+ Optional values: `v1` and `v2`
++ Optional values: `v1` and `v2`. Compared to v1, the changes in v2 are smoother, and the scheduling jitter caused by space reclaim is improved.
+
+> **Note:**
+>
+> If you have upgraded your cluster from a TiDB 4.0 version to the current version, the new formula version is automatically disabled by default to ensure consistent PD behavior before and after the upgrading. If you want to change the formula version, you need to manually switch through the `pd-ctl` setting. For details, refer to [PD Control](/pd-control.md#config-show--set-option-value--placement-rules).
 
 ### `enable-joint-consensus` <span class="version-mark">New in v5.0</span>
 
@@ -317,6 +321,10 @@ Configuration items related to replicas
 + Default value: 3
 + PD rounds the lowest digits of the flow number, which reduces the update of statistics caused by the changes of the Region flow information. This configuration item is used to specify the number of lowest digits to round for the Region flow information. For example, the flow `100512` will be rounded to `101000` because the default value is `3`. This configuration replaces `trace-region-flow`.
 
+> **Note:**
+>
+> If you have upgraded your cluster from a TiDB 4.0 version to the current version, the behavior of `flow-round-by-digit` after the upgrading and the behavior of `trace-region-flow` before the upgrading are consistent by default. This means that if the value of  `trace-region-flow` is false before the upgrading, the value of `flow-round-by-digit` after the upgrading is 127; if the value of `trace-region-flow` is `true` before the upgrading, the value of `flow-round-by-digit` after the upgrading is `3`.
+
 ## `label-property`
 
 Configuration items related to labels