ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

KnowStreaming 贡献指南:从 Issue 认领、Commit 规范到 PR 合并的完整协作流程

KnowStreaming 贡献指南:从 Issue 认领、Commit 规范到 PR 合并的完整协作流程 后端消息队列运维可观测性【免费下载链接】KnowStreaming一站式云原生实时流数据平台通过0侵入、插件化构建企业级Kafka服务极大降低操作、存储和管理实时流数据门槛项目地址https://gitcode.com/gh_mirrors/kn/KnowStreaming点击查看免费下载本文档以仓库内 docs/contribute_guide/贡献指南.md 为骨架结合 CONTRIBUTING.md、docs/contribute_guide/贡献名单.md 与仓库实际提交记录整理而成。KnowStreaming 是一套云原生的 Kafka 管控平台其社区协作遵循标准的 Fork Pull Request 模式。读完本文你将掌握 KnowStreaming 社区从创建/认领 Issue、编写合规 Commit-Log到发起 Pull Request 并合入主仓库的完整操作流程与全部命令可直接照着步骤完成第一次代码贡献。1、KnowStreaming 社区与贡献者角色KnowStreamingKS是滴滴开源的一站式 Kafka 管控平台通过零侵入、插件化方式纳管0.10.x ~ 3.x.x多个版本的 Kafka 集群。在向仓库提交代码之前建议先了解社区的角色划分与行为准则这决定了你的 PR 被合并后获得的社区身份。1.1、行为准则所有贡献者包括 User、Contributor、Committer、PMC都必须阅读并遵守项目的行为准则见仓库根目录的 CODE_OF_CONDUCT.md。该准则基于 Contributor Covenant 1.4 版本核心要求包括使用友好包容的语言、尊重不同观点与经验、优雅接受建设性批评、以社区利益为重、对其他社区成员展现同理心同时明确了维护者有权对不符合准则的评论、提交、代码等内容进行移除、编辑或拒绝。1.2、三种贡献者角色根据 docs/contribute_guide/贡献名单.md 的定义KnowStreaming 开发者包含三种角色角色定义与标准Maintainer完成多个关键模块或工程的设计与开发是项目核心开发人员持续投入并积极参与社区、官网、Issue、PR 等事项维护在社区中具有有目共睹的影响力能代表项目参加重要会议与活动具有培养 Committer 和 Contributor 的意识和能力Committer具有仓库写权限的个人长期持续贡献 Issue、PR参与 Issue 列表维护、重要 feature 讨论与 code reviewContributor对项目有贡献的个人标准为提交过 PR 并被合并从仓库的 CONTRIBUTING.md 可以看出社区还鼓励新人从 User 一路成长为 Contributor、Committer 甚至 PMC并有相应的开源奖励计划贡献者名单展示、纸质与电子版贡献者证书、贡献者礼包等。贡献者名单含姓名、GitHub、角色、所属公司见 docs/contribute_guide/贡献名单.md。2、Issue 规范高质量地报告与认领问题2.1、创建 Issue在 GitHub 的 Issues 页面按模板创建 Issue 即可。原指南重点强调创建 Issue 时必须提供出现问题的环境信息包括使用的操作系统、使用的 KnowStreamingKS版本等出现问题的复现方式让维护者与社区其他成员能够按步骤稳定复现。这两点信息对于定位 Kafka 集群纳管、监控指标采集、健康巡检等场景下的问题尤为关键。对于想要直接上手贡献的新人可以优先挑选带有以下标签的 Issuecontribution welcome社区非常需要解决或新增的 Issuegood first issue对新人友好适合练手热身。2.2、认领问题在 Issue 评论区留言说明自己要处理该问题即可完成认领。仓库文档给出的示例是在 Issue #869 的评论区由贡献者fengqiongfeng留言我来处理从而避免同一问题被多人重复处理。认领前请确认该 Issue 尚未被他人处理认领后尽快进入开发流程。3、Commit-Log 规范Commit-Log是代码贡献中最容易被 review 的环节。KnowStreaming 的提交信息由三部分组成Header、Body、Footer其中Header为必须项且格式固定Body仅在变更有必要详细解释时使用。3.1、Header 规范Header格式为[Type]Message由Type与Message两部分组成Type说明本次提交的类型常见取值包括Bugfix修复缺陷、Feature新增功能、Optimize优化已有实现等Message说明提交的具体内容如修复 xx 问题。实际例子来自仓库贡献记录[Bugfix]修复新接入的集群Controller-Host不显示的问题通过检索仓库 Releases_Notes.md 等提交记录可以看到[Bugfix]、[Optimize]等带方括号的 Type 前缀在项目实际提交中被广泛使用贡献者提交代码时应保持这一风格的一致性。3.2、Body 规范一般情况不需要Body。如果解决了较复杂的问题或本次变更代码较多则需要用Body说清楚解决了什么问题、解决思路是什么。3.3、完整示例仓库指南给出的一个完整 Commit-Log 示例含 Header 与 Body[Optimize]优化 MySQL ES 测试容器的初始化 主要的变更 1、knowstreaming/knowstreaming-manager 容器 2、knowstreaming/knowstreaming-mysql 容器调整为使用 mysql:5.7 容器 3、初始化 mysql:5.7 容器后增加初始化 MySQL 表及数据的动作 被影响的变更 1、移动 km-dist/init/sql 下的MySQL初始化脚本至 km-persistence/src/main/resource/sql 下以便项目测试时加载到所需的初始化 SQL 2、删除无用的 km-dist/init/template 目录 3、因为 km-dist/init/sql 和 km-dist/init/template 目录的调整因此也调整 ReleaseKnowStreaming.xml 内的文件内容该示例同时体现了两个实操要点一是影响面较大的变更要在Body中分条列出主要变更与被影响的变更二是目录或资源位置调整时要同步更新打包配置如ReleaseKnowStreaming.xml与测试资源加载路径。提示原指南中也留下了 TODO欢迎有兴趣的同学考虑引入 Git Hook 对 Commit-Log 做更好的自动化管理。4、Pull-Request 规范创建 Pull Request 时除了在 GitHub 页面按 PR 模板填写页面会提示按模板规范填写标题与内容模板位于上游主仓库的.github/PULL_REQUEST_TEMPLATE.md当前镜像仓库未包含该文件还有两条必须遵守的硬性要求任何 PR 都必须与有效的 ISSUE 相关联否则 PR 将被拒绝一个分支只修改一件事一个 PR 只修改一件事。这两条规则保证了 Issue、Commit 与 PR 三者之间可以一一追溯也保证了 review 与合并的可维护性。仓库的 CONTRIBUTING.md 进一步补充了相关约定从源仓库的开发分支拉取并创建自己的本地分支进行修改完成后 rebase 开发分支并解决冲突再 push 到自己的 Fork 仓库若 PR 包含较大变更如组件重构或新组件请在对应的 Issue 中编写有关设计与使用的详细文档单个 PR 不宜过大大量更改应拆分为多个独立 PR合并前尽量将多次修改的提交合并为一次保持提交信息清晰简洁PR 创建后会被分配一个或多个 reviewer。代码审查原则来自 CONTRIBUTING.md原则要求可读性重要代码应有详细文档API 应有 Javadoc代码风格与现有风格保持一致优雅新的函数、类或组件应设计良好可测试性单元测试用例应覆盖 80% 的新代码可维护性遵守项目的编码规范5、完整操作示例从环境初始化到 PR 合并本节是原指南的核心实操部分。先明确两个名词主仓库https://github.com/didi/KnowStreaming 为上游主仓库分仓库Fork 到自己账号下的 KnowStreaming 仓库为分仓库。5.1、初始化环境按以下步骤完成 Fork、克隆与 remote 配置Fork 主仓库进入主仓库页面点击右上角的Fork按钮将仓库复制到自己账号下克隆分仓库到本地分仓库的简写名通常是origingit clone gitgithub.com:xxxxxxx/KnowStreaming.git添加主仓库为 upstreamupstream是主仓库在本地约定的简写名可随意命名前后保持一致即可git remote add upstream https://github.com/didi/KnowStreaming拉取主仓库代码git fetch upstream拉取分仓库代码git fetch origin将主仓库的master分支拉取到本地并命名为github_mastergit checkout -b github_master upstream/master说明原指南此处写作git checkout -b upstream/master其意图是从主仓库的master分支创建本地分支并命名为github_master实际操作时使用上述完整命令即可达到同样效果。初始化完成后的效果如下图所示——本地git remote -v可见origin个人分仓库与upstream官方主仓库两个 remotegit branch可见github_master、master以及后续基于主分支创建的fix_928开发分支至此环境初始化完成。后续github_master分支即代表主仓库的master分支可以随时使用git pull拉取该分支的最新代码也可以使用git checkout -b xxx基于它创建任意新分支。5.2、认领问题在目标 Issue 的评论区留言说明自己要处理该问题即可完成认领见第 2.2 节。仓库文档以 Issue #869 为例展示了该流程贡献者在评论区提交我来处理页面顶部同步提示评论说明自己要处理该问题即可避免被重复处理。5.3、处理问题 提交解决处理问题与提交解决阶段的核心是分支管理整体流程如下图所示按以下步骤操作切换到主分支git checkout github_master主分支拉取最新代码git pull基于主分支创建新分支以修复 Issue #928 为例分支命名为fix_928git checkout -b fix_928提交代码并按第 3 节的 Commit-Log 规范填写提交信息git commit -m [Optimize]优化xxx问题推送到自己的远端分仓库--set-upstream会建立本地分支与远端分支的跟踪关系git push --set-upstream origin fix_928在 GitHub 页面发起 Pull Request等待管理员合入主仓库详见 5.4 节。5.4、请求合并创建 Pull Request代码推送到 GitHub 分仓库之后即可在 GitHub 网站创建 Pull Request申请将代码合入主仓库。以仓库文档中的实际案例PR #945为例创建页面如下图所示创建 PR 时的要点目标分支选择主仓库didi/KnowStreaming的master分支上游仓库的分支模型遵循 git-flow 风格开发分支为dev详见 CONTRIBUTING.md源分支选择自己分仓库如ZQKC/KnowStreaming中本次修改的分支如fix_944标题与内容按 PR 模板规范填写标题同样遵循[Type]描述(#Issue号)风格如[Bugfix]订正失效的邮箱地址(#944)按第 4 节要求确保 PR 与有效 Issue 关联。6、常见问题如何将多个 Commit-Log 合并为一个问题在开发过程中产生了多个 commit是否需要在提交 PR 前将它们合并为一个回答可以不需要将多个 commit 合并为一个。如果确实要合并可以使用git rebase -i命令进行交互式变基例如git rebase -i github_master进入交互界面后将需要合并的提交对应的操作从pick改为squash或s保存退出后按提示整理最终的提交信息即可。这样可以让最终合入主仓库的提交历史保持清晰符合合并前尽量将多次修改的提交合并为一次的 PR 规范。7、从 Contributor 到 Committer 的进阶之路完成一次 PR 合并即成为 Contributor。若希望进一步成为 Committer参考 CONTRIBUTING.md贡献8 个重要补丁并让至少3 个不同的人review 过这些 PR需要 3 个 Committer 的支持请人提名可在 KnowStreaming 的 Issue 中使用nomination标签发起提名提名需包含姓名、指向个人 GitHub 资料的链接、为什么应成为 Committer、能证明能力的 3 个 PR 及相关 Issue 说明另外 2 个 Committer 需支持该提名若 5 个工作日内无人反对即为 Committer若有人反对或需要更多信息Committer 会讨论并通常在 5 个工作日内达成共识。8、总结KnowStreaming 的贡献流程可以浓缩为一条主线创建/认领 Issue → Fork 配置 upstream → 基于github_master拉新分支 → 按[Type]Message规范提交 → push 到分仓库 → 创建与 Issue 关联的 PR → review 并合并。两条红线贯穿始终PR 必须关联有效 Issue、一个分支/一个 PR 只做一件事。按照本文的步骤与命令操作即可顺利完成你的第一次 KnowStreaming 代码贡献。相关仓库文档索引行为准则CODE_OF_CONDUCT.md贡献总览角色、审查原则、奖励计划CONTRIBUTING.md贡献指南本文主体docs/contribute_guide/贡献指南.md贡献者角色定义与名单docs/contribute_guide/贡献名单.md代码规范docs/contribute_guide/代码规范.md当前仓库中该文档标注为 TODO实际以仓库现有代码风格为准提交记录与发布说明可查看[Bugfix]、[Optimize]等 Type 的实际用法Releases_Notes.md赞分享后端消息队列运维可观测性【免费下载链接】KnowStreaming一站式云原生实时流数据平台通过0侵入、插件化构建企业级Kafka服务极大降低操作、存储和管理实时流数据门槛项目地址https://gitcode.com/gh_mirrors/kn/KnowStreaming点击查看免费下载相关推荐agent-orchestrator 贡献指南从认领 Issue 到合入 PR 的完整协作流程agent orchestrator 贡献指南从认领 Issue 到合入 PR 的完整协作流程 本指南以仓库根目录 CONTRIBUTING.md httpsCANN HIXL 社区贡献指南从 Issue 提交、Commit 规范到 PR 合入的完整协作流程CANN HIXL 社区贡献指南从 Issue 提交、Commit 规范到 PR 合入的完整协作流程 本篇指南面向希望参与 CANN / HIXL 开源仓库通信网络高性能计算CANNAscendLingo.dev 贡献指南从 Issue 认领到 PR 合并的完整开发流程Lingo.dev 贡献指南从 Issue 认领到 PR 合并的完整开发流程 本文以 Lingo.dev 开源仓库本地镜像位于 GitHub_Trendin开发工具AI 应用前端上一篇jQuery.countdown终极指南如何在3分钟内为网站添加专业倒计时功能下一篇【亲测免费】 RabbitMQ模拟器一款强大的消息队列学习与测试工具创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表