提交列表：commits.rst 的自動(dòng)生成機(jī)制與版本演進(jìn)全景)
后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排【免費(fèi)下載鏈接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows項(xiàng)目地址https://gitcode.com/GitHub_Trending/ai/airflow點(diǎn)擊查看免費(fèi)下載Apache Airflow 的每個(gè) provider 包都附帶一份名為commits.rst的“詳細(xì)提交列表”文檔providers/apache/cassandra/docs/commits.rst正是 Apache Cassandra providerapache-airflow-providers-apache-cassandra的這一頁面。本篇以該文檔為切入點(diǎn)完整講清它的文件構(gòu)成、兩套自動(dòng)生成管線breeze 模板 Sphinx 擴(kuò)展、按版本標(biāo)簽切分 git 歷史的實(shí)現(xiàn)原理以及如何借助它追蹤該 provider 從 1.0.0 到 3.10.1 的全部版本演進(jìn)。一、文檔本體commits.rst 里實(shí)際寫了什么先完整看一下 commits.rst 在倉庫中的原始內(nèi)容去掉 Apache License 頭之后的有效部分Package apache-airflow-providers-apache-cassandra ------------------------------------------------------ Apache Cassandra https://cassandra.apache.org/__. This is detailed commit list of changes for versions provider package: apache.cassandra. For high-level changelog, see :doc:package information including changelog index. .. airflow-providers-commits::它由四部分組成包標(biāo)題Package apache-airflow-providers-apache-cassandra指明這份提交列表所屬的 pip 包一句話描述直接取自 provider.yaml 中的description字段Apache Cassandra引導(dǎo)說明聲明這是apache.cassandraprovider 各版本的詳細(xì)提交清單并用:doc:角色把“高層 changelog”指向同目錄的 index.rst——那里有發(fā)布版本、安裝命令和依賴要求表Sphinx 指令占位符.. airflow-providers-commits::整份文檔的技術(shù)核心。真正的提交列表并不保存在這個(gè)文件里而是在文檔構(gòu)建時(shí)由 Sphinx 擴(kuò)展動(dòng)態(tài)注入構(gòu)建命令帶--include-commits時(shí)否則該指令渲染為一行提示文字When you add --include-commits to the build command, this will be replaced with the list of commits.文件頭部還有三行醒目的 RST 注釋.. NOTE! THIS FILE IS AUTOMATICALLY GENERATED AND WILL BE OVERWRITTEN! .. IF YOU WANT TO MODIFY THIS FILE, YOU SHOULD MODIFY THE TEMPLATE PROVIDER_COMMITS_TEMPLATE.rst.jinja2 IN the dev/breeze/src/airflow_breeze/templates DIRECTORY這明確了兩件事該文件是自動(dòng)生成物會(huì)被覆蓋如需修改其結(jié)構(gòu)應(yīng)修改模板而不是手工編輯。下一節(jié)就跟蹤這條生成管線。二、靜態(tài)骨架的來源breeze 的 Jinja2 模板commits.rst的靜態(tài)部分標(biāo)題、描述、引導(dǎo)段、指令占位符完全由模板 PROVIDER_COMMITS_TEMPLATE.rst.jinja2 渲染而成。模板的核心邏輯模板末尾的正文部分為Package {{ PACKAGE_PIP_NAME }} ------------------------------------------------------ {{ PROVIDER_DESCRIPTION | safe }} This is detailed commit list of changes for versions provider package: {{PROVIDER_ID}}. For high-level changelog, see :doc:package information including changelog index. .. airflow-providers-commits::{{ PACKAGE_PIP_NAME }}渲染為apache-airflow-providers-apache-cassandra{{ PROVIDER_DESCRIPTION | safe }}以 RST 安全方式注入 provider 描述因此最終文檔里出現(xiàn)了帶鏈接的Apache Cassandra{{ PROVIDER_ID }}渲染為apache.cassandra點(diǎn)號(hào)形式的 provider id。調(diào)用側(cè)位于 provider_documentation.py_update_commits_rst()在 provider 發(fā)布流程中被觸發(fā)def _update_commits_rst( context: dict[str, Any], provider_id: str, target_path: Path, regenerate_missing_docs: bool, ) - None: _update_file( contextcontext, template_namePROVIDER_COMMITS, extension.rst, file_namecommits.rst, provider_idprovider_id, target_pathtarget_path, regenerate_missing_docsregenerate_missing_docs, )也就是說發(fā)布管理器在準(zhǔn)備 provider 發(fā)布文檔時(shí)breeze 會(huì)用該模板重新生成providers/apache/cassandra/docs/commits.rst與同流程生成的changelog.rst、index.rst等保持同一目錄結(jié)構(gòu)見 index.rst 中 Commits 一節(jié)的 toctree 把Detailed list of commits commits掛進(jìn)文檔樹。三、動(dòng)態(tài)內(nèi)容的來源Sphinx 擴(kuò)展 airflow-providers-commits.. airflow-providers-commits::指令由 providers_commits.py 注冊(cè)注冊(cè)入口在該文件的setup(app)def setup(app): Setup plugin app.add_directive(airflow-providers-commits, ProviderCommitsClassesDirective) if shutil.which(git) is None: raise RuntimeError(Git is not installed or not found in PATH) return {parallel_read_safe: True, parallel_write_safe: True}注意它直接依賴系統(tǒng)git——沒有 git 的構(gòu)建環(huán)境會(huì)直接報(bào)錯(cuò)因?yàn)檎麖執(zhí)峤槐矶际乾F(xiàn)場(chǎng)執(zhí)行g(shù)it log得到的。3.1 渲染開關(guān)INCLUDE_COMMITS指令的render_content()providers_commits.py#L238-L252邏輯非常直接def render_content(self, *, tags: set[str] | None, header_separator: str DEFAULT_HEADER_SEPARATOR): package_name os.environ.get(AIRFLOW_PACKAGE_NAME) if not package_name: raise ValueError(AIRFLOW_PACKAGE_NAME environment variable is not set.) if not package_name.startswith(apache-airflow-providers-): raise ValueError(...) provider_id package_name.replace(apache-airflow-providers-, ).replace(-, .) if os.environ.get(INCLUDE_COMMITS, ) true: return _get_all_changes_for_package_as_rst(provider_id) return ( When you add --include-commits to the build command, this will be replaced with the list of commits.\n\n )要點(diǎn)擴(kuò)展從AIRFLOW_PACKAGE_NAME環(huán)境變量如apache-airflow-providers-apache-cassandra反推出 provider idapache.cassandra因此同一個(gè)指令可以為所有 provider 包通用只有當(dāng)環(huán)境變量INCLUDE_COMMITStrue對(duì)應(yīng)構(gòu)建命令的--include-commits標(biāo)志時(shí)才真正執(zhí)行 git 歷史采集并渲染 RST 表格否則輸出那行占位提示——這正是當(dāng)前倉庫中commits.rst末尾那個(gè)空指令“看起來什么都沒寫”的原因提交表是構(gòu)建期產(chǎn)物不進(jìn)版本庫。3.2 數(shù)據(jù)模型Change 結(jié)構(gòu)每條提交被解析為一個(gè)Change命名元組providers_commits.py#L44-L53class Change(NamedTuple): Stores details about commits full_hash: str short_hash: str date: str version: str message: str message_without_backticks: str pr: str | Nonepr字段由正則PR_PATTERN re.compile(r.*\(#(\d)\))從提交主題中提取例如 Drop support for Python 3.10 (#74157) 會(huì)被關(guān)聯(lián)到 PR 號(hào) 74157message_without_backticks則把消息里的反引號(hào)替換為單引號(hào)避免 RST 行內(nèi)標(biāo)記被提交信息中的代碼塊語法破壞。3.3 git 歷史的采集版本標(biāo)簽與路徑過濾git 命令的構(gòu)造providers_commits.py#L81-L107git_cmd [ git, log, --prettyformat:%H %h %cd %s, --dateshort, ] if from_commit and to_commit: git_cmd.append(f{from_commit}...{to_commit}) ... folders [folder_path.as_posix() for folder_path in folder_paths] if folder_paths else [.] git_cmd.extend([--, *folders])即輸出格式為「完整哈希 短哈希 日期 提交主題」四段%H %h %cd %s日期為 short 格式后續(xù)按空格最多切 3 次拆分。提交區(qū)間用三點(diǎn)的from...to語法且-- 路徑限定只統(tǒng)計(jì)落在 provider 相關(guān)目錄內(nèi)的提交。版本標(biāo)簽方案_get_version_tag()把版本號(hào)3.10.1映射到 git 標(biāo)簽providers-apache-cassandra/3.10.1provider id 中的點(diǎn)號(hào)替換為連字符。歷史路徑兼容_get_possible_old_provider_paths()providers_commits.py#L64-L78為每個(gè) provider 額外收集三個(gè)歷史位置保證早期版本的提交也能被統(tǒng)計(jì)進(jìn)來airflow/providers/...provider 代碼最初位于主倉庫airflow包內(nèi)時(shí)的目錄providers/src/airflow/providers/...provider 拆分前的命名空間包位置docs/apache-airflow-providers-...早期獨(dú)立文檔目錄。逐版本遍歷_get_all_changes_for_package_as_rstproviders_commits.py#L178-L214讀取provider.yaml的versions列表嘗試解析下一個(gè)版本標(biāo)簽git rev-parse providers-apache-cassandra/版本若該標(biāo)簽尚不存在即最新版本還沒打 tag回退為HEAD從最新到最舊逐對(duì)相鄰版本執(zhí)行g(shù)it log每個(gè)版本區(qū)間生成一張表最新版本區(qū)間用git log 上一個(gè)標(biāo)簽無 to 參數(shù)統(tǒng)計(jì)到當(dāng)前分支頂端。表格輸出_convert_git_changes_to_tableproviders_commits.py#L128-L175用tabulate以 RST pipe 表輸出三列Commit | Committed | SubjectCommit列是[短哈希](https://github.com/apache/airflow/commit/完整哈希)形式的鏈接每張表前加版本標(biāo)題和一行Latest change: 日期取自該版本區(qū)間第一條提交的日期。四、結(jié)合 Cassandra provider 實(shí)際看版本列表與提交追蹤4.1 版本清單對(duì) Cassandra provider 而言_get_all_changes_for_package_as_rst遍歷的正是 provider.yaml 中的 35 個(gè)版本從最新的3.10.1一路回溯到1.0.0中間包括3.10.0、3.9.x全系列、3.8.x、3.7.x、3.6.0、3.5.x、3.4.x、3.3.0、3.2.x、3.1.x、3.0.0以及 2.x 時(shí)代的2.1.x/2.0.x和最初的1.0.x。因此最終渲染出的提交頁會(huì)被切分為 35 個(gè)以版本號(hào)作標(biāo)題的區(qū)塊每個(gè)區(qū)塊對(duì)應(yīng)providers-apache-cassandra/舊版本到providers-apache-cassandra/上一版本或HEAD之間的全部提交。文件里也有明確注釋versions由發(fā)布管理器維護(hù)貢獻(xiàn)者不應(yīng)手工改它只有當(dāng)其他 provider 已經(jīng)使用更高版本時(shí)才需同步 bump。4.2 提交統(tǒng)計(jì)覆蓋的代碼范圍對(duì)apache.cassandra而言git 路徑過濾覆蓋的目錄為providers/apache/cassandra現(xiàn)位置源碼在 src/airflow/providers/apache/cassandra/ 下含hooks/cassandra.py、sensors/record.py、sensors/table.py等三個(gè)歷史位置airflow/providers/apache/cassandra、providers/src/airflow/providers/apache/cassandra、docs/apache-airflow-providers-apache-cassandra。所以提交表統(tǒng)計(jì)的是“影響這個(gè) provider 的所有提交”——包括源碼、測(cè)試tests/下、文檔docs/下與元數(shù)據(jù)變更而不只是 hook/sensor 的行為變化。4.3 與 changelog 的分工commits.rst的引導(dǎo)段特意把讀者引向 changelog.rst兩者定位不同changelog是半自動(dòng)維護(hù)的“高層變更日志”按版本分組只保留對(duì)用戶有意義的條目Features/Bugfix/Misc 等并有明確規(guī)范“只有在存在 breaking change 且需要向用戶解釋應(yīng)對(duì)方式時(shí)才在 Changelog 頭部追加說明”其余由發(fā)布管理器半自動(dòng)更新commits.rst則是無過濾的“完整審計(jì)軌跡”每一行對(duì)應(yīng)一次真實(shí)提交。以當(dāng)前 3.10.1 為例changelog.rst 記錄的有效變更只有兩條3.10.1 ...... Misc ~~~~ * Drop support for Python 3.10 (#74157) Doc-only ~~~~~~~~ * Update provider READMEs for the Python 3.11 baseline (#74158)而 changelog 中“Below changes are excluded from the changelog”注釋塊里列出的那些純 CI 類提交如 [main] Upgrade important CI environment (#73629)仍會(huì)出現(xiàn)在 commits 頁的提交表中——這正是這份詳細(xì)提交列表存在的價(jià)值它補(bǔ)齊了高層 changelog 有意省略的完整歷史。4.4 讀者可用的等價(jià)查詢命令理解了生成管線后任何人都可以用同樣的 git 命令在本地倉庫復(fù)刻某一版本的提交表例如查看providers-apache-cassandra/3.9.4到providers-apache-cassandra/3.10.0之間影響該 provider 的提交git log --prettyformat:%H %h %cd %s --dateshort \ providers-apache-cassandra/3.9.4...providers-apache-cassandra/3.10.0 \ -- providers/apache/cassandra airflow/providers/apache/cassandra \ providers/src/airflow/providers/apache/cassandra \ docs/apache-airflow-providers-apache-cassandra這與 providers_commits.py 中_get_git_log_command()拼出的命令完全同構(gòu)。五、使用建議與小結(jié)用戶視角升級(jí)apache-airflow-providers-apache-cassandra前若 changelog 只給了簡(jiǎn)短條目而你想確認(rèn)某個(gè) PR 是否進(jìn)入了目標(biāo)版本應(yīng)查該 provider 文檔站上的 Detailed list of commits 頁即commits.rst渲染結(jié)果包的基本信息與安裝方式見 index.rst最低 Airflow 要求 2.11.0cassandra-driver要求隨 Python 版本分檔。貢獻(xiàn)者視角不要把commits.rst當(dāng)作可編輯文檔——它是 breeze 模板 的產(chǎn)物會(huì)被發(fā)布流程覆蓋想改結(jié)構(gòu)就改模板。同樣changelog.rst只在 breaking change 時(shí)手工補(bǔ)充說明其余交給發(fā)布工具。機(jī)制小結(jié)commits.rst breeze 模板生成的靜態(tài)骨架包名、描述、引導(dǎo)、指令占位符 Sphinx 擴(kuò)展在帶--include-commits的構(gòu)建中現(xiàn)場(chǎng)執(zhí)行的git log結(jié)果按providers-apache-cassandra/版本標(biāo)簽切分、按 provider 現(xiàn)路徑與三個(gè)歷史路徑過濾、解析成Change結(jié)構(gòu)后用tabulate渲染為帶鏈接的 RST 表格。這套機(jī)制由 devel-common/src/sphinx_exts/providers_commits.py 與 provider_documentation.py 共同實(shí)現(xiàn)對(duì)倉庫內(nèi)所有 provider 包統(tǒng)一適用Cassandra provider 的這份文檔只是它的一個(gè)具體實(shí)例。贊分享后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排【免費(fèi)下載鏈接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows項(xiàng)目地址https://gitcode.com/GitHub_Trending/ai/airflow點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Apache Airflow 的 Apache Pinot Provider 版本演進(jìn)與變更全解析1.0.0 → 4.10.3Apache Airflow 的 Apache Pinot Provider 版本演進(jìn)與變更全解析1.0.0 → 4.10.3 Apache Pinot 是后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排Joplin Android 版本日志詳解版本演進(jìn)脈絡(luò)與自動(dòng)化 Changelog 生成機(jī)制Joplin Android 版本日志詳解版本演進(jìn)脈絡(luò)與自動(dòng)化 Changelog 生成機(jī)制 本篇基于 Joplin 倉庫中的 Android 變更日志文檔知識(shí)管理跨平臺(tái)插件系統(tǒng)Apache Airflow Akeyless Provider 版本演進(jìn)深度解析從 AkeylessHook 到云原生 Secrets BackendApache Airflow Akeyless Provider 版本演進(jìn)深度解析從 AkeylessHook 到云原生 Secrets Backend Ap后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Apache Airflow Cassandra Provider 詳細(xì)提交列表：commits.rst 的自動(dòng)生成機(jī)制與版本演進(jìn)全景
后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排【免費(fèi)下載鏈接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows項(xiàng)目地址https://gitcode.com/GitHub_Trending/ai/airflow點(diǎn)擊查看免費(fèi)下載Apache Airflow 的每個(gè) provider 包都附帶一份名為commits.rst的“詳細(xì)提交列表”文檔providers/apache/cassandra/docs/commits.rst正是 Apache Cassandra providerapache-airflow-providers-apache-cassandra的這一頁面。本篇以該文檔為切入點(diǎn)完整講清它的文件構(gòu)成、兩套自動(dòng)生成管線breeze 模板 Sphinx 擴(kuò)展、按版本標(biāo)簽切分 git 歷史的實(shí)現(xiàn)原理以及如何借助它追蹤該 provider 從 1.0.0 到 3.10.1 的全部版本演進(jìn)。一、文檔本體commits.rst 里實(shí)際寫了什么先完整看一下 commits.rst 在倉庫中的原始內(nèi)容去掉 Apache License 頭之后的有效部分Package apache-airflow-providers-apache-cassandra ------------------------------------------------------ Apache Cassandra https://cassandra.apache.org/__. This is detailed commit list of changes for versions provider package: apache.cassandra. For high-level changelog, see :doc:package information including changelog index. .. airflow-providers-commits::它由四部分組成包標(biāo)題Package apache-airflow-providers-apache-cassandra指明這份提交列表所屬的 pip 包一句話描述直接取自 provider.yaml 中的description字段Apache Cassandra引導(dǎo)說明聲明這是apache.cassandraprovider 各版本的詳細(xì)提交清單并用:doc:角色把“高層 changelog”指向同目錄的 index.rst——那里有發(fā)布版本、安裝命令和依賴要求表Sphinx 指令占位符.. airflow-providers-commits::整份文檔的技術(shù)核心。真正的提交列表并不保存在這個(gè)文件里而是在文檔構(gòu)建時(shí)由 Sphinx 擴(kuò)展動(dòng)態(tài)注入構(gòu)建命令帶--include-commits時(shí)否則該指令渲染為一行提示文字When you add --include-commits to the build command, this will be replaced with the list of commits.文件頭部還有三行醒目的 RST 注釋.. NOTE! THIS FILE IS AUTOMATICALLY GENERATED AND WILL BE OVERWRITTEN! .. IF YOU WANT TO MODIFY THIS FILE, YOU SHOULD MODIFY THE TEMPLATE PROVIDER_COMMITS_TEMPLATE.rst.jinja2 IN the dev/breeze/src/airflow_breeze/templates DIRECTORY這明確了兩件事該文件是自動(dòng)生成物會(huì)被覆蓋如需修改其結(jié)構(gòu)應(yīng)修改模板而不是手工編輯。下一節(jié)就跟蹤這條生成管線。二、靜態(tài)骨架的來源breeze 的 Jinja2 模板commits.rst的靜態(tài)部分標(biāo)題、描述、引導(dǎo)段、指令占位符完全由模板 PROVIDER_COMMITS_TEMPLATE.rst.jinja2 渲染而成。模板的核心邏輯模板末尾的正文部分為Package {{ PACKAGE_PIP_NAME }} ------------------------------------------------------ {{ PROVIDER_DESCRIPTION | safe }} This is detailed commit list of changes for versions provider package: {{PROVIDER_ID}}. For high-level changelog, see :doc:package information including changelog index. .. airflow-providers-commits::{{ PACKAGE_PIP_NAME }}渲染為apache-airflow-providers-apache-cassandra{{ PROVIDER_DESCRIPTION | safe }}以 RST 安全方式注入 provider 描述因此最終文檔里出現(xiàn)了帶鏈接的Apache Cassandra{{ PROVIDER_ID }}渲染為apache.cassandra點(diǎn)號(hào)形式的 provider id。調(diào)用側(cè)位于 provider_documentation.py_update_commits_rst()在 provider 發(fā)布流程中被觸發(fā)def _update_commits_rst( context: dict[str, Any], provider_id: str, target_path: Path, regenerate_missing_docs: bool, ) - None: _update_file( contextcontext, template_namePROVIDER_COMMITS, extension.rst, file_namecommits.rst, provider_idprovider_id, target_pathtarget_path, regenerate_missing_docsregenerate_missing_docs, )也就是說發(fā)布管理器在準(zhǔn)備 provider 發(fā)布文檔時(shí)breeze 會(huì)用該模板重新生成providers/apache/cassandra/docs/commits.rst與同流程生成的changelog.rst、index.rst等保持同一目錄結(jié)構(gòu)見 index.rst 中 Commits 一節(jié)的 toctree 把Detailed list of commits commits掛進(jìn)文檔樹。三、動(dòng)態(tài)內(nèi)容的來源Sphinx 擴(kuò)展 airflow-providers-commits.. airflow-providers-commits::指令由 providers_commits.py 注冊(cè)注冊(cè)入口在該文件的setup(app)def setup(app): Setup plugin app.add_directive(airflow-providers-commits, ProviderCommitsClassesDirective) if shutil.which(git) is None: raise RuntimeError(Git is not installed or not found in PATH) return {parallel_read_safe: True, parallel_write_safe: True}注意它直接依賴系統(tǒng)git——沒有 git 的構(gòu)建環(huán)境會(huì)直接報(bào)錯(cuò)因?yàn)檎麖執(zhí)峤槐矶际乾F(xiàn)場(chǎng)執(zhí)行g(shù)it log得到的。3.1 渲染開關(guān)INCLUDE_COMMITS指令的render_content()providers_commits.py#L238-L252邏輯非常直接def render_content(self, *, tags: set[str] | None, header_separator: str DEFAULT_HEADER_SEPARATOR): package_name os.environ.get(AIRFLOW_PACKAGE_NAME) if not package_name: raise ValueError(AIRFLOW_PACKAGE_NAME environment variable is not set.) if not package_name.startswith(apache-airflow-providers-): raise ValueError(...) provider_id package_name.replace(apache-airflow-providers-, ).replace(-, .) if os.environ.get(INCLUDE_COMMITS, ) true: return _get_all_changes_for_package_as_rst(provider_id) return ( When you add --include-commits to the build command, this will be replaced with the list of commits.\n\n )要點(diǎn)擴(kuò)展從AIRFLOW_PACKAGE_NAME環(huán)境變量如apache-airflow-providers-apache-cassandra反推出 provider idapache.cassandra因此同一個(gè)指令可以為所有 provider 包通用只有當(dāng)環(huán)境變量INCLUDE_COMMITStrue對(duì)應(yīng)構(gòu)建命令的--include-commits標(biāo)志時(shí)才真正執(zhí)行 git 歷史采集并渲染 RST 表格否則輸出那行占位提示——這正是當(dāng)前倉庫中commits.rst末尾那個(gè)空指令“看起來什么都沒寫”的原因提交表是構(gòu)建期產(chǎn)物不進(jìn)版本庫。3.2 數(shù)據(jù)模型Change 結(jié)構(gòu)每條提交被解析為一個(gè)Change命名元組providers_commits.py#L44-L53class Change(NamedTuple): Stores details about commits full_hash: str short_hash: str date: str version: str message: str message_without_backticks: str pr: str | Nonepr字段由正則PR_PATTERN re.compile(r.*\(#(\d)\))從提交主題中提取例如 Drop support for Python 3.10 (#74157) 會(huì)被關(guān)聯(lián)到 PR 號(hào) 74157message_without_backticks則把消息里的反引號(hào)替換為單引號(hào)避免 RST 行內(nèi)標(biāo)記被提交信息中的代碼塊語法破壞。3.3 git 歷史的采集版本標(biāo)簽與路徑過濾git 命令的構(gòu)造providers_commits.py#L81-L107git_cmd [ git, log, --prettyformat:%H %h %cd %s, --dateshort, ] if from_commit and to_commit: git_cmd.append(f{from_commit}...{to_commit}) ... folders [folder_path.as_posix() for folder_path in folder_paths] if folder_paths else [.] git_cmd.extend([--, *folders])即輸出格式為「完整哈希 短哈希 日期 提交主題」四段%H %h %cd %s日期為 short 格式后續(xù)按空格最多切 3 次拆分。提交區(qū)間用三點(diǎn)的from...to語法且-- 路徑限定只統(tǒng)計(jì)落在 provider 相關(guān)目錄內(nèi)的提交。版本標(biāo)簽方案_get_version_tag()把版本號(hào)3.10.1映射到 git 標(biāo)簽providers-apache-cassandra/3.10.1provider id 中的點(diǎn)號(hào)替換為連字符。歷史路徑兼容_get_possible_old_provider_paths()providers_commits.py#L64-L78為每個(gè) provider 額外收集三個(gè)歷史位置保證早期版本的提交也能被統(tǒng)計(jì)進(jìn)來airflow/providers/...provider 代碼最初位于主倉庫airflow包內(nèi)時(shí)的目錄providers/src/airflow/providers/...provider 拆分前的命名空間包位置docs/apache-airflow-providers-...早期獨(dú)立文檔目錄。逐版本遍歷_get_all_changes_for_package_as_rstproviders_commits.py#L178-L214讀取provider.yaml的versions列表嘗試解析下一個(gè)版本標(biāo)簽git rev-parse providers-apache-cassandra/版本若該標(biāo)簽尚不存在即最新版本還沒打 tag回退為HEAD從最新到最舊逐對(duì)相鄰版本執(zhí)行g(shù)it log每個(gè)版本區(qū)間生成一張表最新版本區(qū)間用git log 上一個(gè)標(biāo)簽無 to 參數(shù)統(tǒng)計(jì)到當(dāng)前分支頂端。表格輸出_convert_git_changes_to_tableproviders_commits.py#L128-L175用tabulate以 RST pipe 表輸出三列Commit | Committed | SubjectCommit列是[短哈希](https://github.com/apache/airflow/commit/完整哈希)形式的鏈接每張表前加版本標(biāo)題和一行Latest change: 日期取自該版本區(qū)間第一條提交的日期。四、結(jié)合 Cassandra provider 實(shí)際看版本列表與提交追蹤4.1 版本清單對(duì) Cassandra provider 而言_get_all_changes_for_package_as_rst遍歷的正是 provider.yaml 中的 35 個(gè)版本從最新的3.10.1一路回溯到1.0.0中間包括3.10.0、3.9.x全系列、3.8.x、3.7.x、3.6.0、3.5.x、3.4.x、3.3.0、3.2.x、3.1.x、3.0.0以及 2.x 時(shí)代的2.1.x/2.0.x和最初的1.0.x。因此最終渲染出的提交頁會(huì)被切分為 35 個(gè)以版本號(hào)作標(biāo)題的區(qū)塊每個(gè)區(qū)塊對(duì)應(yīng)providers-apache-cassandra/舊版本到providers-apache-cassandra/上一版本或HEAD之間的全部提交。文件里也有明確注釋versions由發(fā)布管理器維護(hù)貢獻(xiàn)者不應(yīng)手工改它只有當(dāng)其他 provider 已經(jīng)使用更高版本時(shí)才需同步 bump。4.2 提交統(tǒng)計(jì)覆蓋的代碼范圍對(duì)apache.cassandra而言git 路徑過濾覆蓋的目錄為providers/apache/cassandra現(xiàn)位置源碼在 src/airflow/providers/apache/cassandra/ 下含hooks/cassandra.py、sensors/record.py、sensors/table.py等三個(gè)歷史位置airflow/providers/apache/cassandra、providers/src/airflow/providers/apache/cassandra、docs/apache-airflow-providers-apache-cassandra。所以提交表統(tǒng)計(jì)的是“影響這個(gè) provider 的所有提交”——包括源碼、測(cè)試tests/下、文檔docs/下與元數(shù)據(jù)變更而不只是 hook/sensor 的行為變化。4.3 與 changelog 的分工commits.rst的引導(dǎo)段特意把讀者引向 changelog.rst兩者定位不同changelog是半自動(dòng)維護(hù)的“高層變更日志”按版本分組只保留對(duì)用戶有意義的條目Features/Bugfix/Misc 等并有明確規(guī)范“只有在存在 breaking change 且需要向用戶解釋應(yīng)對(duì)方式時(shí)才在 Changelog 頭部追加說明”其余由發(fā)布管理器半自動(dòng)更新commits.rst則是無過濾的“完整審計(jì)軌跡”每一行對(duì)應(yīng)一次真實(shí)提交。以當(dāng)前 3.10.1 為例changelog.rst 記錄的有效變更只有兩條3.10.1 ...... Misc ~~~~ * Drop support for Python 3.10 (#74157) Doc-only ~~~~~~~~ * Update provider READMEs for the Python 3.11 baseline (#74158)而 changelog 中“Below changes are excluded from the changelog”注釋塊里列出的那些純 CI 類提交如 [main] Upgrade important CI environment (#73629)仍會(huì)出現(xiàn)在 commits 頁的提交表中——這正是這份詳細(xì)提交列表存在的價(jià)值它補(bǔ)齊了高層 changelog 有意省略的完整歷史。4.4 讀者可用的等價(jià)查詢命令理解了生成管線后任何人都可以用同樣的 git 命令在本地倉庫復(fù)刻某一版本的提交表例如查看providers-apache-cassandra/3.9.4到providers-apache-cassandra/3.10.0之間影響該 provider 的提交git log --prettyformat:%H %h %cd %s --dateshort \ providers-apache-cassandra/3.9.4...providers-apache-cassandra/3.10.0 \ -- providers/apache/cassandra airflow/providers/apache/cassandra \ providers/src/airflow/providers/apache/cassandra \ docs/apache-airflow-providers-apache-cassandra這與 providers_commits.py 中_get_git_log_command()拼出的命令完全同構(gòu)。五、使用建議與小結(jié)用戶視角升級(jí)apache-airflow-providers-apache-cassandra前若 changelog 只給了簡(jiǎn)短條目而你想確認(rèn)某個(gè) PR 是否進(jìn)入了目標(biāo)版本應(yīng)查該 provider 文檔站上的 Detailed list of commits 頁即commits.rst渲染結(jié)果包的基本信息與安裝方式見 index.rst最低 Airflow 要求 2.11.0cassandra-driver要求隨 Python 版本分檔。貢獻(xiàn)者視角不要把commits.rst當(dāng)作可編輯文檔——它是 breeze 模板 的產(chǎn)物會(huì)被發(fā)布流程覆蓋想改結(jié)構(gòu)就改模板。同樣changelog.rst只在 breaking change 時(shí)手工補(bǔ)充說明其余交給發(fā)布工具。機(jī)制小結(jié)commits.rst breeze 模板生成的靜態(tài)骨架包名、描述、引導(dǎo)、指令占位符 Sphinx 擴(kuò)展在帶--include-commits的構(gòu)建中現(xiàn)場(chǎng)執(zhí)行的git log結(jié)果按providers-apache-cassandra/版本標(biāo)簽切分、按 provider 現(xiàn)路徑與三個(gè)歷史路徑過濾、解析成Change結(jié)構(gòu)后用tabulate渲染為帶鏈接的 RST 表格。這套機(jī)制由 devel-common/src/sphinx_exts/providers_commits.py 與 provider_documentation.py 共同實(shí)現(xiàn)對(duì)倉庫內(nèi)所有 provider 包統(tǒng)一適用Cassandra provider 的這份文檔只是它的一個(gè)具體實(shí)例。贊分享后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排【免費(fèi)下載鏈接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows項(xiàng)目地址https://gitcode.com/GitHub_Trending/ai/airflow點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Apache Airflow 的 Apache Pinot Provider 版本演進(jìn)與變更全解析1.0.0 → 4.10.3Apache Airflow 的 Apache Pinot Provider 版本演進(jìn)與變更全解析1.0.0 → 4.10.3 Apache Pinot 是后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排Joplin Android 版本日志詳解版本演進(jìn)脈絡(luò)與自動(dòng)化 Changelog 生成機(jī)制Joplin Android 版本日志詳解版本演進(jìn)脈絡(luò)與自動(dòng)化 Changelog 生成機(jī)制 本篇基于 Joplin 倉庫中的 Android 變更日志文檔知識(shí)管理跨平臺(tái)插件系統(tǒng)Apache Airflow Akeyless Provider 版本演進(jìn)深度解析從 AkeylessHook 到云原生 Secrets BackendApache Airflow Akeyless Provider 版本演進(jìn)深度解析從 AkeylessHook 到云原生 Secrets Backend Ap后端任務(wù)調(diào)度工作流自動(dòng)化數(shù)據(jù)編排批處理數(shù)據(jù)工程流程編排創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考