兩天、20 個 commit — 我怎麼開始貢獻 GitLab Orbit | HCYTLOG

先講背景：我是 GitLab 的社群貢獻者（Community Contributor）。Orbit 是 GitLab 內部團隊開發的專案，社群可以透過 community fork 提交 MR。這篇是我第一次貢獻的經驗。

Orbit 是什麼

先用一句話講：GitLab Orbit 是一個把你的程式碼和開發流程資料變成可查詢圖譜的引擎。

具體一點。你的 repo 裡有程式碼，GitLab 上有 MR、issue、pipeline、deployment 記錄。這些東西散落在不同地方，要回答「誰呼叫了這個函數」「改這個檔案會影響哪些 pipeline」「這個模組的測試覆蓋率如何」這類跨領域問題，你得自己串好幾個 API。

Orbit 做的事是把這些全部索引成一個 property graph — 程式碼定義、呼叫關係、繼承鏈、import 圖、加上 MR / issue / pipeline 的 SDLC 資料 — 然後讓你用 SQL 或 Query DSL 查詢。

它有兩種模式：

Orbit Local：單機 CLI，索引一個 repo 到本地 DuckDB，不需要 GitLab 帳號。跑一次大概幾秒鐘。
Orbit Remote：託管服務，索引整個 GitLab group 到 ClickHouse，搭配授權和 API 端點。

技術棧是 Rust，單一 workspace 裡 28 個 crate，支援 11 種以上的程式語言解析（Ruby、Java、Python、TypeScript、Rust、Go、C#、C/C++、Kotlin、Elixir、Bash）。用 tree-sitter 做程式碼解析，OXC 處理 JavaScript/TypeScript。

聽起來很龐大。確實是。但這不代表你不能貢獻。

怎麼找到切入點

我會開始貢獻 Orbit，起因是黑客松。GitLab Transcend Hackathon 有一個 track 是圍繞 Orbit 做應用，我的隊伍做了一個用 Orbit 圖查詢讓 AI code review 變可稽核的工具。做的過程中我一直在翻 Orbit 的原始碼和文件，發現了好幾個可以改善的地方。

第一個切入點通常不是寫 code，是文件。

我在本機跑 Orbit Local 的時候，發現 quickstart 文件假設你已經裝好 GDK（GitLab Development Kit），但其實跑 Local 根本不需要 GDK。很多想貢獻的人可能在這一步就放棄了。所以我寫了一份不需要 GDK 的開發者快速入門指南。

這就是我的第一個 MR。

我的四個 MR

兩天之內我送出了 4 個 MR，類型各不相同：

1. docs/690 — Orbit Local 開發者快速入門

最簡單的一個：寫一份從零開始的 quickstart，不假設你有 GDK。涵蓋 protoc 安裝（Linux / macOS / Windows）、build 指令、跑測試、常見問題。

後來 review 的時候 maintainer 提醒我加上 Windows 的 protoc 安裝路徑和 ontology E2E 測試的注意事項。這就是送 MR 的好處 — review 過程本身就是學習。

2. feat/847 — Java sealed type 的 permits clause 萃取

這個是 Rust 功能開發。Java 17 引入了 sealed class（JEP 409），允許用 permits 關鍵字限制哪些子類別可以繼承。但 Orbit 的 Java indexer 從來沒讀過這個欄位，所以 sealed type 的繼承階層在圖譜裡是斷的。

我做的事：

在 tree-sitter-java 的 AST 裡找到 permits 欄位，寫一個 java_permitted_types() extractor
在 code graph 裡加一個新的 EdgeKind::Permits
在 ontology schema 註冊新的 edge kind
複用既有的 link_extends 的名稱解析邏輯（抽成 resolve_disambiguated_targets）
補測試 fixture

改了 13 個檔案、+237/-36 行。聽起來很多，但其實大部分是沿著既有的 pattern 做 — Orbit 的 code graph pipeline 設計得很好，加新的 edge kind 有清楚的路徑可以跟。

3. fix/741 — Indexer 遇到超長行檔案的 log 修復

