参与其中

• 1: 设计
• 1.1: SecurityPolicy
• 2: 路线图
• 3: 开发者指南
• 4: 贡献
• 5: 参与 Envoy Gateway 文档工作
• 6: 发布流程
• 7: 维护者
• 8: 文档内容编写规范（中文）
• 9: 行为准则

1 - 设计

1.1 - SecurityPolicy

概述

本设计文档引入了 SecurityPolicy API，允许系统管理员为进入网关的流量配置身份验证和鉴权策略。

目标

• 添加 API 定义以保存用于配置进入网关的流量的身份验证和鉴权规则的设置。

非目标

• 定义该 API 中的 API 配置字段。

实现

SecurityPolicy 是一个策略附件类型的 API，可用于扩展 Gateway API 来定义身份验证和鉴权规则。

示例

以下示例重点介绍了用户如何配置此 API。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
  namespace: default
spec:
  gatewayClassName: eg
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: backend
  namespace: default
spec:
  parentRefs:
    - name: eg
  hostnames:
    - "www.example.com"
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: backend
          port: 3000
          weight: 1
      matches:
        - path:
            type: PathPrefix
            value: /
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: jwt-authn-policy
  namespace: default
spec:
  jwt:
    providers:
    - name: example
      remoteJWKS:
        uri: https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/jwks.json
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: eg
    namespace: default

功能及 API 字段

以下是此 API 中包含的功能列表：

• JWT 基础鉴权
• OIDC 鉴权
• 外部认证
• Basic Auth
• API Key Auth
• CORS（跨域）

设计决策

• 此 API 仅支持单个 targetRef，并且可以绑定到 Gateway 资源或 HTTPRoute 或 GRPCRoute。
• 此 API 资源必须与 targetRef 资源属于同一命名空间
• 只能有一个策略资源附加到特定的 targetRef，例如 Gateway 内的 Listener（部分）
• 如果策略针对某个资源但无法附加到该资源，则应使用 Conflicted=True 条件将该信息反映在“策略状态”字段中。
• 如果多个策略针对同一资源，则最旧的资源（基于创建时间戳）将附加到网关侦听器，其他资源则不会。
• 如果策略 A 具有包含 sectionName 的 targetRef，即它以 Gateway 内的特定侦听器为目标， 并且策略 B 具有以同一整个 Gateway 为目标的 targetRef，则
  • 策略 A 将应用/附加到 targetRef.SectionName 中定义的特定监听器
  • 策略 B 将应用于 Gateway 内的其余侦听器。策略 B 将具有附加状态条件 Overridden=True。
• 针对拥有具体范围的策略胜过针对缺少具体范围的策略。即，针对 xRoute（HTTPRoute 或 GRPCRoute）的策略会覆盖针对侦听器的策略， 该侦听器是该路由的 parentRef，而侦听器又会覆盖针对侦听器/部分所属 Gateway 的策略。

替代方案

• 项目可以无限期地等待这些配置参数成为 Gateway API 的一部分。

2 - 路线图

本文档可作为 Envoy Gateway 用户和贡献者了解项目方向的高级参考。

为路线图做出贡献

• 要将功能添加到路线图中，请创建 Issue 或加入社区会议来讨论您的用例。 如果您的功能被接受，维护人员会将您的 Issue 分配到发布里程碑并相应地更新此文档。
• 为了帮助解决现有的路线图项，请对相关 Issue 进行评论或将自己分配到该 Issue。
• 如果路线图项没有 Issue，请创建一个 Issue，将自己分配到该 Issue，并参考此文档。 维护者将提交 Pull Request 以将该功能添加到路线图中。 **注意：**在实现该功能之前，应在 Issue 或社区会议上讨论该功能。

如果您不知道从哪里开始贡献，需要帮助来减少技术、自动化和文档债务。查找带有 help wanted 标签的 Issue 以开始。

细节

路线图功能和时间表可能会根据反馈、社区贡献等而改变。 如果您依赖特定的路线图项，我们鼓励您参加社区会议讨论细节，或者通过为项目做出贡献来帮助我们提供该功能。

最后更新时间：2023 年 4 月

