From 7a28ad648344bc785907e175014a840f50923f22 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Fri, 11 Aug 2023 09:02:21 +0800 Subject: [PATCH 1/4] Update upgrade documentation to add a check for deprecated configurations --- .../installation/upgrade-from-gitea.en-us.md | 16 ++++++++++++---- .../installation/upgrade-from-gitea.zh-cn.md | 16 ++++++++++++---- 2 files changed, 24 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 9b82de467a2a7..4fe3f27b12621 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. +Before upgrade to a new version of Gitea, you need to do some preparation. ## 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 upgrade, please read the [Changelog on Gitea blog](https://blog.gitea.com/) and check whether the breaking changes affect your Gitea instance. +## Check Deprecated Configurations from admin panel + +Some configurations will be deprecated in future versions, you need to check them from admin panel's topbar. +If these deprecated configurations are not resolved, Gitea may refuse to start. You can also get the correct +configuration from this version documentation on https://docs.gitea.com + ## 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,10 @@ 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 those has been prepared, 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. + ## 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 c0ad8d551a1a6..6300917e2d5c1 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 的最新发布版。 From 78ec6398914b1cb6a53c5fc8085cbc4189dd7da3 Mon Sep 17 00:00:00 2001 From: Jason Song Date: Fri, 11 Aug 2023 10:29:09 +0800 Subject: [PATCH 2/4] Apply suggestions from code review --- docs/content/installation/upgrade-from-gitea.en-us.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/installation/upgrade-from-gitea.en-us.md b/docs/content/installation/upgrade-from-gitea.en-us.md index 4fe3f27b12621..1d0cee6500f31 100644 --- a/docs/content/installation/upgrade-from-gitea.en-us.md +++ b/docs/content/installation/upgrade-from-gitea.en-us.md @@ -22,7 +22,7 @@ Before upgrade to a new version of Gitea, you need to do some preparation. ## 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.com/) +Before upgrading, please read the [Changelog on Gitea blog](https://blog.gitea.com/) and check whether the breaking changes affect your Gitea instance. ## Check Deprecated Configurations from admin panel @@ -64,7 +64,7 @@ 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 those has been prepared, to update Gitea, download a newer version, stop the old one, perform a backup, and run the new one. +After all of those have been prepared, 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. From 51234761c43ce81a85b651c11c95ec435e9ca6bf Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Fri, 11 Aug 2023 13:10:37 +0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: silverwind --- .../installation/upgrade-from-gitea.en-us.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/content/installation/upgrade-from-gitea.en-us.md b/docs/content/installation/upgrade-from-gitea.en-us.md index 1d0cee6500f31..486b05f783975 100644 --- a/docs/content/installation/upgrade-from-gitea.en-us.md +++ b/docs/content/installation/upgrade-from-gitea.en-us.md @@ -17,7 +17,7 @@ menu: # Upgrade from an old Gitea -Before upgrade to a new version of Gitea, you need to do some preparation. +Follow below steps to ensure a smooth upgrade to a new Gitea version. ## Check the Changelog for breaking changes @@ -25,12 +25,11 @@ To make Gitea better, some breaking changes are unavoidable, especially for big Before upgrading, please read the [Changelog on Gitea blog](https://blog.gitea.com/) and check whether the breaking changes affect your Gitea instance. -## Check Deprecated Configurations from admin panel - -Some configurations will be deprecated in future versions, you need to check them from admin panel's topbar. -If these deprecated configurations are not resolved, Gitea may refuse to start. You can also get the correct -configuration from this version documentation on https://docs.gitea.com +## 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`), @@ -64,9 +63,10 @@ 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 those have been prepared, 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. +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 From 810ba97dcab02ce37c6ffece05c7535732d5ffec Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Fri, 11 Aug 2023 13:27:11 +0800 Subject: [PATCH 4/4] Fix markdown lint --- docs/content/installation/upgrade-from-gitea.en-us.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/installation/upgrade-from-gitea.en-us.md b/docs/content/installation/upgrade-from-gitea.en-us.md index 4fe3f27b12621..392deee51cec1 100644 --- a/docs/content/installation/upgrade-from-gitea.en-us.md +++ b/docs/content/installation/upgrade-from-gitea.en-us.md @@ -29,7 +29,7 @@ and check whether the breaking changes affect your Gitea instance. Some configurations will be deprecated in future versions, you need to check them from admin panel's topbar. If these deprecated configurations are not resolved, Gitea may refuse to start. You can also get the correct -configuration from this version documentation on https://docs.gitea.com +configuration from this version documentation on https://docs.gitea.com . ## Backup for downgrade