Apache DolphinScheduler 自动化发版工具tools/release 使用指南与源码解析【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinschedulerDolphinScheduler 仓库下的 tools/release 目录提供了一套基于 Python 的自动化发版辅助工具围绕 GitHub 的 Milestone 聚合已合并的 Pull Request自动完成「分支 cherry-pick、Release Changelog 生成、贡献者名单生成」三项高频发版操作。本文将先介绍该工具的环境准备与三个子命令的实际用法再深入 release.py 与 github 包的源码说明其底层如何调用 GitHub RESTful API、如何对 PR 分类以及如何处理 cherry-pick 冲突帮助 Release Manager 与社区贡献者快速上手并理解其实现原理。工具定位与目录结构tools/release是 Apache DolphinScheduler 官方发版流程中的辅助脚本集合其定位是「把发版过程中机械、重复的 Git 与 GitHub 操作自动化」。整个目录结构如下tools/release/ ├── README.md # 使用说明本文对应的原始文档 ├── release.py # 命令行入口定义三个子命令 ├── requirements.txt # Python 依赖声明 └── github/ ├── __init__.py ├── changelog.py # 按标签分类 PR 并生成 Changelog 文本 ├── git.py # 封装 GitPython执行 cherry-pick 等 Git 操作 ├── pull_request.py# 封装 GitHub PR / 搜索 REST API ├── resp_get.py # 统一的 HTTP GET 封装支持分页拉取 └── user.py # 从 PR 列表提取贡献者依赖方面requirements.txt 只声明了两个包requests~2.28 GitPython~3.1其中requests用于调用 GitHub RESTful APIGitPython用于在本地仓库执行git cherry-pick等操作整体依赖非常轻量。准备环境要求与依赖安装原文档要求的环境非常基础任何常规开发机均可满足Python3.6 或以上版本release.py中使用了 f-string、typing注解等语法均需 Python 3.6pip建议使用最新版本避免旧版 pip 在解析依赖时出现兼容问题。进入tools/release目录后执行以下命令安装依赖python -m pip install -r requirements.txt安装完成后即可使用。注意由于工具会读取本地 Git 仓库执行 cherry-pick运行时应确保当前目录处于 DolphinScheduler 的 Git 仓库工作区中关于这一点git.py 会通过相对路径定位仓库根目录下的.git目录详见下文「cherry-pick 的本地仓库定位」一节。配置环境变量Token 与 Milestone运行任何子命令前都必须先导出两个环境变量export GH_ACCESS_TOKENYOUR-GITHUB-TOKEN-WITH-REPO-ACCESS export GH_REPO_MILESTONEYOUR-MILESTONE两个变量的含义与要求如下环境变量含义要求GH_ACCESS_TOKENGitHub Personal Access Token只需授予repo范围内的全部权限用于读取 PR 信息、操作私有/公开仓库GH_REPO_MILESTONE目标 Milestone 名称即 GitHub 仓库中为本次发版创建的 Milestone 标题Token 可以在 GitHub 个人设置中的 Developer settings 里创建Personal Access Token。原文档特别强调token 只需repo权限即可不需要更高权限。在源码层面release.py 会从环境变量读取这两个值若任一为空则直接抛出RuntimeErrorENV_ACCESS_TOKEN os.environ.get(GH_ACCESS_TOKEN, None) ENV_MILESTONE os.environ.get(GH_REPO_MILESTONE, None) if ENV_ACCESS_TOKEN is None or ENV_MILESTONE is None: raise RuntimeError( Environment variable GH_ACCESS_TOKEN and GH_REPO_MILESTONE must provider )也就是说漏配任何一个变量都会在启动阶段立刻报错而不是等到请求 API 时才失败便于尽早发现问题。命令总览与帮助工具的命令行入口是 release.py它基于argparse构建了三个子命令见 build_argparse子命令功能对应函数cherry-pick将指定 Milestone 中已合并的 PR 逐个 cherry-pick 到当前分支auto_cherry_pickchangelog根据指定 Milestone 生成发版 Changelog 文本get_changelogcontributor列出指定 Milestone 中所有贡献者 IDget_contributor查看完整帮助python release.py -h输出会列出上述三个子命令及其用途说明。三个子命令的执行路径完全一致argparse解析子命令后通过set_defaults(func...)把对应的处理函数绑定到args.func最后在__main__中统一调用release.pyargs arg_parser.parse_args() print(args.func(ENV_ACCESS_TOKEN, ENV_MILESTONE))三个 Action 详解Auto cherry-pick自动挑选 PR 到发布分支当发布分支如x.y.z-release需要从 dev 分支合入本次发版包含的所有 PR 时可以执行python release.py cherry-pick其工作流程见 auto_cherry_pick为用 GitHub 搜索 API 拉取指定 Milestone 中所有已合并的 PR按合并时间closed_at升序排序保证 cherry-pick 顺序与合并顺序一致降低冲突概率逐个获取 PR 详情的merge_commit_sha打印将要执行的命令并实际执行for p in pr_merged_sort: pr_detail pr.get_merged_detail(p[number]) print(fgit cherry-pick -x {pr_detail[merge_commit_sha]}) Git().cherry_pick_pr(pr_detail)原文档特别说明了两点行为特征默认分支未更新会报错如果本地仓库缺失某个 PR 的合并提交 SHAcherry-pick 会失败并抛出异常冲突时可修复后直接重跑工具是幂等的冲突修复后重新执行命令会跳过已成功应用的提交、继续处理剩余 PR。这两点均能在 git.py 的cherry_pick_pr实现中得到印证def cherry_pick_pr(self, pr: Dict) - None: sha pr[merge_commit_sha] if not self.has_commit_global(sha): raise RuntimeError( Cherry-pick SHA %s error because SHA not exists, please make sure you local default branch is up-to-date, sha, ) if self.has_commit_current(sha): print(SHA %s already in current active branch, skip it., sha) self.repo.git.cherry_pick(-x, sha)关键实现细节使用git cherry-pick -x添加-x参数在提交信息中记录原始提交 SHA便于追溯has_commit_globalgit.py检查 SHA 是否存在于本地所有分支中——不存在则说明本地默认分支没有拉最新代码直接报错has_commit_currentgit.py检查 SHA 是否已包含在当前活动分支中——若已包含则打印跳过信息这正是「重跑继续」的幂等性来源。另外工具通过git_dir_pathgit.py定位仓库根目录下的.git从github/git.py所在目录向上回溯四层即到达tools/release的上层仓库根目录再拼接.git。因此只要在克隆好的 DolphinScheduler 仓库内运行脚本即可。Generate changelog自动生成发版 Changelog执行python release.py changelog工具会拉取指定 Milestone 中所有已合并 PR并按 PR 标签自动归类生成 Changelog 文本见 get_changelog。输出结构见 changelog.py为若干个按类型命名的章节每个章节以details折叠块包裹## Feature detailssummaryClick to expand/summary - PR 标题 (#PR 号) 提交者 GitHub ID /details分类规则是这套工具的核心逻辑定义在 changelog.py 的类注释中Each pull requests will only once in final result. If pull requests have more than one label we need, will classify to high priority label type, currently priority isfeature bug improvement document chore.即每个 PR 只归入一个章节当 PR 带有多个相关标签时按优先级feature bug improvement document chore归入高优先级章节。例如一个同时带feature和improvement标签的 PR 只会进入 Feature 章节。分类的具体实现在 classify依次调用_is_feature、_is_bugfix、_is_improvement、_is_document、_is_chore判定均不匹配则落入others。生成的目标章节依次为## Feature新功能## Improvement改进## Bugfix缺陷修复## Document文档## Chore杂项## Others未分类每个条目由_convertchangelog.py格式化格式为- {title} (#{number}) {user.login}即标题、PR 号和提交者可直接粘贴进 GitHub Release Notes。值得注意的是classify在 PR 缺少labels字段时会抛出KeyErrorchangelog.py因此要求仓库内所有已合并 PR 都必须打上上述标签之一这也从侧面反映了 DolphinScheduler 社区对 PR 标签规范的约定。在完整发版流程中changelog 的产出用于创建 GitHub Release Note——官方发版指南对应英文版为 docs/docs/en/contribute/release.md提到可以在投票邮件发出前运行python release.py changelog自动生成再人工整理后发布。Generate contributor生成贡献者名单执行python release.py contributor工具会统计指定 Milestone 中所有已合并 PR 的提交者去重后按字母序输出以逗号分隔见 get_contributorusers User(prspr_merged) contributor users.contributors() # Sort according alphabetical return , .join(sorted(contributor))去重逻辑在 user.pycontribution_num会统计每个贡献者的 PR 数量dict 累加contributors只取 key 集合完成去重。因此同一贡献者提交多个 PR 也只会出现一次。该命令的典型用途在发版尾声官方发版指南的 News 章节 明确要求发布新闻稿时列出「自上一版本以来的所有贡献者」此时即可用python release.py contributor一键生成贡献者 GitHub ID 列表。底层实现GitHub RESTful API 与分页三个子命令的数据来源都是「指定 Milestone 中已合并的 PR」统一封装在 PullRequest 类中url_search https://api.github.com/search/issues url_pr https://api.github.com/repos/{}/pulls/{}search_merged_by_milestonepull_request.py调用 GitHub 的 Search API查询条件为repo:apache/dolphinscheduler is:pr is:merged milestone:milestone默认仓库为apache/dolphinscheduler见构造函数参数默认值返回匹配的 PR 列表get_merged_detail/get_merged_detail_by_milestonepull_request.py通过GET /repos/{repo}/pulls/{number}获取单个 PR 的完整信息包括 cherry-pick 所需的merge_commit_sha。HTTP 请求统一由 resp_get.py 处理其get_total方法resp_get.py实现了自动分页从第 1 页开始循环请求每次将page参数加 1直到某页返回的items为空才停止从而拉取全部结果。请求头中通过Authorization: token token携带凭据pull_request.py响应非 OK 时抛出ValueErrorresp_get.py。从源码结构可以推断这套封装是可复用的RespGet是通用 GET 封装PullRequest、Changelog、User各自只负责一个职责未来若要支持新的发版操作例如按标签生成统计只需在release.py中追加一个子命令并复用上述类即可。注意事项与最佳实践综合原文档与源码实现使用该工具时有几点需要留意Token 安全GH_ACCESS_TOKEN只授予repo权限即可避免在共享终端、日志或提交记录中暴露 token。Milestone 命名GH_REPO_MILESTONE必须与 GitHub 仓库中实际存在的 Milestone 名称完全一致否则搜索 API 返回空列表changelog、contributor会输出空内容cherry-pick则无事可做。运行前保持仓库最新cherry-pick 前务必先拉取并同步默认分支否则会因缺少merge_commit_sha直接报错git.py。冲突处理cherry-pick 遇冲突时手动解决冲突并git cherry-pick --continue完成后可重新运行命令已应用的提交会被自动跳过git.py。PR 标签规范生成 Changelog 依赖feature、bug、improvement、document、chore等标准标签changelog.py维护者应保证合并前 PR 标签规范否则会触发KeyError。与完整发版流程配合该工具只是 DolphinScheduler 发版流程中的一环完整的版本准备GPG 签名、Maven 发布、SVN 上传、投票、公告等请参考 官方发版指南英文版见 docs/docs/en/contribute/release.md。小结tools/release以极轻量的依赖requestsGitPython实现了发版中最繁琐的三个自动化步骤按 Milestone 自动 cherry-pick 已合并 PR、生成结构化的 Release Changelog、产出去重排序后的贡献者名单。其代码结构清晰、幂等设计友好既可以直接服务于 DolphinScheduler 的每一次版本发布也可以作为其他开源项目构建同类发版工具的参考模板。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache DolphinScheduler 自动化发版工具：tools/release 使用指南与源码解析
Apache DolphinScheduler 自动化发版工具tools/release 使用指南与源码解析【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinschedulerDolphinScheduler 仓库下的 tools/release 目录提供了一套基于 Python 的自动化发版辅助工具围绕 GitHub 的 Milestone 聚合已合并的 Pull Request自动完成「分支 cherry-pick、Release Changelog 生成、贡献者名单生成」三项高频发版操作。本文将先介绍该工具的环境准备与三个子命令的实际用法再深入 release.py 与 github 包的源码说明其底层如何调用 GitHub RESTful API、如何对 PR 分类以及如何处理 cherry-pick 冲突帮助 Release Manager 与社区贡献者快速上手并理解其实现原理。工具定位与目录结构tools/release是 Apache DolphinScheduler 官方发版流程中的辅助脚本集合其定位是「把发版过程中机械、重复的 Git 与 GitHub 操作自动化」。整个目录结构如下tools/release/ ├── README.md # 使用说明本文对应的原始文档 ├── release.py # 命令行入口定义三个子命令 ├── requirements.txt # Python 依赖声明 └── github/ ├── __init__.py ├── changelog.py # 按标签分类 PR 并生成 Changelog 文本 ├── git.py # 封装 GitPython执行 cherry-pick 等 Git 操作 ├── pull_request.py# 封装 GitHub PR / 搜索 REST API ├── resp_get.py # 统一的 HTTP GET 封装支持分页拉取 └── user.py # 从 PR 列表提取贡献者依赖方面requirements.txt 只声明了两个包requests~2.28 GitPython~3.1其中requests用于调用 GitHub RESTful APIGitPython用于在本地仓库执行git cherry-pick等操作整体依赖非常轻量。准备环境要求与依赖安装原文档要求的环境非常基础任何常规开发机均可满足Python3.6 或以上版本release.py中使用了 f-string、typing注解等语法均需 Python 3.6pip建议使用最新版本避免旧版 pip 在解析依赖时出现兼容问题。进入tools/release目录后执行以下命令安装依赖python -m pip install -r requirements.txt安装完成后即可使用。注意由于工具会读取本地 Git 仓库执行 cherry-pick运行时应确保当前目录处于 DolphinScheduler 的 Git 仓库工作区中关于这一点git.py 会通过相对路径定位仓库根目录下的.git目录详见下文「cherry-pick 的本地仓库定位」一节。配置环境变量Token 与 Milestone运行任何子命令前都必须先导出两个环境变量export GH_ACCESS_TOKENYOUR-GITHUB-TOKEN-WITH-REPO-ACCESS export GH_REPO_MILESTONEYOUR-MILESTONE两个变量的含义与要求如下环境变量含义要求GH_ACCESS_TOKENGitHub Personal Access Token只需授予repo范围内的全部权限用于读取 PR 信息、操作私有/公开仓库GH_REPO_MILESTONE目标 Milestone 名称即 GitHub 仓库中为本次发版创建的 Milestone 标题Token 可以在 GitHub 个人设置中的 Developer settings 里创建Personal Access Token。原文档特别强调token 只需repo权限即可不需要更高权限。在源码层面release.py 会从环境变量读取这两个值若任一为空则直接抛出RuntimeErrorENV_ACCESS_TOKEN os.environ.get(GH_ACCESS_TOKEN, None) ENV_MILESTONE os.environ.get(GH_REPO_MILESTONE, None) if ENV_ACCESS_TOKEN is None or ENV_MILESTONE is None: raise RuntimeError( Environment variable GH_ACCESS_TOKEN and GH_REPO_MILESTONE must provider )也就是说漏配任何一个变量都会在启动阶段立刻报错而不是等到请求 API 时才失败便于尽早发现问题。命令总览与帮助工具的命令行入口是 release.py它基于argparse构建了三个子命令见 build_argparse子命令功能对应函数cherry-pick将指定 Milestone 中已合并的 PR 逐个 cherry-pick 到当前分支auto_cherry_pickchangelog根据指定 Milestone 生成发版 Changelog 文本get_changelogcontributor列出指定 Milestone 中所有贡献者 IDget_contributor查看完整帮助python release.py -h输出会列出上述三个子命令及其用途说明。三个子命令的执行路径完全一致argparse解析子命令后通过set_defaults(func...)把对应的处理函数绑定到args.func最后在__main__中统一调用release.pyargs arg_parser.parse_args() print(args.func(ENV_ACCESS_TOKEN, ENV_MILESTONE))三个 Action 详解Auto cherry-pick自动挑选 PR 到发布分支当发布分支如x.y.z-release需要从 dev 分支合入本次发版包含的所有 PR 时可以执行python release.py cherry-pick其工作流程见 auto_cherry_pick为用 GitHub 搜索 API 拉取指定 Milestone 中所有已合并的 PR按合并时间closed_at升序排序保证 cherry-pick 顺序与合并顺序一致降低冲突概率逐个获取 PR 详情的merge_commit_sha打印将要执行的命令并实际执行for p in pr_merged_sort: pr_detail pr.get_merged_detail(p[number]) print(fgit cherry-pick -x {pr_detail[merge_commit_sha]}) Git().cherry_pick_pr(pr_detail)原文档特别说明了两点行为特征默认分支未更新会报错如果本地仓库缺失某个 PR 的合并提交 SHAcherry-pick 会失败并抛出异常冲突时可修复后直接重跑工具是幂等的冲突修复后重新执行命令会跳过已成功应用的提交、继续处理剩余 PR。这两点均能在 git.py 的cherry_pick_pr实现中得到印证def cherry_pick_pr(self, pr: Dict) - None: sha pr[merge_commit_sha] if not self.has_commit_global(sha): raise RuntimeError( Cherry-pick SHA %s error because SHA not exists, please make sure you local default branch is up-to-date, sha, ) if self.has_commit_current(sha): print(SHA %s already in current active branch, skip it., sha) self.repo.git.cherry_pick(-x, sha)关键实现细节使用git cherry-pick -x添加-x参数在提交信息中记录原始提交 SHA便于追溯has_commit_globalgit.py检查 SHA 是否存在于本地所有分支中——不存在则说明本地默认分支没有拉最新代码直接报错has_commit_currentgit.py检查 SHA 是否已包含在当前活动分支中——若已包含则打印跳过信息这正是「重跑继续」的幂等性来源。另外工具通过git_dir_pathgit.py定位仓库根目录下的.git从github/git.py所在目录向上回溯四层即到达tools/release的上层仓库根目录再拼接.git。因此只要在克隆好的 DolphinScheduler 仓库内运行脚本即可。Generate changelog自动生成发版 Changelog执行python release.py changelog工具会拉取指定 Milestone 中所有已合并 PR并按 PR 标签自动归类生成 Changelog 文本见 get_changelog。输出结构见 changelog.py为若干个按类型命名的章节每个章节以details折叠块包裹## Feature detailssummaryClick to expand/summary - PR 标题 (#PR 号) 提交者 GitHub ID /details分类规则是这套工具的核心逻辑定义在 changelog.py 的类注释中Each pull requests will only once in final result. If pull requests have more than one label we need, will classify to high priority label type, currently priority isfeature bug improvement document chore.即每个 PR 只归入一个章节当 PR 带有多个相关标签时按优先级feature bug improvement document chore归入高优先级章节。例如一个同时带feature和improvement标签的 PR 只会进入 Feature 章节。分类的具体实现在 classify依次调用_is_feature、_is_bugfix、_is_improvement、_is_document、_is_chore判定均不匹配则落入others。生成的目标章节依次为## Feature新功能## Improvement改进## Bugfix缺陷修复## Document文档## Chore杂项## Others未分类每个条目由_convertchangelog.py格式化格式为- {title} (#{number}) {user.login}即标题、PR 号和提交者可直接粘贴进 GitHub Release Notes。值得注意的是classify在 PR 缺少labels字段时会抛出KeyErrorchangelog.py因此要求仓库内所有已合并 PR 都必须打上上述标签之一这也从侧面反映了 DolphinScheduler 社区对 PR 标签规范的约定。在完整发版流程中changelog 的产出用于创建 GitHub Release Note——官方发版指南对应英文版为 docs/docs/en/contribute/release.md提到可以在投票邮件发出前运行python release.py changelog自动生成再人工整理后发布。Generate contributor生成贡献者名单执行python release.py contributor工具会统计指定 Milestone 中所有已合并 PR 的提交者去重后按字母序输出以逗号分隔见 get_contributorusers User(prspr_merged) contributor users.contributors() # Sort according alphabetical return , .join(sorted(contributor))去重逻辑在 user.pycontribution_num会统计每个贡献者的 PR 数量dict 累加contributors只取 key 集合完成去重。因此同一贡献者提交多个 PR 也只会出现一次。该命令的典型用途在发版尾声官方发版指南的 News 章节 明确要求发布新闻稿时列出「自上一版本以来的所有贡献者」此时即可用python release.py contributor一键生成贡献者 GitHub ID 列表。底层实现GitHub RESTful API 与分页三个子命令的数据来源都是「指定 Milestone 中已合并的 PR」统一封装在 PullRequest 类中url_search https://api.github.com/search/issues url_pr https://api.github.com/repos/{}/pulls/{}search_merged_by_milestonepull_request.py调用 GitHub 的 Search API查询条件为repo:apache/dolphinscheduler is:pr is:merged milestone:milestone默认仓库为apache/dolphinscheduler见构造函数参数默认值返回匹配的 PR 列表get_merged_detail/get_merged_detail_by_milestonepull_request.py通过GET /repos/{repo}/pulls/{number}获取单个 PR 的完整信息包括 cherry-pick 所需的merge_commit_sha。HTTP 请求统一由 resp_get.py 处理其get_total方法resp_get.py实现了自动分页从第 1 页开始循环请求每次将page参数加 1直到某页返回的items为空才停止从而拉取全部结果。请求头中通过Authorization: token token携带凭据pull_request.py响应非 OK 时抛出ValueErrorresp_get.py。从源码结构可以推断这套封装是可复用的RespGet是通用 GET 封装PullRequest、Changelog、User各自只负责一个职责未来若要支持新的发版操作例如按标签生成统计只需在release.py中追加一个子命令并复用上述类即可。注意事项与最佳实践综合原文档与源码实现使用该工具时有几点需要留意Token 安全GH_ACCESS_TOKEN只授予repo权限即可避免在共享终端、日志或提交记录中暴露 token。Milestone 命名GH_REPO_MILESTONE必须与 GitHub 仓库中实际存在的 Milestone 名称完全一致否则搜索 API 返回空列表changelog、contributor会输出空内容cherry-pick则无事可做。运行前保持仓库最新cherry-pick 前务必先拉取并同步默认分支否则会因缺少merge_commit_sha直接报错git.py。冲突处理cherry-pick 遇冲突时手动解决冲突并git cherry-pick --continue完成后可重新运行命令已应用的提交会被自动跳过git.py。PR 标签规范生成 Changelog 依赖feature、bug、improvement、document、chore等标准标签changelog.py维护者应保证合并前 PR 标签规范否则会触发KeyError。与完整发版流程配合该工具只是 DolphinScheduler 发版流程中的一环完整的版本准备GPG 签名、Maven 发布、SVN 上传、投票、公告等请参考 官方发版指南英文版见 docs/docs/en/contribute/release.md。小结tools/release以极轻量的依赖requestsGitPython实现了发版中最繁琐的三个自动化步骤按 Milestone 自动 cherry-pick 已合并 PR、生成结构化的 Release Changelog、产出去重排序后的贡献者名单。其代码结构清晰、幂等设计友好既可以直接服务于 DolphinScheduler 的每一次版本发布也可以作为其他开源项目构建同类发版工具的参考模板。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/gh_mirrors/do/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考