v0.2.0: 建立坚实的基础

• 完成核心 Envoy Gateway 实现 - Issue #60。
• 建立初步测试、e2e、集成等 - Issue #64。
• 建立用户和开发人员项目文档 - Issue #17。
• 实现 Gateway API 一致性（例如路由、LB、标头转换等）- Issue #65。
• 设置 CI/CD 流程 - Issue #63。

v0.3.0: 通过扩展机制驱动高级功能

• 支持扩展 Gateway API 字段 Issue #707。
• 支持实验性 Gateway API，例如 TCPRoute Issue #643、UDPRoute Issue #641 和 GRPCRoute Issue #642。
• 制定利用 Gateway API 扩展的指南 Issue #675。
• 限流 Issue #670。
• 认证 Issue #336。

v0.4.0: 自定义 Envoy Gateway

• 扩展 Envoy Gateway 控制平面 Issue #20
• 基于 Helm 的 Envoy Gateway 安装 Issue #650
• 自定义被管理的 Envoy Proxy Kubernetes 资源字段 Issue #648
• 配置 xDS Bootstrap Issue #31

v0.5.0: 可观察性和扩缩容

• 数据平面的可观察性 Issue #699。
• 允许用户配置 xDS 资源 Issue #24。

v0.6.0: 为 GA 做准备

• 控制平面的可观察性 Issue #700。
• 计算并记录 Envoy Gateway 性能 Issue #1365。
• 添加 TrafficPolicy API 以实现高级功能 Issue #1492。
• Envoy Gateway 满足就绪标准 Issue #1160。

3 - 开发者指南

Envoy Gateway 使用基于 make 的构建系统进行构建。我们的 CI 使用基于 Github Actions 的工作流建设。

先决条件

go

• 版本：1.20
• 安装指南：https://go.dev/doc/install

make

• 推荐版本：4.0 或更高
• 安装指南：https://www.gnu.org/software/make

docker

• 当您想要构建 Docker 镜像或在 Docker 内运行 make 时可选。
• 推荐版本：20.10.16
• 安装指南：https://docs.docker.com/engine/install

python3

• 需要一个 python3 程序
• 必须有一个正常运行的 venv 模块；这是标准库的一部分，但某些发行版使用 stub 将其替换（例如 Debian 和 Ubuntu）， 并要求您单独安装 python3-venv 包。

快速开始

• 运行 make help 以查看构建、测试和运行 Envoy Gateway 的所有可用目标。

构建

• 运行 make build 来构建所有二进制文件。
• 运行 make build BINS="envoy-gateway" 来构建 Envoy Gateway 二进制文件。
• 运行 make build BINS="egctl" 来构建 egctl 二进制文件。

**注意：**二进制文件在 bin/$OS/$ARCH 目录中生成，例如，bin/linux/amd64/。

测试

• 运行 make test 来运行 golang 测试。

• 运行 make testdata 生成标准的 YAML 测试数据文件。

运行 Linter

• 运行 make lint 以确保您的代码通过所有 Linter 检查。

注意：golangci-lint 配置位于此处。

构建并推送镜像

• 运行 IMAGE=docker.io/you/gateway-dev make image 来构建 Docker 镜像。
• 运行 IMAGE=docker.io/you/gateway-dev make push-multiarch 来构建并推送多架构 Docker 镜像。

**注意：**将 IMAGE 替换为您的仓库的镜像名称。

部署 Envoy Gateway 进行测试/开发

• 运行 make create-cluster 创建一个 Kind 集群。

选项 1：使用最新的 gateway-dev 镜像

• 运行 TAG=latest make kube-deploy 以使用最新镜像在 Kind 集群中部署 Envoy Gateway。 替换 latest 以使用不同的镜像标签。

选项 2：使用自定义镜像

• 运行 make kube-install-image 从当前分支的最新构建镜像并将其加载到 Kind 集群中。
• 运行 IMAGE_PULL_POLICY=IfNotPresent make kube-deploy 以使用自定义镜像将 Envoy Gateway 安装到 Kind 集群中。

在 Kubernetes 中部署 Envoy Gateway

