簡介
在您深入開發之前,我們希望您先了解以下幾點:- Overleaf 官方是在一個內部儲存庫中進行開發,社群版則發布於 overleaf/overleaf。一個 copybot 負責在內部與公開儲存庫之間同步程式碼。
- Ayaka-notes/overleaf-pro 是 Overleaf 社群版的分支版本。我們希望這個專案能夠長期維護,因此在貢獻之前請遵守以下規則。
提交規則
- 請勿對既有的 Overleaf 程式碼進行大幅修改。請盡可能將功能集中在
services/web/modules資料夾中,這能將我們日後合併與更新程式碼的工作量降到最低。 - Vibe coding 確實是一種非常簡便的方式,但它很容易把專案弄得一團亂,導致日後難以維護,因此請謹慎使用。
- 請盡可能重複使用既有的翻譯鍵。若確實需要新的鍵,請一次為所有語言將其加入
services/web/locales/locales_patches/added/,請參閱 更新 i18n 翻譯。 - 除非絕對必要,否則請避免引入環境變數。若確實需要,請確保它們盡可能與 Overleaf toolkit 或 docs.overleaf.com 中的環境變數保持一致。
分支規則
我們在 overleaf-pro 開發中使用以下分支:main:此分支僅用於同步上游程式碼,請不要提交任何外部變更。在此分支中,我們會設定一些像ce-v[X.x.x]這樣的標籤,表示其對應於 Overleaf 官方社群版的v[X.x.x]。注意:此標籤不可變更!server-pro:此分支是日常開發的預設分支。feat-X:此分支用於開發特定功能,例如feat-gitea-sync。release-vX.Y.Z:專門用於發布的分支,我們會在發布前於此進行一些 hot-fix。修補版本也有自己的分支,例如release-v6.3.1。發布的提交會在此分支上標記為pro-vX.Y.Z。

Overleaf Pro 的分支規則
GitHub Action
GitHub Action 負責自動化 CI/CD。您不需要在自己的電腦上建置映像檔:以下每個映像檔都由工作流程建置,具備手動觸發功能的工作流程更可一鍵完成建置。- 開發映像檔每個只包含一個微服務(
web、webpack、clsi……),支援linux/amd64與linux/arm64。Codespace 環境會透過develop/docker-compose.image.yml拉取這些映像檔,而不必執行bin/build。 - 維運映像檔是完整的單一容器映像檔(類似
sharelatex/sharelatex),用於端對端測試變更。ops:latest只會在推送至server-pro時更新;PR 只會取得帶時間戳記的標籤。這些映像檔會保留 7 天,僅供測試使用。 - 發布映像檔是使用者實際部署的映像檔。版本號取自分支名稱,因此
release-v6.3.0會發布overleaf-pro:6.3.0。
1
手動執行工作流程
開啟 Actions 分頁,在左側選擇工作流程,點選 Run workflow 並確認。Build Operations Image 另提供 Build without cache 選項,可在快取層過舊時使用。
2
在您的 Fork 中建置
相同的工作流程也能在 fork 中執行:在您的 fork 中啟用 Actions,然後從其 Actions 分頁執行即可。映像檔會使用內建的
GITHUB_TOKEN 推送至 ghcr.io/<your-name>/overleaf-pro/...,因此不需要任何 secrets。Sync Upstream Code 與舊映像檔清理只會在 ayaka-notes 中執行。Build Release Image 需要您的 fork 中有 release-v* 分支。若要查看映像檔是由哪個 commit 建置的:維運映像檔的標籤結尾即為簡短的 commit hash,而發布映像檔則將其記錄在
com.overleaf.pro.revision 標籤中(請參閱下方問與答中的 docker inspect)。問與答
如何找到 Overleaf 社群版 X.0.0 對應的 commit hash?
如何找到 Overleaf 社群版 X.0.0 對應的 commit hash?
為什麼 6.0.0 與 6.0.1 的 CE 映像檔中 commit hash 相同?
為什麼 6.0.0 與 6.0.1 的 CE 映像檔中 commit hash 相同?
這是預期中的行為。6.0.1 是建立在 6.0.0 映像檔之上的小型修補版本。這些變更是透過修補既有的 6.0.0 映像檔來套用,而不是從新的 commit 重新建置映像檔。因此,映像檔內的 commit hash 在 6.0.0 與 6.0.1 之間是相同的。詳細資訊請參閱 hotfix。