這個是典型的「用的時候踩到的 bug」。Orbit 索引 repo 時如果遇到某些行超過限制的檔案會直接跳過，但只在 DEBUG level 記 log。你在 INFO level 跑完，完全不知道有檔案被跳過了。

修法很簡單：在 INFO level 記一行「N 個檔案因為 line_too_long 被跳過」，細節留在 DEBUG。Review 之後 maintainer 建議把 aggregate 拿掉，改成每次跳過時各記一行 DEBUG。很合理的簡化。

4. docs/850 — 把前置條件整理成隨查即用的參考頁

原本 Orbit 的前置條件散落在好幾份文件裡。我把它們整理成一個獨立的參考頁面，需要的時候查就好，不用在 quickstart 裡塞一大段。

其他零散貢獻

除了這四個主要 MR，我還順手做了幾件事：

幫 Gemini CLI 接 Orbit MCP 端點寫了認證設定文件（原來需要額外指定 mcp_orbit OAuth scope）
加了 Kotlin suspend function 的測試 fixture
更新 v0.74.0 CLI 的文件
寫了 production runbook 的骨架
修了 troubleshooting 頁面的 redirect

總計 20 個 commit，+1,260/-235 行。

上手一個 2,800+ commits 的 Rust 專案沒有想像中難

講幾個我覺得降低門檻的因素：

Orbit 的 code graph pipeline 很模組化。 加一種新的 edge kind，你就跟著 EXTENDS 或 CALLS 的 pattern 走 — 加 extractor、加 edge kind enum、加 ontology config、加 fixture。每一步都有現成的範例可以照抄。我做 Java permits 的時候，大概 80% 的時間花在搞清楚「現在的 pattern 是什麼」，只有 20% 在寫新的東西。

Orbit Local 不需要複雜的基礎設施。 不用裝 ClickHouse、不用設定 NATS、不用跑 GDK。一個 cargo build 就可以開始。本地跑一次索引只要幾秒鐘，改 code → 跑測試的迴圈很快。

文件貢獻是真正的貢獻。 不要覺得「只是寫文件」不算什麼。我的 quickstart MR 收到的 review 反饋跟 Rust code MR 一樣認真。對一個還在快速成長的專案來說，降低新人門檻的文件是非常有價值的。

Maintainer 的 review 很有建設性。 每個 MR 我都學到東西。feat/847 的 review 讓我把 permits edge 從獨立方向改成跟 EXTENDS 反向對齊（更符合圖的語意）。fix/741 的 review 讓我理解 log level 設計的取捨。這種 review 品質是你自己寫 side project 拿不到的。

如果你也想貢獻

幾個建議：

先跑 Orbit Local。 glab orbit local index . 把你自己的 repo 索引一次，然後用 glab orbit local sql 查幾個 query。碰到的問題通常就是你的第一個 MR。
從 issue 列表開始。 Orbit 的 issue tracker 有標 good first issue 的項目，通常是文件、小修復、或加新語言的 test fixture。
文件永遠缺人寫。 特別是安裝步驟、平台差異、常見錯誤處理。你踩過的坑就是別人的 MR。
用 community fork 提交。 GitLab 社群貢獻者透過 community fork 送 MR，流程跟一般的 GitLab MR 一樣。
不要怕 Rust。 如果你有其他語言的經驗，Orbit 的 Rust code 讀起來沒有想像中可怕。特別是 code graph 那塊，大部分是 tree-sitter AST 操作和 pattern matching，不需要深入 lifetime 或 async 的黑魔法。

最後

兩天、20 個 commit、4 個 MR。回頭看，門檻真的沒有我想像中高。

Orbit 是一個很有意思的專案 — 把程式碼分析和 SDLC 資料統一成可查詢的圖譜，這個方向對 AI 輔助開發來說會越來越重要。而且它還在快速成長中（支援的語言一直在加、query 能力一直在擴充），現在加入剛好。

如果你對程式碼分析、知識圖譜、或 Rust 有興趣，GitLab Orbit 是一個很好的貢獻目標。歡迎在社群裡碰面。