• 运行 TAG=latest make kube-deploy 以使用最新镜像将 Envoy Gateway 部署到 Kubernetes 集群（链接到当前 kube 上下文）。 在命令前面加上 IMAGE 或替换 TAG 以使用不同的 Envoy Gateway 镜像或标签。
• 运行 make kube-undeploy 从集群中卸载 Envoy Gateway。

**注意：**Envoy Gateway 针对 Kubernetes v1.24.0 进行了测试。

演示设置

• 运行 make kube-demo 来部署演示后端服务、GatewayClass、Gateway 和 HTTPRoute 资源 （类似于快速入门文档中概述的步骤）并测试配置。
• 运行 make kube-demo-undeploy 删除 make kube-demo 命令创建的资源。

运行 Gateway API 一致性测试

通过以下命令将 Envoy Gateway 部署到 Kubernetes 集群并运行 Gateway API 一致性测试。 请参阅 Gateway API 一致性主页以了解有关测试的更多信息。如果 Envoy Gateway 已安装， 请运行 TAG=latest make run-conformance 来运行一致性测试。

在 Linux 主机上

• 运行 TAG=latest make conformance 来创建 Kind 集群， 使用最新的 gateway-dev 镜像安装 Envoy Gateway，并运行 Gateway API 一致性测试。

在 Mac 主机上

由于 Mac 不支持将 Docker 网络直接暴露到 Mac 主机，因此请使用以下解决方法之一来运行一致性测试：

• 部署您自己的 Kubernetes 集群或使用具有 Kubernetes 支持 的 Docker Desktop， 然后运行 TAG=latest make kube-deploy run-conformance。这将使用最新的 gateway-dev 镜像将 Envoy Gateway 安装到使用当前 kubectl 上下文的 Kubernetes 集群，并运行一致性测试。使用 make kube-undeploy 卸载 Envoy Gateway。
• 安装并运行 Docker Mac Net Connect，然后运行 TAG=latest make conformance。

**注意：**在命令前加上 IMAGE 或替换 TAG 以使用不同的 Envoy Gateway 镜像或标签。如果未指定 TAG，则使用当前分支的短 SHA。

调试 Envoy 配置

查看 Envoy Gateway 正在使用的 Envoy 配置的一种简单方法是将端口转发到与 Gateway 对应的 Envoy 部署上的管理界面端口（当前为 19000），以便可以在本地访问它。

获取 Envoy 部署的名称。以下示例适用于 default 命名空间中的网关 eg：

export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')

通过端口转发管理接口端口：

kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000

现在，您可以通过导航到 127.0.0.1:19000/config_dump 来查看正在运行的 Envoy 配置。

Envoy 管理接口上还有许多其他端点在调试时可能会有所帮助。

JWT 测试

JSON Web Token（JWT）和 JSON Web Key Set（JWKS）示例用于请求身份验证任务。 JWT 由 JWT Debugger 使用 RS256 算法创建。JWT 验证签名中的公钥已复制到 JWK Creator 以生成 JWK。 JWK Creator 配置了匹配的设置，即 Signing 公钥使用和 RS256 算法。生成的 JWK 包装在 JWKS 结构中并托管在仓库中。

4 - 贡献

我们欢迎来自社区的贡献。请仔细查看项目目标和以下指南，以简化您的贡献流程。

沟通

• 在开始开发主要功能之前，请通过 GitHub 或 Slack 联系我们。 我们将确保没有其他人正在处理此问题，并要求您创建 GitHub Issue。
• “主要功能”定义为超过 100 个 LOC 的任意更改（不包括测试）， 或更改任何面向用户的行为。我们将使用 GitHub Issue 来讨论该功能并达成一致。 这是为了防止浪费您和我们的时间。主要功能的 GitHub 审核流程也很重要， 以便与提交权限的干系者可以就设计达成一致。 如果适合编写设计文档，则该文档必须托管在 GitHub Issue 中，或者托管在公开可读的位置并链接到 Issue 中。
• 小补丁和错误修复不需要事先沟通。

包容性

Envoy Gateway 社区的一个明确的目标是完全包容性。 因此，所有 PR 的所有代码、API 和文档都必须遵守以下准则：

