Omnibus 极狐GitLab 弃用信息

你必须知道
添加废弃消息
跟踪废弃消息的移除
跟踪功能的移除
移除废弃消息

通过废弃消息通知极狐GitLab 管理员功能的废弃和移除包括：

添加废弃消息。
跟踪废弃消息的移除。
跟踪功能的移除。
移除废弃消息。

你必须知道

在添加废弃消息之前，请确保阅读：

添加废弃消息

我们在 Gitlab::Deprecations 类的 list 方法中存储与其相关的废弃列表。如果某个配置需要被废弃，就必须添加到该列表中并提供适当的详细信息。例如：

deprecations = [
          {
            config_keys: %w(gitlab postgresql data_dir),
            deprecation: '11.6',
            removal: '14.0',
            note: "Please see https://gitlab.cn/docs/omnibus/settings/database.html#store-postgresql-data-in-a-different-directory for how to use postgresql['dir']"
          },
          {
            config_keys: %w(gitlab sidekiq cluster),
            deprecation: '13.0',
            removal: '14.0',
            note: "Running sidekiq directly is deprecated. Please see https://gitlab.cn/docs/administration/operations/extra_sidekiq_processes/ for how to use sidekiq-cluster."
          },
...
]

`config_keys`

config_keys 表示一组键列表，可用于从 /opt/gitlab/embedded/nodes/{fqdn}.json 中的配置哈希遍历到特定配置。例如 %w(mattermost log_file_directory) 意味着 mattermost['log_file_directory'] 设置。类似地，%w(gitlab nginx listen_addresses) 意味着 gitlab['nginx']['listen_addresses']。我们内部将其转换为 nginx['listen_addresses']，这就是我们在 /etc/gitlab/gitlab.rb 中使用的。

`deprecation`

deprecation 是您设置废弃更改的 <major>.<minor> 版本的地方。从该版本开始，运行 gitlab-ctl reconfigure 将警告设置将在 removal 版本中被移除，并显示提供的 note。

`removal`

removal 是您设置将不再支持更改的 <major>.<minor> 版本的地方。这几乎总是一个主要版本。Omnibus 软件包在安装开始时运行一个脚本，确保您的设置中没有任何被移除的配置。如果它发现不再支持的配置，安装将提前失败，以避免进行任何更改。同样，运行 gitlab-ctl reconfigure 也会检查 gitlab.rb 文件中的被移除配置。这是为了处理用户简单地将 gitlab.rb 从旧实例复制到新实例的情况。

`note`

note 是在 gitlab-ctl reconfigure 期间提供给用户的废弃消息的一部分。使用此区域来告知用户如何更改他们的设置，通常通过链接到新文档，或者在设置重命名的情况下，告诉他们新设置名称应该是什么。

跟踪废弃消息的移除

废弃消息 不应该 与移除一起清理，因为即使在移除之后，它们也会保护升级，即管理员尝试升级到移除键的版本，但他们尚未迁移所有旧配置。

升级通过运行 Gitlab::Deprecations.check_config 方法来完成，该方法在允许极狐GitLab 软件包更新之前，将现有配置与计划的移除日期进行比较。

此外，我们还有用户可能在升级时跳过多个极狐GitLab 版本。出于这个原因，我们建议废弃消息仅在移除里程碑之后的下一个计划的必需停靠点中移除，按照我们的升级路径。例如：

废弃消息在 15.8 中添加。
旧配置在 16.0 中从代码库中移除。
废弃消息应在 16.3 中移除，因为这是下一个计划的必需停靠点。

要跟踪废弃消息的移除：

使用 Remove Deprecation Message 议题模板创建后续议题。

在您的废弃消息旁添加一个评论，并链接到移除消息的后续议题。例如：

{
  config_keys: ...
  deprecation: '15.8', # Remove message Issue: https://jihulab.com/gitlab-cn/omnibus-gitlab/-/issues/XYZ
  removal: '16.0',
  note: "..."
},

跟踪功能的移除

根据上面你必须知道部分定义要废弃的功能的正确里程碑。然后创建一个后续议题来跟踪功能的移除，并在 removal 键旁添加一个评论，说明哪个议题正在跟踪其移除。例如：

{
  config_keys: ...
  deprecation: '15.8', # Remove message Issue: https://jihulab.com/gitlab-cn/omnibus-gitlab/-/issues/1
  removal: '16.0', # Removal issue: https://jihulab.com/gitlab-cn/omnibus-gitlab/-/issues/2
  note: "..."
},

后续议题应设置为预期移除功能的里程碑。

移除废弃消息

当消息准备好被移除时，您应该：

确保废弃的配置确实在之前的里程碑中被移除。
确保消息移除正在一个必需停靠里程碑中发布，晚于移除配置的里程碑。
打开一个 MR 来移除废弃消息并关闭后续议题。