From 7e382a55558d4a8719e8493de5455883a2003759 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Fri, 11 Aug 2023 13:53:23 +0800 Subject: [PATCH] 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 --- .../installation/upgrade-from-gitea.en-us.md | 17 +++++++++++++---- .../installation/upgrade-from-gitea.zh-cn.md | 16 ++++++++++++---- 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 的最新发布版。