• 不允许使用以下单词和短语：
  • Whitelist：使用 allowlist 代替。
  • Blacklist：使用 denylist 或 blocklist 代替。
  • Master：使用 primary 代替。
  • Slave：使用 secondary 或 replica 代替。
• 文档应该以包容的风格编写。 Google 开发人员文档包含有关此主题的出色参考。
• 上述政策并非最终政策，未来可能会随着行业最佳实践的发展而进行修改。 维护人员在代码审查期间可能会提供有关此主题的其他评论。

提交一个 PR

• Fork 该仓库。
• 修改。
• 对每次提交都进行 DCO 签署。这可以通过 git commit -s 来完成。
• 提交您的 PR。
• 将为您自动运行测试。
• 我们不会合并任何未通过测试的 PR。
• PR 预计对添加的代码具有 100% 的测试覆盖率。这可以通过覆盖范围构建来验证。 如果您的 PR 由于某种原因无法被 100% 覆盖，请在创建时明确解释原因。
• 任何更改面向用户行为的 PR 必须在仓库中的 docs 文件夹中具有关联的文档以及变更日志。
• 所有代码注释和文档均应具有正确的英语语法和标点符号。 如果您的英语不流利（或者是一个糟糕的写作者 ;-)），请告诉我们，我们会尽力为您寻求帮助，但不能保证。
• 您的 PR 标题应该是描述性的，通常以包含子系统名称的类型开头， 如有必要，带有 ()，摘要后跟冒号。格式例子如下：
  • “docs: fix grammar error”
  • “feat(translator): add new feature”
  • “fix: fix xx bug”
  • “chore: change ci & build tools etc”
• 当您的 PR 被合并时，您的 PR 提交消息将用作其提交消息。 如果您的 PR 在审核期间出现分歧，您应该更新此字段。
• 您的 PR 描述应详细说明 PR 的用途。如果它修复了现有问题，则应以“Fixes #XXX”结尾。
• 如果您的 PR 是共同创作的或基于其他贡献者的早期 PR， 请注明 Co-authored-by: name <name@example.com>。 有关更多详细信息，请参阅 GitHub 的多作者指南。
• 当所有测试都通过并且满足本文所述的所有其他条件时，将指派维护人员审查并合并 PR。
• 一旦您提交了 PR，请不要对其进行 Rebase。 如果后续提交是新提交和/或合并，则检查起来要容易得多。我们会压缩并合并，因此 PR 中的提交数量并不重要。
• 我们预计，一旦 PR 被开启，它将被积极处理，直到它被合并或关闭。 我们保留关闭没有取得进展的 PR 的权利。这通常定义为 7 天内没有变化。 显然，由于缺乏活跃度而被关闭的 PR 可以稍后重新开启。 关闭过时的 PR 有助于我们掌控当前正在进行的所有工作。

维护者 PR 审查策略

• 请参阅 CODEOWNERS.md 了解当前的维护者列表。
• 需要由代表与 PR 所有者不同的隶属关系的维护者来审查和批准 PR。
• 当项目成熟时，预计 PR 涉及代码的“领域专家”应该对 PR 进行审查。 此人不需要提交权限，只需要领域知识。
• 对于仅更新文档或评论， 或对测试和工具进行细微更改（其中细微更改由相关维护者决定）的 PR，可以免除上述规则。
• 如果有关于谁应该审查 PR 的问题，请在 Slack 中讨论。
• 欢迎任何人审查他们想要审查的任何 PR，无论他们是否是维护者。
• 如果 PR 在审核期间发生重大变化，请确保更新 PR 标题、提交消息和描述。
• 合并前请清理标题和正文。默认情况下，GitHub 使用原始标题填充压缩合并标题， 并使用 PR 中的每个单独提交填充提交正文。进行合并的维护者应确保标题遵循上述准则， 并应使用 PR 的原始提交消息覆盖正文（如有必要，请将其清理），同时保留 PR 作者的最终 DCO 签名。

决策

这是一个新的、复杂的项目，我们需要很快做出很多决定。 为此，我们确定了做出（可能有争议的）决定的流程：

