經過近一個月的學習,從實戰入門到深入原始碼,我們已經對 DataFusion 有了相當深入的理解。
Apache DataFusion 是一個由全球貢獻者共同維護的開源專案,從 Apple、InfluxData 到個人開發者,各種背景的人都在為它添磚加瓦。今天是本系列的最後一天,我們來聊聊如何參與這個開源專案的貢獻。
這不需要什麼特殊條件——如果你已經跟著這個系列學習到這裡,你就已經有足夠的基礎了
首先準備一個能夠開發和測試的環境。
# 在 GitHub 上 Fork apache/datafusion
# 然後 clone 你的 fork
git clone https://github.com/YOUR_USERNAME/datafusion.git
cd datafusion
# 添加上游倉庫作為 remote
git remote add upstream https://github.com/apache/datafusion.git
確保你已安裝 Rust(建議使用 rustup):
# 執行完整測試套件(第一次會比較慢)
cargo test
# 如果測試都通過,你的環境就準備好了!
DataFusion 使用以下工具來維護程式碼品質:
# 程式碼格式化(必須在提交前執行)
cargo fmt --all
# 程式碼靜態分析(會提示潛在問題)
cargo clippy --all -- -D warnings
# 執行特定模組的測試
cargo test -p datafusion-expr
重要提示:在提交 PR 之前,務必確保 cargo fmt
和 cargo clippy
都沒有錯誤,否則 CI 會失敗。
在 Day 8 我們探討過 DataFusion 的專案結構,這裡快速回顧:
DataFusion 專案結構:
datafusion/
├── datafusion/ # 主要入口,統整所有功能
├── datafusion-expr/ # 邏輯表達式和計劃
├── datafusion-sql/ # SQL 解析器
├── datafusion-optimizer/ # 查詢優化器
├── datafusion-physical-plan/ # 物理執行計劃
├── datafusion-physical-expr/ # 物理表達式
└── datafusion-common/ # 共用工具和類型
尋找感興趣的模組:
datafusion-sql
datafusion-optimizer
datafusion-physical-plan
最容易入手的方式,不需要深入程式碼:
修復 Bug 能讓你更理解程式碼運作。步驟:
good first issue
流程:
1. 重現問題
└─> 根據 Issue 描述寫一個測試案例
2. 定位問題
└─> 使用除錯工具或日誌找到問題根源
3. 實作修復
└─> 修改程式碼,確保測試通過
4. 新增測試
└─> 確保這個 Bug 未來不會再出現
5. 提交 PR
└─> 清楚描述問題和解決方案
熟悉程式碼庫後,可以試試新功能。
實作新的 SQL 函數是不錯的練習:
// 假設要實作 REVERSE(string) 函數
// 1. 在 datafusion-functions 中定義函數邏輯
use datafusion_expr::ColumnarValue;
pub fn reverse(args: &[ColumnarValue]) -> Result<ColumnarValue> {
// 實作反轉字串的邏輯
// ...
}
// 2. 註冊函數
// 在適當的位置添加函數註冊
回顧 Day 13 的優化器框架,可以試著實作新的優化規則:
// 實作一個新的優化規則
impl OptimizerRule for MyNewRule {
fn name(&self) -> &str {
"my_new_optimization"
}
fn optimize(
&self,
plan: &LogicalPlan,
config: &dyn OptimizerConfig,
) -> Result<LogicalPlan> {
// 你的優化邏輯
}
}
增加測試也很有價值:
完成修改後的檢查清單:
# ✓ 執行所有測試
cargo test
# ✓ 格式化程式碼
cargo fmt --all
# ✓ 通過 Clippy 檢查
cargo clippy --all -- -D warnings
# ✓ 確保沒有未提交的變更
git status
# ✓ Rebase 最新的 main 分支
git fetch upstream
git rebase upstream/main
維護者審查時:
貢獻不只是提交程式碼,參與社群討論同樣重要。
DataFusion 的 Discord 伺服器 非常活躍:
參與技巧:
在 GitHub Issues 上:
回報 Bug:
提出功能建議:
當你累積了一些貢獻後,可以考慮更深度的參與。
幫助審查其他人的 PR 是很好的學習方式:
審查 PR 的注意事項:
如果你有重大的功能想法或架構改進:
持續貢獻的認可是成為 Apache DataFusion 的 Committer:
如何成為 Committer:
讓我們通過一個具體的例子,走過完整的貢獻流程。
假設你發現 COALESCE
函數的文件缺少範例。
# 搜尋相關檔案
grep -r "COALESCE" docs/
# 找到文件位置,例如 docs/source/user-guide/sql/scalar_functions.md
# 建立新分支
git checkout -b improve-coalesce-docs
# 編輯文件,新增範例
# 儲存變更
# 提交變更
git add docs/source/user-guide/sql/scalar_functions.md
git commit -m "docs: add examples for COALESCE function"
# 推送到你的 fork
git push origin improve-coalesce-docs
在 GitHub 上建立 PR,填寫描述:
## What changes are proposed in this pull request?
Add usage examples for the COALESCE function in the documentation.
## Why are the changes needed?
The current documentation lacks practical examples, which makes it harder for new users to understand how to use this function.
## How was this patch tested?
- Manually verified the documentation renders correctly
- Tested the example queries to ensure they work as expected
Reviewer 可能會提出一些建議,例如:
"Could you also add an example showing COALESCE with NULL values?"
你可以:
# 修改文件,新增建議的範例
git add docs/source/user-guide/sql/scalar_functions.md
git commit -m "docs: add NULL handling example for COALESCE"
git push origin improve-coalesce-docs
PR 會自動更新,完成後就會被合併!
A: 絕對可以!從文件改進、測試案例開始都是很好的貢獻。在過程中你會逐漸熟悉程式碼庫,能力也會隨之提升。
A: 這很正常!即使是資深貢獻者也會有 PR 被拒絕的情況。重要的是理解被拒絕的原因,學習改進。你可以:
A: Git 衝突在協作專案中很常見:
# 1. 拉取最新的上游變更
git fetch upstream
git rebase upstream/main
# 2. 如果有衝突,Git 會提示你
# 手動解決衝突後:
git add <resolved-files>
git rebase --continue
# 3. 強制推送(因為 rebase 改變了歷史)
git push origin your-branch --force
A: 不需要!DataFusion 是 Apache 專案,採用 Apache License 2.0。你只需要確保你的貢獻使用這個授權即可。
開源貢獻是一段旅程,而不是終點。你的第一個 PR 可能只是修正一個錯字,但這就是開始。隨著時間累積,你會發現自己不僅對 DataFusion 理解更深,也成為了這個全球社群的一份子。
這是本系列的最後一篇文章,但這不是你與 DataFusion 旅程的結束。相反的,這是一個新開始:
下一步該做什麼:
記住:每個專家都曾是初學者,每個貢獻者都從第一個 PR 開始。
感謝你完成了這 30 天的學習之旅。期待在 DataFusion 社群中見到你!