尧图网页设计 
Higress 开源贡献指南从 Fork 到合入主分支的完整实操流程与质量门槛【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressHigress 是一个云原生 AI 网关AI Native API Gateway以 Go 实现控制面、以 WasmGo/C/Rust承载插件生态。本文基于仓库根目录的 CONTRIBUTING_EN.md 完整梳理其官方贡献流程涵盖安全与一般问题上报、Fork/Clone/上游同步、分支模型、提交规范、PR 模板填写以及极具项目特色的 AI/编程代理辅助贡献强制门禁与 Bug 修复运行时验证要求。读完本文你将掌握一套可直接落地执行的 Higress 贡献 SOP并能用仓库内的源码与测试文件作为自查清单。贡献总览任何形式的帮助都是贡献Higress 将贡献视为项目持续演进的生命线贡献方式不限于提交代码。官方文档明确鼓励修复错别字、修复 Bug、删除冗余代码、补充缺失测试、增强特性、为晦涩代码加注释、重构丑陋代码、改进文档……一言以蔽之WE ARE LOOKING FORWARD TO ANY PR FROM YOU.期待你的任何 PR。此外即使不写代码也可以在 GitHub 上以其他方式参与回复他人提出的 issue帮助解决其他用户的部署与使用问题参与其他 PR 的设计评审与代码评审参与技术讨论、撰写 Higress 相关博客、在 GitHub 之外推广 Higress 技术。报告安全问题走私有通道绝不公开讨论安全问题在 Higress 中被最高优先级对待。原则是不鼓励任何人公开扩散安全漏洞信息——如果你发现 Higress 的安全问题不要公开讨论也不要开公开 issue而应严格遵循 SECURITY.md 中描述的私有上报流程。结合 SECURITY.md 的补充细节该流程的关键事实包括支持版本2.x.x 与 1.x.x 均在支持范围内 1.0.0不再支持上报入口首选且充分的渠道是 GitHub Private Security Advisory通过higress-group/higress的 security/advisories 页面新建当问题影响阿里云服务时可额外向阿里云安全响应中心ASRC提交但 ASRC 提交通报为可选上报信息建议包括问题类型如缓冲区溢出、注入、提权、相关源文件完整路径、可复现的逐步操作、PoC/利用代码如可行、影响范围、建议修复方案响应流程3 个工作日内确认收悉14 天内完成分类与严重性评估随后进入修复开发与协调披露阶段最终通过 GitHub Security Advisories 披露并致谢发现者角色分工SRT安全响应团队由当前项目维护者组成每个报告会分配分类协调人、修复负责人、评审与发布负责人、披露负责人且任何确认的漏洞至少需要两名无利益冲突的 SRT 成员参与确保修复经过独立评审。报告一般问题写出高质量、可复用的 issueHigress 以分布式方式协作因此官方文档格外强调 issue 报告要WELL-WRITTEN、DETAILED、EXPLICIT写得清楚、详细、明确。提交 issue 前的三条硬性建议先搜索确认你的问题是否已存在。若已存在请在既有 issue 下补充评论而不是新开一个以提高沟通效率使用模板仓库提供了 .github/ISSUE_TEMPLATE包含 FEATURE_REQUEST.md 等功能请求模板请务必按模板填写各字段清理敏感数据发布前移除密码、密钥、网络位置、私有业务数据等敏感信息。可开 issue 的场景包括Bug 报告、功能请求、性能问题、功能提案、功能设计、需要帮助、文档不完整、测试改进以及任何关于项目的问题。代码与文档贡献完整 PR 流程实操工作区准备Workspace Preparation贡献前提是注册 GitHub 账号然后依次完成三步第 1 步Fork 仓库。在 Higress 主仓库主页点击 Fork 按钮得到你自己的仓库https://github.com/your-username/higressyour-username为你的 GitHub 用户名。第 2 步Clone 本地仓库。使用 SSH 方式克隆git clone gitgithub.com:your-username/higress.git之后即可创建新分支进行开发。第 3 步设置 upstream 远端。官方给出的两条命令非常关键git remote add upstream gitgithub.com:alibaba/higress.git git remote set-url --push upstream no-pushing第二条命令把 upstream 的 push 地址设置为no-pushing从机制上杜绝误向官方仓库推送。配置完成后可用git remote -v验证$ git remote -v origin gitgithub.com:your-username/higress.git (fetch) origin gitgithub.com:your-username/higress.git (push) upstream gitgithub.com:alibaba/higress.git (fetch) upstream no-pushing (push)这样即可随时用 upstream 同步官方主干分支的最新代码。分支定义Branch Definition当前所有 PR 默认面向main分支。除此之外 Higress 还存在三类辅助分支Release 分支发布分支正式发布版本时以版本号命名创建如 0.6.0、0.6.1发布后将发布分支的提交合并回 main 分支Hotfix 分支热修复分支某版本发现 Bug 且决定单独修复时基于对应 release 分支 checkout 出来完成修复与验证后合并回 main 分支Feature 分支特性分支较大特性单独拉出分支进行开发与验证。提交规则Commit Rules提交时两条规则必须认真对待提交消息Commit Message与提交内容Commit Content。提交消息清晰的提交消息能让评审者快速理解 PR 目的、加速代码评审。官方推荐以下类型前缀类型示例docs:docs: add docs about Higress cluster installationfeature:feature: use higress config instead of istio configbugfix:bugfix: fix panic when input nil parameterrefactor:refactor: simplify to make codes more readabletest:test: add unit test case for func InsertIntoArray同时明确不鼓励这类模糊消息fix bug、update、add doc。对提交消息格式不熟悉的读者可参考《How to Write a Git Commit Message》一文入门。提交内容一次提交应自洽可审——评审者仅凭这一个提交即可完成完整审查无需依赖其他提交且提交内容必须能通过 CI。三条小规则避免单次提交改动过大每次提交完整且可评审提交前检查 git 配置的user.name与user.email是否关联到你的 GitHub IDgit config --get user.name git config --get user.email提交 PR 时请在changes/目录下对应版本X.X.X.md文件中为当前改动添加简要说明。代码变更部分还应先阅读本文末尾的代码风格一节。PR 描述以模板为纲PR 是修改 Higress 项目文件的唯一途径。官方要求遵循 .github/PULL_REQUEST_TEMPLATE.md 完成 PR。仓库中的模板实际包含七个部分Summary改了什么、为什么、兼容性/迁移影响、Related issue用 Fixes #123 关联、Change typeBug fix / Feature or enhancement / Documentation or configuration only / Refactoring, tests, or maintenance、Agent participation and issue-spec gate、Testing and verification、Special notes for reviewers、AI coding disclosure。模板还明确要求每个不适用的分类也要写N/A并说明原因空白字段不算解释。开发前准备在正式开发前运行官方提供的初始化命令用于拉取子模块并整理依赖make prebuild go mod tidy从源码看make prebuild对应 Makefile.core.mk 中的submodule目标实际执行git submodule update --init即初始化并拉取 Higress 依赖的 vendored 子模块如 istio、envoy 相关依赖参见仓库根目录的 istio/、envoy/ 目录随后go mod tidy负责整理 Go 模块依赖。AI/编程代理实质性参与贡献的强制门禁这是 Higress 贡献流程中极具特色的部分。如果 AI 或编程代理实质性参与了分析、设计、实现、测试或 PR 准备该贡献在开始实现之前必须进入 Higress issue-spec 工作流且 Proposal Issue 与 Design Issue 必须先获得维护者批准。实现必须遵循已批准的 Design 及其授权的实现 TASKDesign 必须在验证开始前包含具体的 Verification Plan验证 TASK 完成后需附带证据才能请求维护者接受或评审。实质性参与的定义包括进行实质性分析或设计、选择实现或验证方案、生成或实质性改写代码/测试/文档/配置、解释测试结果、准备实质性 PR 内容。由作者独立指导并验证的机械式自动补全不一定构成实质性参与。唯一例外是代理仅用于拼写、标点、空白或格式修正且无实质性行为影响——作者必须在 PR 中声明并说明该例外。纯人工 PR 不受此规则影响。绕过该门禁只有一条已验证维护者/管理员例外通道必须先通过已认证的ghCLI 验证当前登录身份及其在规范仓库higress-group/higress中的role_name为maintain或admin。完整的验证命令序列在 docs/developers/agent-assisted-contributions.md 中给出核心要点包括用env -u GH_TOKEN -u GITHUB_TOKEN确保校验命令不使用 token 覆盖、通过gh api查询role_name、用gh pr view核对 PR 作者与登录身份一致且 PR 中必须记录 PR 编号/URL、登录名、role_name、PR 作者绝不记录 token、token 覆盖声明与绕过理由。任何校验失败、缺失或不匹配都会使该例外失效接受例外或合并 PR 的维护者还会在取消 token 覆盖的情况下独立核验实时证据。该例外不豁免 AI 披露、评审、合并要求也不豁免 Bug 修复的运行时验证。所有使用 AI 或编程代理的 PR 还必须披露提示词/指令并提供包含关键决策、主要更改及重要限制的 AI 辅助工作总结。未满足门禁的实质性代理辅助 PR 会被安排为较低审查优先级且不保证维护者及时审查。这一规则在仓库的 issue-spec/config.yaml 中同样有机器可读的materially_agent_assisted_gate规则声明并与 docs/developers/agent-assisted-contributions.md 相互印证。PR 模板的 Agent participation and issue-spec gate 一节要求作者从纯人工 / 平凡代理例外 / 已验证维护者例外 / 实质性代理参与四种声明中恰好选择一种并勾选开始实现前 / 开始验证前 / 请求评审前三项时间义务最后给出整体门禁状态Complete / Noncompliant / Verified exception / N/A。测试用例贡献新功能与 Bug 修复的硬性门槛任何测试用例都受欢迎其中 Higress 功能测试用例优先级最高。仓库为此设定了量化门槛场景要求新 Wasm 插件必须包含单元测试代码覆盖率不低于30%CI 强制检查新核心功能应包含单元测试适用时补充 E2E 一致性测试用例Bug 修复必须包含回归测试并使用相同固定输入和配置提供修复前基线复现证据与修复后确认结果Patch 覆盖率新增或修改代码须达到50%覆盖率Codecov 通过codecov.yml强制检查关于 Patch 覆盖率仓库根目录的 codecov.yml 给出了佐证coverage.status.patch.default.target为50%、threshold为0%、CI 失败时视为 errorproject 级别目标为auto且阈值 1%helm/**目录被忽略不参与统计。当修复声明涉及运行时行为时单元测试不能替代运行时证据——具体要求见 docs/developers/agent-assisted-contributions.md 的 runtime-verification 章节。如何编写测试单元测试在同一模块的 test 目录中创建名为xxxTest.go的测试文件例如filter_test.go、config_test.go仓库的pkg/ingress/config/下就存在大量*_test.go文件集成测试将集成测试放入 test 目录Wasm 插件 E2E 测试在test/e2e/conformance/tests/下添加测试用例具体参见 test/README.md。E2E 测试体系速览源码佐证从 test/README.md 与仓库目录结构可确认Higress E2E 测试主要由两部分组成Ingress API 一致性测试与 Gateway API 一致性测试并通过以下 Make 目标运行API 测试make higress-conformance-testGateway API 测试make gateway-conformance-test运行上游 Gateway API v1.6.0 一致性套件默认覆盖 GATEWAY-HTTP、GATEWAY-TLS、GATEWAY-GRPC、GATEWAY-TCP 核心 profile直接导入上游套件与内嵌 manifests不维护官方用例副本WasmPlugin 测试make higress-wasmplugin-test并支持大量参数化组合例如# 构建全部 Go Wasm 插件进行测试 make higress-wasmplugin-test # 仅构建并测试指定 Go Wasm 插件 PLUGIN_NAMEip-restriction make higress-wasmplugin-test # 仅构建并测试指定 C Wasm 插件 PLUGIN_TYPECPP PLUGIN_NAMEkey_auth make higress-wasmplugin-test # 仅测试指定用例逗号分隔 TEST_SHORTNAMEWasmPluginsIPRestrictionAllow,WasmPluginsIPRestrictionDeny make higress-wasmplugin-test # 跳过 dev 镜像构建加速迭代 PLUGIN_NAMEip-restriction TEST_SHORTNAMEWasmPluginsIPRestrictionAllow make higress-wasmplugin-test-skip-docker-build测试流水线通常包含delete-cluster清理 kind 集群→ create-cluster创建 kind 集群→ docker-build构建 higress dev 镜像→ kube-load-image加载镜像到 kind→ install-dev安装 controller/gateway/istiod→ run-e2e-test加载并逐个执行用例。测试用例的登记入口在test/e2e/conformance/tests/tests.go导入github.com/alibaba/higress/v2/test/e2e/conformance/utils/suite实际用例即test/e2e/conformance/tests/目录下成对的*.go与*.yaml文件——*.yaml是要应用到集群的 Ingress/路由资源*.go定义测试结构。目录中可以看到go-wasm-ip-restriction.go、go-wasm-jwt-auth.go、cpp-wasm-basic-auth.go、rust-wasm-ai-data-masking.go、httproute-*系列等大量跨语言、跨场景用例新用例可参照 httproute-simple-same-namespace.go 与其同名 yaml 上手。Bug 修复的运行时验证Runtime Verification任何 Bug 修复都要求在相同固定输入与配置下做红/绿对比在受影响/修复前基线版本上复现 Bug在修复版本或镜像上确认预期行为。两种变体都需记录精确源码修订版本/镜像标签与 digest、manifests/Helm values/配置/请求与夹具、预期与实际结果、相关日志与指标、可确定复现的清理与重跑命令、机器可校验的断言、证据 URL 与产物哈希。控制面与数据面修复须在真实的kind或k3s集群中运行 Higress记录 Kubernetes 与 kind/k3s 版本、精确的 Higress 修订/镜像、安装 manifests 或 Helm values、触发请求、controller/gateway 日志与指标、断言及集群清理说明Wasm 插件修复必须通过真实的 proxy-Wasm 数据路径运行两种变体仅靠 Go helper/parser 测试与原生 mock不算充分运行时证据。需要记录基线/修复源码 SHA、每个 Wasm 模块的 SHA-256、精确的 Envoy 修订或固定的 Higress 网关发布镜像、插件配置与触发请求、客户端响应特征状态码、选中头、body 字节与 body SHA-256、Envoy access log 与插件日志、涉及时序/流式/缓存/并发/生命周期时的重复确定性结果以及证明测试端口、容器、进程均已清理的证据。仓库为此提供了可复用的本地验证 harnessdocs/developers/wasm-runtime-verification/README.md。它以 Docker Compose 拉起选定 Higress 网关发布镜像中的 Envoy加载一个仓库相对路径下的 Wasm 模块向隔离的 httpbin 服务发流量并把 access log 输出到容器 stdout。使用前需显式设置HIGRESS_GATEWAY_IMAGE、HTTPBIN_IMAGE、WASM_PATH须保持相对 Compose 目录且指向仓库内部、ENVOY_PORT、ENVOY_ADMIN_PORT等环境变量并用sha256sum/shasum记录镜像与模块哈希。注意该 harness 本身只是起点而非证据必须针对被测 Bug 参数化请求与插件配置后用同一输入跑基线与修复两个模块。常见问题排查提示上游同步设置 upstream 后开发前先git fetch upstream并将upstream/main合并进自己的特性分支避免提交冲突CI 失败自查新 Wasm 插件未达 30% 单元覆盖率、Patch 覆盖率低于 50%见 codecov.yml都会导致 CI 失败建议本地先跑对应*_test.go与make higress-wasmplugin-test相关目标AI 辅助 PR 被降权确认是否属于实质性代理参与以及是否完成了 issue-spec 门禁的三项时间义务实现前 Proposal/Design 批准、验证前 Verification Plan、评审前 TASK done 附证据并在 PR 模板中如实声明。代码风格官方文档中此节标注为//TBD待定尚未形成独立成文的规范文档但文档同时强调无论是提交消息还是提交内容代码评审都是最受重视的环节。总结一句官方原话ANY HELP IS CONTRIBUTION.任何帮助都是贡献。结语Higress 的贡献体系可以概括为一条主线与两条底线主线是Fork → Clone → 设 upstream → 按分支/提交/PR 规范提交流程的标准开源协作路径两条底线分别是安全问题的私有上报通道以及对 AI 辅助贡献的强制门禁与 Bug 修复运行时验证。对中文读者仓库还维护了一份内容对应的 CONTRIBUTING_CN.md安全策略、AI 辅助贡献政策、E2E 测试说明、Wasm 运行时验证 harness 等配套资料分别见 SECURITY.md、docs/developers/agent-assisted-contributions.md、test/README.md 与 docs/developers/wasm-runtime-verification/README.md。按本文流程走完一遍即可向 Higress 提交一份规范、完整、可评审的 PR。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Higress 开源贡献指南：从 Fork 到合入主分支的完整实操流程与质量门槛
Higress 开源贡献指南从 Fork 到合入主分支的完整实操流程与质量门槛【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressHigress 是一个云原生 AI 网关AI Native API Gateway以 Go 实现控制面、以 WasmGo/C/Rust承载插件生态。本文基于仓库根目录的 CONTRIBUTING_EN.md 完整梳理其官方贡献流程涵盖安全与一般问题上报、Fork/Clone/上游同步、分支模型、提交规范、PR 模板填写以及极具项目特色的 AI/编程代理辅助贡献强制门禁与 Bug 修复运行时验证要求。读完本文你将掌握一套可直接落地执行的 Higress 贡献 SOP并能用仓库内的源码与测试文件作为自查清单。贡献总览任何形式的帮助都是贡献Higress 将贡献视为项目持续演进的生命线贡献方式不限于提交代码。官方文档明确鼓励修复错别字、修复 Bug、删除冗余代码、补充缺失测试、增强特性、为晦涩代码加注释、重构丑陋代码、改进文档……一言以蔽之WE ARE LOOKING FORWARD TO ANY PR FROM YOU.期待你的任何 PR。此外即使不写代码也可以在 GitHub 上以其他方式参与回复他人提出的 issue帮助解决其他用户的部署与使用问题参与其他 PR 的设计评审与代码评审参与技术讨论、撰写 Higress 相关博客、在 GitHub 之外推广 Higress 技术。报告安全问题走私有通道绝不公开讨论安全问题在 Higress 中被最高优先级对待。原则是不鼓励任何人公开扩散安全漏洞信息——如果你发现 Higress 的安全问题不要公开讨论也不要开公开 issue而应严格遵循 SECURITY.md 中描述的私有上报流程。结合 SECURITY.md 的补充细节该流程的关键事实包括支持版本2.x.x 与 1.x.x 均在支持范围内 1.0.0不再支持上报入口首选且充分的渠道是 GitHub Private Security Advisory通过higress-group/higress的 security/advisories 页面新建当问题影响阿里云服务时可额外向阿里云安全响应中心ASRC提交但 ASRC 提交通报为可选上报信息建议包括问题类型如缓冲区溢出、注入、提权、相关源文件完整路径、可复现的逐步操作、PoC/利用代码如可行、影响范围、建议修复方案响应流程3 个工作日内确认收悉14 天内完成分类与严重性评估随后进入修复开发与协调披露阶段最终通过 GitHub Security Advisories 披露并致谢发现者角色分工SRT安全响应团队由当前项目维护者组成每个报告会分配分类协调人、修复负责人、评审与发布负责人、披露负责人且任何确认的漏洞至少需要两名无利益冲突的 SRT 成员参与确保修复经过独立评审。报告一般问题写出高质量、可复用的 issueHigress 以分布式方式协作因此官方文档格外强调 issue 报告要WELL-WRITTEN、DETAILED、EXPLICIT写得清楚、详细、明确。提交 issue 前的三条硬性建议先搜索确认你的问题是否已存在。若已存在请在既有 issue 下补充评论而不是新开一个以提高沟通效率使用模板仓库提供了 .github/ISSUE_TEMPLATE包含 FEATURE_REQUEST.md 等功能请求模板请务必按模板填写各字段清理敏感数据发布前移除密码、密钥、网络位置、私有业务数据等敏感信息。可开 issue 的场景包括Bug 报告、功能请求、性能问题、功能提案、功能设计、需要帮助、文档不完整、测试改进以及任何关于项目的问题。代码与文档贡献完整 PR 流程实操工作区准备Workspace Preparation贡献前提是注册 GitHub 账号然后依次完成三步第 1 步Fork 仓库。在 Higress 主仓库主页点击 Fork 按钮得到你自己的仓库https://github.com/your-username/higressyour-username为你的 GitHub 用户名。第 2 步Clone 本地仓库。使用 SSH 方式克隆git clone gitgithub.com:your-username/higress.git之后即可创建新分支进行开发。第 3 步设置 upstream 远端。官方给出的两条命令非常关键git remote add upstream gitgithub.com:alibaba/higress.git git remote set-url --push upstream no-pushing第二条命令把 upstream 的 push 地址设置为no-pushing从机制上杜绝误向官方仓库推送。配置完成后可用git remote -v验证$ git remote -v origin gitgithub.com:your-username/higress.git (fetch) origin gitgithub.com:your-username/higress.git (push) upstream gitgithub.com:alibaba/higress.git (fetch) upstream no-pushing (push)这样即可随时用 upstream 同步官方主干分支的最新代码。分支定义Branch Definition当前所有 PR 默认面向main分支。除此之外 Higress 还存在三类辅助分支Release 分支发布分支正式发布版本时以版本号命名创建如 0.6.0、0.6.1发布后将发布分支的提交合并回 main 分支Hotfix 分支热修复分支某版本发现 Bug 且决定单独修复时基于对应 release 分支 checkout 出来完成修复与验证后合并回 main 分支Feature 分支特性分支较大特性单独拉出分支进行开发与验证。提交规则Commit Rules提交时两条规则必须认真对待提交消息Commit Message与提交内容Commit Content。提交消息清晰的提交消息能让评审者快速理解 PR 目的、加速代码评审。官方推荐以下类型前缀类型示例docs:docs: add docs about Higress cluster installationfeature:feature: use higress config instead of istio configbugfix:bugfix: fix panic when input nil parameterrefactor:refactor: simplify to make codes more readabletest:test: add unit test case for func InsertIntoArray同时明确不鼓励这类模糊消息fix bug、update、add doc。对提交消息格式不熟悉的读者可参考《How to Write a Git Commit Message》一文入门。提交内容一次提交应自洽可审——评审者仅凭这一个提交即可完成完整审查无需依赖其他提交且提交内容必须能通过 CI。三条小规则避免单次提交改动过大每次提交完整且可评审提交前检查 git 配置的user.name与user.email是否关联到你的 GitHub IDgit config --get user.name git config --get user.email提交 PR 时请在changes/目录下对应版本X.X.X.md文件中为当前改动添加简要说明。代码变更部分还应先阅读本文末尾的代码风格一节。PR 描述以模板为纲PR 是修改 Higress 项目文件的唯一途径。官方要求遵循 .github/PULL_REQUEST_TEMPLATE.md 完成 PR。仓库中的模板实际包含七个部分Summary改了什么、为什么、兼容性/迁移影响、Related issue用 Fixes #123 关联、Change typeBug fix / Feature or enhancement / Documentation or configuration only / Refactoring, tests, or maintenance、Agent participation and issue-spec gate、Testing and verification、Special notes for reviewers、AI coding disclosure。模板还明确要求每个不适用的分类也要写N/A并说明原因空白字段不算解释。开发前准备在正式开发前运行官方提供的初始化命令用于拉取子模块并整理依赖make prebuild go mod tidy从源码看make prebuild对应 Makefile.core.mk 中的submodule目标实际执行git submodule update --init即初始化并拉取 Higress 依赖的 vendored 子模块如 istio、envoy 相关依赖参见仓库根目录的 istio/、envoy/ 目录随后go mod tidy负责整理 Go 模块依赖。AI/编程代理实质性参与贡献的强制门禁这是 Higress 贡献流程中极具特色的部分。如果 AI 或编程代理实质性参与了分析、设计、实现、测试或 PR 准备该贡献在开始实现之前必须进入 Higress issue-spec 工作流且 Proposal Issue 与 Design Issue 必须先获得维护者批准。实现必须遵循已批准的 Design 及其授权的实现 TASKDesign 必须在验证开始前包含具体的 Verification Plan验证 TASK 完成后需附带证据才能请求维护者接受或评审。实质性参与的定义包括进行实质性分析或设计、选择实现或验证方案、生成或实质性改写代码/测试/文档/配置、解释测试结果、准备实质性 PR 内容。由作者独立指导并验证的机械式自动补全不一定构成实质性参与。唯一例外是代理仅用于拼写、标点、空白或格式修正且无实质性行为影响——作者必须在 PR 中声明并说明该例外。纯人工 PR 不受此规则影响。绕过该门禁只有一条已验证维护者/管理员例外通道必须先通过已认证的ghCLI 验证当前登录身份及其在规范仓库higress-group/higress中的role_name为maintain或admin。完整的验证命令序列在 docs/developers/agent-assisted-contributions.md 中给出核心要点包括用env -u GH_TOKEN -u GITHUB_TOKEN确保校验命令不使用 token 覆盖、通过gh api查询role_name、用gh pr view核对 PR 作者与登录身份一致且 PR 中必须记录 PR 编号/URL、登录名、role_name、PR 作者绝不记录 token、token 覆盖声明与绕过理由。任何校验失败、缺失或不匹配都会使该例外失效接受例外或合并 PR 的维护者还会在取消 token 覆盖的情况下独立核验实时证据。该例外不豁免 AI 披露、评审、合并要求也不豁免 Bug 修复的运行时验证。所有使用 AI 或编程代理的 PR 还必须披露提示词/指令并提供包含关键决策、主要更改及重要限制的 AI 辅助工作总结。未满足门禁的实质性代理辅助 PR 会被安排为较低审查优先级且不保证维护者及时审查。这一规则在仓库的 issue-spec/config.yaml 中同样有机器可读的materially_agent_assisted_gate规则声明并与 docs/developers/agent-assisted-contributions.md 相互印证。PR 模板的 Agent participation and issue-spec gate 一节要求作者从纯人工 / 平凡代理例外 / 已验证维护者例外 / 实质性代理参与四种声明中恰好选择一种并勾选开始实现前 / 开始验证前 / 请求评审前三项时间义务最后给出整体门禁状态Complete / Noncompliant / Verified exception / N/A。测试用例贡献新功能与 Bug 修复的硬性门槛任何测试用例都受欢迎其中 Higress 功能测试用例优先级最高。仓库为此设定了量化门槛场景要求新 Wasm 插件必须包含单元测试代码覆盖率不低于30%CI 强制检查新核心功能应包含单元测试适用时补充 E2E 一致性测试用例Bug 修复必须包含回归测试并使用相同固定输入和配置提供修复前基线复现证据与修复后确认结果Patch 覆盖率新增或修改代码须达到50%覆盖率Codecov 通过codecov.yml强制检查关于 Patch 覆盖率仓库根目录的 codecov.yml 给出了佐证coverage.status.patch.default.target为50%、threshold为0%、CI 失败时视为 errorproject 级别目标为auto且阈值 1%helm/**目录被忽略不参与统计。当修复声明涉及运行时行为时单元测试不能替代运行时证据——具体要求见 docs/developers/agent-assisted-contributions.md 的 runtime-verification 章节。如何编写测试单元测试在同一模块的 test 目录中创建名为xxxTest.go的测试文件例如filter_test.go、config_test.go仓库的pkg/ingress/config/下就存在大量*_test.go文件集成测试将集成测试放入 test 目录Wasm 插件 E2E 测试在test/e2e/conformance/tests/下添加测试用例具体参见 test/README.md。E2E 测试体系速览源码佐证从 test/README.md 与仓库目录结构可确认Higress E2E 测试主要由两部分组成Ingress API 一致性测试与 Gateway API 一致性测试并通过以下 Make 目标运行API 测试make higress-conformance-testGateway API 测试make gateway-conformance-test运行上游 Gateway API v1.6.0 一致性套件默认覆盖 GATEWAY-HTTP、GATEWAY-TLS、GATEWAY-GRPC、GATEWAY-TCP 核心 profile直接导入上游套件与内嵌 manifests不维护官方用例副本WasmPlugin 测试make higress-wasmplugin-test并支持大量参数化组合例如# 构建全部 Go Wasm 插件进行测试 make higress-wasmplugin-test # 仅构建并测试指定 Go Wasm 插件 PLUGIN_NAMEip-restriction make higress-wasmplugin-test # 仅构建并测试指定 C Wasm 插件 PLUGIN_TYPECPP PLUGIN_NAMEkey_auth make higress-wasmplugin-test # 仅测试指定用例逗号分隔 TEST_SHORTNAMEWasmPluginsIPRestrictionAllow,WasmPluginsIPRestrictionDeny make higress-wasmplugin-test # 跳过 dev 镜像构建加速迭代 PLUGIN_NAMEip-restriction TEST_SHORTNAMEWasmPluginsIPRestrictionAllow make higress-wasmplugin-test-skip-docker-build测试流水线通常包含delete-cluster清理 kind 集群→ create-cluster创建 kind 集群→ docker-build构建 higress dev 镜像→ kube-load-image加载镜像到 kind→ install-dev安装 controller/gateway/istiod→ run-e2e-test加载并逐个执行用例。测试用例的登记入口在test/e2e/conformance/tests/tests.go导入github.com/alibaba/higress/v2/test/e2e/conformance/utils/suite实际用例即test/e2e/conformance/tests/目录下成对的*.go与*.yaml文件——*.yaml是要应用到集群的 Ingress/路由资源*.go定义测试结构。目录中可以看到go-wasm-ip-restriction.go、go-wasm-jwt-auth.go、cpp-wasm-basic-auth.go、rust-wasm-ai-data-masking.go、httproute-*系列等大量跨语言、跨场景用例新用例可参照 httproute-simple-same-namespace.go 与其同名 yaml 上手。Bug 修复的运行时验证Runtime Verification任何 Bug 修复都要求在相同固定输入与配置下做红/绿对比在受影响/修复前基线版本上复现 Bug在修复版本或镜像上确认预期行为。两种变体都需记录精确源码修订版本/镜像标签与 digest、manifests/Helm values/配置/请求与夹具、预期与实际结果、相关日志与指标、可确定复现的清理与重跑命令、机器可校验的断言、证据 URL 与产物哈希。控制面与数据面修复须在真实的kind或k3s集群中运行 Higress记录 Kubernetes 与 kind/k3s 版本、精确的 Higress 修订/镜像、安装 manifests 或 Helm values、触发请求、controller/gateway 日志与指标、断言及集群清理说明Wasm 插件修复必须通过真实的 proxy-Wasm 数据路径运行两种变体仅靠 Go helper/parser 测试与原生 mock不算充分运行时证据。需要记录基线/修复源码 SHA、每个 Wasm 模块的 SHA-256、精确的 Envoy 修订或固定的 Higress 网关发布镜像、插件配置与触发请求、客户端响应特征状态码、选中头、body 字节与 body SHA-256、Envoy access log 与插件日志、涉及时序/流式/缓存/并发/生命周期时的重复确定性结果以及证明测试端口、容器、进程均已清理的证据。仓库为此提供了可复用的本地验证 harnessdocs/developers/wasm-runtime-verification/README.md。它以 Docker Compose 拉起选定 Higress 网关发布镜像中的 Envoy加载一个仓库相对路径下的 Wasm 模块向隔离的 httpbin 服务发流量并把 access log 输出到容器 stdout。使用前需显式设置HIGRESS_GATEWAY_IMAGE、HTTPBIN_IMAGE、WASM_PATH须保持相对 Compose 目录且指向仓库内部、ENVOY_PORT、ENVOY_ADMIN_PORT等环境变量并用sha256sum/shasum记录镜像与模块哈希。注意该 harness 本身只是起点而非证据必须针对被测 Bug 参数化请求与插件配置后用同一输入跑基线与修复两个模块。常见问题排查提示上游同步设置 upstream 后开发前先git fetch upstream并将upstream/main合并进自己的特性分支避免提交冲突CI 失败自查新 Wasm 插件未达 30% 单元覆盖率、Patch 覆盖率低于 50%见 codecov.yml都会导致 CI 失败建议本地先跑对应*_test.go与make higress-wasmplugin-test相关目标AI 辅助 PR 被降权确认是否属于实质性代理参与以及是否完成了 issue-spec 门禁的三项时间义务实现前 Proposal/Design 批准、验证前 Verification Plan、评审前 TASK done 附证据并在 PR 模板中如实声明。代码风格官方文档中此节标注为//TBD待定尚未形成独立成文的规范文档但文档同时强调无论是提交消息还是提交内容代码评审都是最受重视的环节。总结一句官方原话ANY HELP IS CONTRIBUTION.任何帮助都是贡献。结语Higress 的贡献体系可以概括为一条主线与两条底线主线是Fork → Clone → 设 upstream → 按分支/提交/PR 规范提交流程的标准开源协作路径两条底线分别是安全问题的私有上报通道以及对 AI 辅助贡献的强制门禁与 Bug 修复运行时验证。对中文读者仓库还维护了一份内容对应的 CONTRIBUTING_CN.md安全策略、AI 辅助贡献政策、E2E 测试说明、Wasm 运行时验证 harness 等配套资料分别见 SECURITY.md、docs/developers/agent-assisted-contributions.md、test/README.md 与 docs/developers/wasm-runtime-verification/README.md。按本文流程走完一遍即可向 Higress 提交一份规范、完整、可评审的 PR。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考