• 对于需要记录的决策，我们会创建一个 Issue。
• 在该 Issue 中，我们讨论想法，然后维护者可以在评论中要求投票。
• 维护者可以通过在另外的评论中做出反馈或回复来对该评论进行具有约束力的投票。
• 欢迎非维护者社区成员通过这两种方法进行不具约束力的投票。
• 投票将通过简单多数达成决定。
• 如果出现僵局，这个问题将被转移到 Steering 处理。

DCO：签署您的工作

签署是补丁说明末尾的一行简单内容，它证明您编写了该补丁或有权将其作为开源补丁传递。 规则非常简单：如果您可以证明以下内容（来自 developercertificate.org）：

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

然后您只需在每个 git 提交消息中使用您的真实姓名（抱歉，不支持化名或匿名贡献）添加一行：

Signed-off-by: Joe Smith <joe@gmail.com>

您可以在通过 git commit -s 创建 git 提交时添加签署。

如果您希望这是自动的，您可以设置一些别名：

git config --add alias.amend "commit -s --amend"
git config --add alias.c "commit -s"

修复 DCO

如果您的 PR 未通过 DCO 检查，则有必要修复 PR 中的整个提交历史记录。 最佳实践是 squash 将提交历史记录合并到单个提交中，如上所述附加 DCO 签名， 然后强制推送。 例如，如果您的历史记录中有 2 次提交：

git rebase -i HEAD^^
(interactive squash + DCO append)
git push origin -f

请注意，一般来说，以这种方式重写历史记录会阻碍审核过程，并且只能在纠正 DCO 错误时才这样做。

5 - 参与 Envoy Gateway 文档工作

Envoy Gateway 的文档位于 site/content/en 目录中（中文内容位于 site/content/zh 目录中）。 任何单独的文档都可以使用 Markdown 编写。

文档结构

我们现在支持版本化的文档，文档下的目录名代表了文档的版本。 最新站点的根目录位于 site/content/en/latest 中。 如果您想了解这些内容如何组合在一起，可以由此处开始。

请注意，新内容应被添加到 site/content/en/latest 中， 并将在下一个版本中被截断。site/content/en/v0.5.0 下的内容是自动生成的， 通常不需要对其进行更改，除非您发现当前发布页面有一些不正确的内容。 如果是这样，您应该提交 PR 来一并更新 site/content/en/latest 和 site/content/en/v0.5.0 的内容。

您可以默认访问代表当前版本的网站内容， 也可以在此处或页面的页脚处访问包含最新版本变更的网站。

文档工作流程

要参与文档工作，只需编辑 site/content/en/latest 中的 Markdown 文件，然后运行：

make docs

这将使用被构建的 HTML 页面创建 site/public。您可以通过运行以下命令来预览它：

make docs-serve

如果您想生成文档的新发布版本，例如 v0.6.0，请运行：

make docs-release TAG=v0.6.0

该操作将更新项目根目录下的 VERSION 文件，该文件记录当前发布的版本， 并将在页面版本上下文和二进制版本输出中被使用。此外，这将生成新的目录 site/content/en/v0.6.0， 其中包含 v0.6.0 的文档，如 /api、/install 等。

发布文档

每当文档被推送到 main 分支时，CI 都会将构建的文档发布到 GitHub Pages。 有关更多详细信息，请参阅 .github/workflows/docs.yaml。

参考

前往 Hugo 和 Docsy 了解更多信息。

如果您希望参与中文内容翻译或贡献，请先阅读规范以帮助您更好的参与内容贡献。

6 - 发布流程

本文档指导维护人员完成创建 Envoy Gateway 版本的过程。

• 候选版本
  • 先决条件
  • 设置 Cherry Picker Action
• 次要版本
  • 先决条件
• 公告发布

候选版本

应使用以下步骤创建候选版本。

先决条件

• 具备推送到 Envoy Gateway 仓库的权限。

设置环境变量以供后续步骤使用：

export MAJOR_VERSION=0
export MINOR_VERSION=3
export RELEASE_CANDIDATE_NUMBER=1
export GITHUB_REMOTE=origin

