简介
在开始开发之前,我们希望你先了解以下几点:- 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:专用于发布的分支,我们会在发布前在此进行一些热修复。补丁版本也有自己的分支,例如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/...,因此无需配置任何密钥。Sync Upstream Code 和旧镜像清理仅在 ayaka-notes 中运行。Build Release Image 需要你的 Fork 中存在 release-v* 分支。查看镜像是基于哪个提交构建的:运维镜像的标签以短提交哈希结尾,发布镜像则在
com.overleaf.pro.revision 标签中记录该哈希(参见下方问答中的 docker inspect)。问答
如何找到 Overleaf 社区版 X.0.0 对应的提交哈希?
如何找到 Overleaf 社区版 X.0.0 对应的提交哈希?
为什么 CE 镜像 6.0.0 和 6.0.1 中的提交哈希相同?
为什么 CE 镜像 6.0.0 和 6.0.1 中的提交哈希相同?
这是预期行为。6.0.1 版本是基于 6.0.0 镜像构建的小型补丁版本。这些更改是通过对现有 6.0.0 镜像打补丁实现的,而不是基于新的提交重新构建镜像。因此,6.0.0 和 6.0.1 镜像中的提交哈希是相同的。详细信息请参阅 hotfix。

