Update upgrade documentation to add a check for deprecated configurations (#26451)

fix
https://github.com/go-gitea/gitea/issues/25995#issuecomment-1674096710

---------

Co-authored-by: silverwind <me@silverwind.io>

2 files changed, 25 insertions, 8 deletions

diff --git a/docs/content/installation/upgrade-from-gitea.en-us.md b/docs/content/installation/upgrade-from-gitea.en-us.md
index 9b82de467a..984f2d1336 100644
--- a/docs/content/installation/upgrade-from-gitea.en-us.md
+++ b/docs/content/installation/upgrade-from-gitea.en-us.md
@@ -17,16 +17,20 @@ menu:
 
 # Upgrade from an old Gitea
 
-To update Gitea, download a newer version, stop the old one, perform a backup, and run the new one.
-Every time a Gitea instance starts up, it checks whether a database migration should be run.
-If a database migration is required, Gitea will take some time to complete the upgrade and then serve.
+Follow below steps to ensure a smooth upgrade to a new Gitea version.
 
 ## Check the Changelog for breaking changes
 
 To make Gitea better, some breaking changes are unavoidable, especially for big milestone releases.
-Before upgrade, please read the [Changelog on Gitea blog](https://blog.gitea.io/)
+Before upgrading, please read the [Changelog on Gitea blog](https://blog.gitea.com/)
 and check whether the breaking changes affect your Gitea instance.
 
+## Verify there are no deprecated configuration options
+
+New versions of Gitea often come with changed configuration syntax or options which are usually displayed for
+at least one release cycle inside at the top of the Site Administration panel. If these warnings are not
+resolved, Gitea may refuse to start in the following version.
+
 ## Backup for downgrade
 
 Gitea keeps compatibility for patch versions whose first two fields are the same (`a.b.x` -> `a.b.y`),
@@ -60,6 +64,11 @@ Backup steps:
 If you are using cloud services or filesystems with snapshot feature,
 a snapshot for the Gitea data volume and related object storage is more convenient.
 
+After all of steps have been prepared, download the new version, stop the application, perform a backup and
+then start the new application. On each startup, Gitea verifies that the database is up to date and will automtically
+perform any necessary migrations. Depending on the size of the database, this can take some additional time on the
+first launch during which the application will be unavailable.
+
 ## Upgrade with Docker
 
 * `docker pull` the latest Gitea release.
diff --git a/docs/content/installation/upgrade-from-gitea.zh-cn.md b/docs/content/installation/upgrade-from-gitea.zh-cn.md
index c0ad8d551a..6300917e2d 100644
--- a/docs/content/installation/upgrade-from-gitea.zh-cn.md
+++ b/docs/content/installation/upgrade-from-gitea.zh-cn.md
@@ -15,16 +15,20 @@ menu:
 
 # 从旧版 Gitea 升级
 
-想要升级 Gitea，只需要下载新版，停止运行旧版，进行数据备份，然后运行新版就好。
-每次 Gitea 实例启动时，它都会检查是否要进行数据库迁移。
-如果需要进行数据库迁移，Gitea 会花一些时间完成升级然后继续服务。
+在升级之前，您需要做如下的准备工作。
 
 ## 为重大变更检查更新日志
 
 为了让 Gitea 变得更好，进行重大变更是不可避免的，尤其是一些里程碑更新的发布。
-在更新前，请 [在 Gitea 博客上阅读更新日志](https://blog.gitea.io/)
+在更新前，请 [在 Gitea 博客上阅读更新日志](https://blog.gitea.com/)
 并检查重大变更是否会影响你的 Gitea 实例。
 
+## 在控制面板中检查过期的配置项
+
+一些配置项可能会在后续版本中过期，你需要在控制面板中检查他们。如果不解决过期的配置项，
+Gitea也许会在升级后无法重启。你可以访问 https://docs.gitea.com 获得要升级的版本
+对应的文档来修改你的配置文件。
+
 ## 降级前的备份
 
 Gitea 会保留首二位版本号相同的版本的兼容性 (`a.b.x` -> `a.b.y`)，
@@ -56,6 +60,10 @@ Gitea 会保留首二位版本号相同的版本的兼容性 (`a.b.x` -> `a.b.y`
 如果你在使用云服务或拥有快照功能的文件系统，
 最好对 Gitea 的数据盘及相关资料存储进行一次快照。
 
+在所有上述步骤准备妥当之后，要升级 Gitea，只需要下载新版，停止运行旧版，进行数据备份，然后运行新版就好。
+每次 Gitea 实例启动时，它都会检查是否要进行数据库迁移。
+如果需要进行数据库迁移，Gitea 会花一些时间完成升级然后继续服务。
+
 ## 从 Docker 升级
 
 * `docker pull` 拉取 Gitea 的最新发布版。