Velero 代码规范实践：PR Changelog、版权头、导入约定、Mock 生成与 DCO 签署

Velero 代码规范实践PR Changelog、版权头、导入约定、Mock 生成与 DCO 签署【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文基于 Velero 官方文档 Code Standards 系统整理 Velero 项目的贡献者代码规范涵盖提交 Pull Request 时的清单要求、changelog 文件的命名规则与 CI 强制检查、源文件版权头约定、日志与错误消息的风格约定、Kubernetes 客户端导入命名约定、基于 mockery 的 mock 生成方式、label 值合法性处理以及 DCODeveloper Certificate of Origin签署机制。读完本文你可以按 Velero 仓库的实际 CI 行为而非仅凭文档描述完整地发起一个能通过 changelog 检查、代码风格与版权头校验的合规 PR。提交 Pull Request先填清单再说话Velero 要求在开 PR 时填写 PR 模板提供的 checklist目的是帮助维护者正确地对 PR 分类和评审。仓库中的 PR 模板见 .github/pull_request_template.md当前模板包含三项核心确认已接受 DCO未签署 DCO 的提交会延迟 PR 被接受已创建 changelog 文件可通过make new-changelog生成或在 PR 上评论/kind changelog-not-required已同步更新site/content/docs/main下对应的文档。- [ ] Accepted the DCO. Commits without the DCO will delay acceptance. - [ ] Created a changelog file (make new-changelog) or comment /kind changelog-not-required on this PR. - [ ] Updated the corresponding documentation in site/content/docs/main.从仓库配置看PR 的分类标签由 .github/labels.yaml 定义包含kind如changelog-not-required、refactor、tech-debt等与area如CLI、CSI、fs-backup、kopia-integration、schedule等两类维护者可据此决定评审路由与是否触发特定 CI 流程。Changelog 约定每个 PR 都该留痕文件位置与命名Velero 要求 PR 作者随 PR 附带一个 changelog 文件新建文件放在changelogs/unreleased目录下文件命名约定为pr-username即PR编号-GitHub用户名文件内容就是本 PR 要写进 changelog 的文案并把这个新文件加入 PR 一起提交velero/changelogs/unreleased - 目录 000-username - 文件仓库中changelogs/unreleased/目录下的真实文件如9995-shubham-pampattiwar、10000-shubham-pampattiwar印证了这一约定文件内容通常是一行改动描述例如Fix PodVolumeBackup metadata loss on fs-backup timeout, which caused all fs-backup volumes to become unrestorable用make new-changelog自动生成Makefile 中提供了new-changelog目标约 L523-L532可自动完成建目录 按 PR 信息命名 写入文案三步。它依赖已登录的ghCLI从当前 PR 自动获取作者登录名、PR 编号并默认以 PR 标题作为 changelog 内容也可通过CHANGELOG_BODY变量覆盖# 需要先 gh auth login 并创建好 PR make new-changelog # 或自定义文案 make new-changelog CHANGELOG_BODYChanges you have made其执行逻辑是读取gh pr view --json author/number/title然后mkdir -p ./changelogs/unreleased/并写入$(GH_PR_NUMBER)-$(GH_LOGIN)文件。如果分支没有关联 PR 或未登录会直接报错退出。CI 强制检查与豁免标签如果某个 PR 确实不需要 changelog可以在 PR 上打changelog-not-required标签来跳过 CI 的 changelog 检查但如果 PR 是面向 release 分支的仍需在 release 分支的changelogs/unreleased目录中新建文件。需要注意的是从源码看当前 CI 的豁免规则比文档描述更具体。检查工作流 .github/workflows/pr-changelog-check.yml 在opened / synchronize / reopened / labeled / unlabeled五类 PR 事件上触发执行 hack/changelog-check.sh。该脚本的逻辑是仅在 GitHub Actions 环境运行本地直接执行会以This script is intended to be run only on Github Actions退出从GITHUB_REF形如refs/pull/:prNumber/merge中解析出 PR 编号通过gh api实时查询 PR 当前标签而不是冻结的事件 payload这样事后补打标签、重跑 CI 都能正确反映状态命中以下任一标签即豁免kind/changelog-not-required、Design、Website、Documentation检查changelogs/unreleased/pr_number-*是否存在存在则通过否则报错退出并提示参考 code-standards 文档补充 changelog。也就是说当前实际生效的豁免标签是kind/changelog-not-required与 PR 模板中/kind changelog-not-required评论命令对应而设计类Design、网站类Website、纯文档类Documentation改动天然免写 changelog。版权头规范只要修改了源代码文件就应把其中的版权声明更新为 Velero 的标准版权声明Copyright the Velero contributors.。对于新建文件必须添加完整的版权与许可证头部。文档文件则不需要版权头。标准头部可以直接对照 hack/boilerplate.go.txt其内容就是/* Copyright the Velero contributors. Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */仓库内任意 Go 文件如 pkg/label/label.go的开头都是这一标准块个别历史文件头部保留具体年份如 Copyright 2019 the Velero contributors属既有文件沿袭规范要求的标准写法是 Copyright the Velero contributors.。代码风格约定Velero 对日志、错误与集合工具使用有四条明确的风格约定日志消息首字母大写错误消息保持小写Log messages are capitalized日志消息首字母大写Error messages are kept lower-cased错误消息保持小写。两者刻意区分便于在日志流中快速区分操作日志与错误信息两类内容。只对外部错误包装调用栈规范明确errors.WithStack(err)只应加在直接由非 Velero 代码返回的错误上比如对 Kubernetes API server 的调用返回的错误。Velero 内部产生的错误不需要逐层包 stack避免调用栈膨胀且无信息增量。errors.WithStack(err)仓库中这一模式的真实用法可以见 pkg/restore/restore.go、pkg/restore/pv_restorer.go 等恢复流程代码——它们在对 API server 的调用失败处包装 stack便于排障时定位到外部调用的具体位置。优先使用 Kubernetes 的 sets 工具集合操作优先使用 apimachinery 提供的工具包import k8s.io/apimachinery/pkg/util/sets这保证了集合语义存在判断、并差集、字符串/整数集合与 Kubernetes 生态一致避免项目内自造轮子。导入约定groupversionapi | client | informer | ...Velero 对导入别名有一套固定命名约定groupversionapi | client | informer | ...即资源组 版本 客户端角色三段拼接。官方示例如下import ( corev1api k8s.io/api/core/v1 metav1 k8s.io/apimachinery/pkg/apis/meta/v1 corev1client k8s.io/client-go/kubernetes/typed/core/v1 corev1listers k8s.io/client-go/listers/core/v1 velerov1api github.com/velero-io/velero/pkg/apis/velero/v1 velerov1client github.com/velero-io/velero/pkg/generated/clientset/versioned/typed/velero/v1 )从源码结构看这套约定在整个仓库被一致执行例如 pkg/label/label.go 中即使用metav1 k8s.io/apimachinery/pkg/apis/meta/v1和velerov1api github.com/vmware-tanzu/velero/pkg/apis/velero/v1注意仓库当前模块路径已迁移到github.com/vmware-tanzu/velero文档示例中的velero-io前缀对应早期版本。遵循该约定可以让 reviewer 一眼识别出这个包是 API 类型、typed client 还是 lister/informer显著降低阅读成本。Mock 生成使用 mockeryVelero 用 mockery操作步骤为go get github.com/vektra/mockery/.../ cd pkg/podvolume mockery -nameRestorer如果需要改动某个 mock先进入对应包目录、指定接口名重新运行mockery之后可能还需要执行make update来更新导入。从生成的文件头部可以印证当前仓库使用的生成器版本例如 pkg/podvolume/mocks/restorer.go 第一行即为// Code generated by mockery v2.42.2. DO NOT EDIT.。仓库中pkg/client/mocks/、pkg/discovery/mocks/、pkg/persistence/mocks/等目录下均有同类的mockery生成物说明这是全仓库统一的 mock 策略mock 文件一律不手工编辑只通过mockery -name接口名重新生成。Kubernetes Label 值安全label.GetValidName()文档要求生成 label 值时必须经过label.GetValidName()辅助函数处理以确保值的长度和格式适合被存储与查询UID 一般可以安全地作为 label 值持久化该函数与 annotation 值无关annotation 没有长度/格式限制。其实现位于 pkg/label/label.go逻辑清晰// GetValidName converts an input string to valid Kubernetes label string in accordance to rfc1035 DNS Label spec // Length of the label is adjusted basis the DNS1035LabelMaxLength // If length exceeds, we trim the label name to contain only max allowed characters // Additionally, the last 6 characters of the label name are replaced by the first 6 characters of the sha256 of original label func GetValidName(label string) string { if len(label) validation.DNS1035LabelMaxLength { return label } sha : sha256.Sum256([]byte(label)) strSha : hex.EncodeToString(sha[:]) charsFromLabel : validation.DNS1035LabelMaxLength - 6 // ... return label[:charsFromLabel] strSha[:6] }也就是说长度不超过 Kubernetes 的DNS1035LabelMaxLength63 字符时原样返回超长时截断到 63 字符上限并把尾部 6 个字符替换为原字符串 SHA256 的前 6 个 hex 字符——既满足长度限制又通过哈希后缀保证不同超长输入截断后仍尽量可区分。同文件中还提供了一组基于它的便捷构造器NewSelectorForBackup/NewListOptionsForBackup/NewSelectorForRestorepkg/label/label.go它们把 backup/restore 名称先过GetValidName再拼进 label selector——这正是 Velero 在 PVC、Pod 等对象上以velero.io/backup-name等标签做关联查询的底层保障无论用户给备份起多长的名字label 值都保证合法。相关测试见 pkg/label/label_test.go。DCO 签署Signed-off-byVelero 遵循 DCO 机制所有作者保留其作品的版权但为确保提交的都是自己有权提交的工作要求每位贡献者对提交进行签署认证。仓库内所有版权声明的作者一律写为 the Velero contributors。签署方式是在 commit message 末尾添加一行Signed-off-by: Joe Beda joeheptio.com实际使用时直接给git commit加--signoff或-s选项即可自动附加该行。签署即表示你可以认证以下内容Developer Certificate of Origin v1.1Developers 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.从源码结构看DCO 不仅是提交侧的约定也是 CI 侧的硬约束.github/workflows/backport.yml 在自动 backport 流程中专门包含 Rename changelog file(s) and ensure DCO signoff 步骤——cherry-pick 后的 changelog 文件会被重命名为 backport PR 编号前缀以保证 changelog 检查通过同时流程会检查并补签 DCO印证了无 DCO 的提交会延迟接受这一规范在整个工程自动化中是一以贯之的。小结合规 PR 的最小动作清单结合本文各节与仓库中的 CI 实现一个 Velero 合规 PR 的最小动作集为使用git commit -s签署每个提交修改源文件时更新版权头为 Copyright the Velero contributors.新建文件补全 hack/boilerplate.go.txt 的完整头部用make new-changelog或手工创建changelogs/unreleased/PR编号-用户名文件附 changelog纯文档/设计/网站改动可评论/kind changelog-not-required或由Documentation/Design/Website标签豁免新 mock 一律mockery -name接口生成不手改生成文件必要时make update修导入导入别名遵循groupversionapi|client|informer|...日志大写、错误小写、errors.WithStack仅用于外部调用错误label 值一律过label.GetValidName()按 .github/pull_request_template.md 勾选 checklist 并提交 PR。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考