1. 克隆仓库，迁出 main 分支，确保它是最新的，并且您的本地分支是干净的。

2. 创建一个主题分支，用于添加发布说明并使用发布版本更新 VERSION 文件。 请参阅之前的发布说明和 VERSION 了解更多详细信息。

3. 签名、提交更改并将其推送到您 Fork 的分支。

4. 提交 Pull Request 将更改合并到 main 分支中。 在您的 PR 合并并且构建和测试成功完成之前，请勿继续。

5. 从 main 创建一个新的发布分支。发布分支应命名为 release/v${MAJOR_VERSION}.${MINOR_VERSION}，例如 release/v0.3。

   git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION}
   

6. 将分支推送到 Envoy Gateway 仓库。

   git push ${GITHUB_REMOTE} release/v${MAJOR_VERSION}.${MINOR_VERSION}
   

7. 创建主题分支，用于将 Envoy Proxy 镜像和 Envoy Ratelimit 镜像更新为版本支持的 Tag。 有关更新镜像 Tag 的更多详细信息，请参阅 PR #2098。

8. 签名、提交更改并将其推送到您 Fork 的分支。

9. 提交 Pull Request 将更改合并到 release/v${MAJOR_VERSION}.${MINOR_VERSION} 分支中。 在您的 PR 已合并到发布分支并且 PR 的构建和测试已完成之前，请勿继续。

10. 确保您的发布分支是最新的，并使用候选版本编号为发布分支的头部打 Tag。

    git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER} Release Candidate'
    

11. 将 Tag 推送到 Envoy Gateway 仓库。

    git push ${GITHUB_REMOTE} v${MAJOR_VERSION}.${MINOR_VERSION}.0-rc.${RELEASE_CANDIDATE_NUMBER}
    

12. 这将触发发布 GitHub Action 并生成发布版本、发布制品等内容。

13. 确认发布工作流程已成功完成。

14. 确认具有正确发布标签的 Envoy Gateway 镜像已发布到 Docker Hub。

15. 确认版本已被创建。

16. 请注意，快速入门参考资料并未针对候选版本进行更新。 但是，请通过手动更新链接来使用候选版本测试快速入门步骤。

17. 生成 GitHub 变更日志。

18. 确保在编辑 GitHub 版本时选中 “这是一个 pre-release” 复选框。

19. 如果您在此过程中发现任何错误，请创建 Issue。

设置 Cherry Picker Action

在发布分支切分后，RM（发布经理）应添加 Cherrypick Action Job 以进行目标发布。

配置如下所示：

  cherry_pick_release_v0_4:
    runs-on: ubuntu-latest
    name: Cherry pick into release-v0.4
    if: ${{ contains(github.event.pull_request.labels.*.name, 'cherrypick/release-v0.4') && github.event.pull_request.merged == true }}
    steps:
      - name: Checkout
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
        with:
          fetch-depth: 0
      - name: Cherry pick into release/v0.4
        uses: carloscastrojumo/github-cherry-pick-action@a145da1b8142e752d3cbc11aaaa46a535690f0c5  # v1.0.9
        with:
          branch: release/v0.4
          title: "[release/v0.4] {old_title}"
          body: "Cherry picking #{old_pull_request_id} onto release/v0.4"
          labels: |
            cherrypick/release-v0.4            
          # 将发布经理名字放在这里
          reviewers: |
            Alice-Lilith            

将 v0.4 替换为真实的分支名称，并将 Alice-Lilith 替换为 RM 的真实名称。

次要版本

应使用以下步骤创建次要版本。

先决条件

• 具备推送到 Envoy Gateway 仓库的权限。
• 版本分支是从相应候选版本中切分的。 有关切分候选版本的更多详细信息，请参阅候选版本部分。

设置环境变量以供后续步骤使用：

export MAJOR_VERSION=0
export MINOR_VERSION=3
export GITHUB_REMOTE=origin

1. 克隆仓库，迁出 main 分支，确保它是最新的，并且您的本地分支是干净的。

2. 创建主题分支以添加发布说明、发布公告和具体版本的发布文档。

   1. 创建发布说明。请参阅之前的发布说明以了解更多详细信息。 **注意：**发布说明应该是候选版本发布说明以及自发布候选版以来的任何更改的累积。
   2. 创建发布公告。请参阅 PR #635 作为发布公告示例。
   3. 将版本包含在兼容性矩阵中。请参阅 PR #1002 作为示例。
   4. 生成具体版本的发布文档：

      make docs-release TAG=v${MAJOR_VERSION}.${MINOR_VERSION}.0
   

   5. 更新 site/content/en/_index.md 中的 Get Started 和 Contributing 按钮引用链接：

      <a class="btn btn-lg btn-primary me-3 mb-4" href="/v0.5.0">
      Get Started <i class="fas fa-arrow-alt-circle-right ms-2"></i>
      </a>
      <a class="btn btn-lg btn-secondary me-3 mb-4" href="/v0.5.0/contributions">
      Contributing <i class="fa fa-heartbeat ms-2 "></i>
      </a>
   

   6. 更新 site/hugo.toml 中菜单上的 Documentation 引用链接：

   [[menu.main]]
      name = "Documentation"
      weight = -101
      pre = "<i class='fas fa-book pr-2'></i>"
      url = "/v0.5.0"
   

3. 签名、提交更改并将其推送到您 Fork 的分支。

4. 提交 Pull Request 将更改合并到 main 分支中。 在您的所有 PR 合并并且最终 PR 的构建和测试完成之前，请勿继续。

5. 迁出发布分支。

   git checkout -b release/v${MAJOR_VERSION}.${MINOR_VERSION} $GITHUB_REMOTE/release/v${MAJOR_VERSION}.${MINOR_VERSION}
   

6. 如果发布分支的提示与 main 的提示不匹配，则执行以下操作：

   1. 从发布分支创建主题分支。

   2. 从 main 中 Cherry-pick 与发布分支不同的提交。

   3. 在本地运行测试，例如 make lint。

   4. 签名、提交主题分支并将其推送到您 Fork 的 Envoy Gateway 分支。

   5. 提交 PR，将您的 Fork 分支中的主题合并到 Envoy Gateway 发布分支中。

   6. 在 PR 合并以及该合并的 PR 的 CI 通过之前，不要继续。

   7. 如果您仍在主题分支，请切换到发布分支：

      git checkout release/v${MAJOR_VERSION}.${MINOR_VERSION}
      

   8. 确保您的本地发布分支是最新的：

      git pull $GITHUB_REMOTE release/v${MAJOR_VERSION}.${MINOR_VERSION}
      

7. 使用发布信息为发布分支的头部打 Tag。例如：

   git tag -a v${MAJOR_VERSION}.${MINOR_VERSION}.0 -m 'Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION}.0 Release'
   

   **注意：**Tag 版本与发布分支的不同之处在于包含 .0 补丁版本。

8. 将标签推送到 Envoy Gateway 仓库。

   git push origin v${MAJOR_VERSION}.${MINOR_VERSION}.0
   

9. 这将触发发布 GitHub Action 并生成发布版本、发布制品等内容。

10. 确认发布工作流程已成功完成。

11. 确认具有正确发布标签的 Envoy Gateway 镜像已发布到 Docker Hub。

12. 确认版本已被创建。

13. 确认快速入门中的步骤按预期工作。

14. 生成 GitHub 变更日志并保持发布页面的开头包含以下文本：

# Release Announcement

Check out the [v${MAJOR_VERSION}.${MINOR_VERSION} release announcement]
(https://gateway.envoyproxy.io/releases/v${MAJOR_VERSION}.${MINOR_VERSION}.html) to learn more about the release.

如果您在此过程中发现任何错误，请创建 Issue。

公告发布

让所有人都知道这次发布非常重要。使用以下步骤来公告发布。

1. 在 Envoy Gateway Slack 频道中设置发布信息。例如：

   Envoy Gateway v${MAJOR_VERSION}.${MINOR_VERSION} has been released: https://github.com/envoyproxy/gateway/releases/tag/v${MAJOR_VERSION}.${MINOR_VERSION}.0
   

2. 向 Envoy Gateway Slack 频道发送消息。例如：

   On behalf of the entire Envoy Gateway community, I am pleased to announce the release of Envoy Gateway
   v${MAJOR_VERSION}.${MINOR_VERSION}. A big thank you to all the contributors that made this release possible.
   Refer to the official v${MAJOR_VERSION}.${MINOR_VERSION} announcement for release details and the project docs
   to start using Envoy Gateway.
   ...
   

   链接到 GitHub 版本和突出显示该版本的版本公告页面。

7 - 维护者

以下是拥有所有权限的维护者（按字母顺序排列）

• @arkodg
• @qicz
• @Xunzhuo
• @zirain
• @zhaohuabing

荣誉退休维护者

• @alexgervais
• @danehans
• @LukeShu
• @skriss
• @youngnick
• @Alice-Lilith

8 - 文档内容编写规范（中文）

中文内容的位置在 site/content/zh 目录中，具体内容和结构应与英文版本保持一致。

规范

以下定义了一些编写规范，并提供示例和对应 Markdown 写法。

中英文混排

当内容中存在中文和英文混排的时候中英文间需要加一个空格， 中文与中文之间无需空格（即使某个中文是链路的一部分也不需要空格）：

示例：

这里有中文和 English 混排。 可以跳转到规范处重新阅读。

这里有中文和 English 混排。
可以跳转到[规范](#standard)处重新阅读。

粗体

在中文内容中建议一律使用两个星号表示粗体：

示例：

其中非常重要的内容是

其中**非常重要**的内容是

标点符号

中文内容中遇到的标点符号都要用全角， 无论中英文内容与全角标点符号之间无需空格（即使某个中文是在加粗格式之中也不需要空格）

示例：

无法确认吗？确认无误（没有任何拼写错误）后，可以继续后面的步骤。 安装 Envoy Gateway（通过命令）结束后，查看相关 Service。

无法确认吗？确认无误（没有任何拼写错误）后，可以继续后面的步骤。
安装 Envoy Gateway（通过命令）**结束后**，查看相关 Service。

锚

标题要添加英文锚（anchor），用于在其他内容中保持引用定位的一致性：

示例：

示例

#### 示例 {#example}

无需翻译的情况

如果内容中的英文是命令，特定专有名词，如 CRD 名称，协议名称等，请保持大小写与原本定义一致：

示例：

使用 curl 命令发起 HTTP 请求。 在 kind 集群中添加 Gateway 资源，创建 Service 和 Deployment。

使用 curl 命令发起 HTTP 请求。
在 kind 集群中添加 Gateway 资源，创建 Service 和 Deployment。

英文复数处理

大部分情况遇到英文的复数形式请按需调整为单数：

示例：

英文：Delete all Services in Kubernetes.

中文：删除所有 Kubernetes 中的 Service。

英文：Delete all Services in Kubernetes.
中文：删除所有 Kubernetes 中的 Service。

换行断句

如果一句话很长，尽量按照本身的句子进行断句换行，通常一行内容保持在 40-60 字符，方便 Review：

示例：

这是一个长句子，在网页中查看，它是一整段话， 不会由于在 Markdown 编写时换行而另起一段，而在 Markdown 编写时， 只要换行间隔不多于一个换行，他们始终将保持一个段落。

而这句话则会另起一段！

这是一个长句子，在网页中查看，它是一整段话，
不会由于在 Markdown 编写时换行而另起一段，而在 Markdown 编写时，
只要换行间隔不多于一个换行，他们始终将保持一个段落。

而这句话则会另起一段！

使用“您”

第二人称代词统一使用“您”：

示例：

至此，您已经了解了中文文档内容编写规范！

至此，您已经了解了中文文档内容编写规范！

必要时意译

翻译时有些情况需要使用意译代替直译：

示例：

英文原文：He is as cool as a cucumber.

直译成中文：他像黄瓜一样冷静。

更好的翻译可能是：他泰然自若，从容不迫。

欢迎贡献

以上规范参考了一些开源社区中文内容贡献者日常贡献中的约定俗成的做法，如有不适合或需要改进的，欢迎提出您的建议！

9 - 行为准则

Envoy Gateway 遵循 CNCF 行为准则。