Chuyển đến nội dung chính

Giới thiệu

Trước khi bắt tay vào phát triển, chúng tôi mong bạn hiểu rõ những điều sau:
  • Overleaf được phát triển chính thức trong một repository nội bộ, và phiên bản cộng đồng được công bố tại overleaf/overleaf. Một copybot chịu trách nhiệm đồng bộ mã nguồn giữa repository nội bộ và repository công khai.
  • Ayaka-notes/overleaf-pro là một bản fork của Overleaf cộng đồng. Chúng tôi mong dự án này có thể duy trì lâu dài, vì vậy hãy tuân thủ các quy tắc trước khi đóng góp.

Quy tắc commit

  • Vui lòng không chỉnh sửa quá nhiều vào mã nguồn Overleaf hiện có. Hãy tập trung càng nhiều chức năng càng tốt vào thư mục services/web/modules. Điều này giúp giảm thiểu khối lượng công việc của chúng tôi khi hợp nhất và cập nhật mã sau này.
  • Vibe coding thực sự là một cách rất dễ dàng, nhưng nó có thể dễ dàng làm rối dự án, khiến dự án khó bảo trì về sau, vì vậy hãy sử dụng một cách thận trọng.
  • Hãy tái sử dụng các khóa dịch có sẵn bất cứ khi nào có thể. Nếu thực sự cần một khóa mới, hãy thêm nó vào services/web/locales/locales_patches/added/ cho tất cả ngôn ngữ cùng lúc, xem Cập nhật bản dịch i18n.
  • Tránh thêm biến môi trường trừ khi thực sự cần thiết. Nếu bắt buộc, hãy đảm bảo chúng nhất quán nhất có thể với các biến trong Overleaf toolkit hoặc docs.overleaf.com.

Quy tắc nhánh

Chúng tôi sử dụng các nhánh sau cho việc phát triển overleaf-pro:
  • main: Nhánh này chỉ dùng để đồng bộ mã từ upstream, vui lòng KHÔNG commit bất kỳ thay đổi bên ngoài nào. Trên nhánh này, chúng tôi sẽ đặt một số tag như ce-v[X.x.x], cho biết tag này tương ứng với v[X.x.x] trong Overleaf Community Edition chính thức. Lưu ý: tag này là bất biến!
  • server-pro: Nhánh mặc định cho công việc phát triển hằng ngày.
  • feat-X: Nhánh dùng để phát triển một tính năng cụ thể, ví dụ feat-gitea-sync.
  • release-vX.Y.Z: Nhánh dành riêng cho việc phát hành, chúng tôi sẽ thực hiện một số hot-fix trước khi phát hành. Các bản vá cũng có nhánh riêng, ví dụ release-v6.3.1. Commit được phát hành sẽ được gắn tag pro-vX.Y.Z trên nhánh này.

Quy tắc nhánh của Overleaf Pro

GitHub Action

GitHub Action chịu trách nhiệm CI/CD tự động. Bạn không cần tự build image trên máy của mình: mọi image dưới đây đều được build bởi một workflow, và những workflow có kích hoạt thủ công có thể được build chỉ với một cú nhấp chuột.
  • Development image mỗi image chứa một microservice (web, webpack, clsi, …) cho linux/amd64 và linux/arm64. Thiết lập Codespace kéo chúng qua develop/docker-compose.image.yml thay vì chạy bin/build.
  • Operations image là các image đầy đủ dạng một container (giống sharelatex/sharelatex) để kiểm thử một thay đổi từ đầu đến cuối. ops:latest chỉ được cập nhật khi push vào server-pro; một PR chỉ nhận tag có dấu thời gian. Các image này được giữ trong 7 ngày và chỉ dùng cho mục đích kiểm thử.
  • Release image là những gì người dùng triển khai. Phiên bản được lấy từ tên nhánh, vì vậy release-v6.3.0 sẽ phát hành overleaf-pro:6.3.0.
1

Chạy workflow thủ công

Mở tab Actions, chọn workflow ở bên trái, nhấp Run workflow và xác nhận. Build Operations Image còn có tùy chọn Build without cache cho trường hợp một layer được cache đã lỗi thời.
2

Build trong bản fork của bạn

Các workflow tương tự cũng chạy trong một bản fork: bật Actions trong bản fork của bạn, sau đó chạy chúng từ tab Actions của nó. Image được push lên ghcr.io/<your-name>/overleaf-pro/... bằng GITHUB_TOKEN tích hợp sẵn, vì vậy không cần secret nào. Sync Upstream Code và việc dọn dẹp image cũ chỉ chạy trong ayaka-notes.Build Release Image cần một nhánh release-v* trong bản fork của bạn.
Để kiểm tra một image được build từ commit nào: tag của operations image kết thúc bằng mã hash commit rút gọn, còn release image mang mã này trong label com.overleaf.pro.revision (xem docker inspect trong phần Hỏi đáp bên dưới).

Hỏi & Đáp

Trước hết, bạn cần pull docker image và chạy lệnh sau để kiểm tra các label trong docker image này:
bash
Sau đó, bạn có thể kiểm tra xem commit (b0d05c0) có tồn tại trong nhánh master của upstream hay không.
Đây là hành vi được dự kiến. Bản phát hành 6.0.1 là một bản vá nhỏ được xây dựng dựa trên image 6.0.0. Các thay đổi được áp dụng bằng cách vá image 6.0.0 hiện có, thay vì build lại image từ một commit mới. Do đó, commit hash bên trong image giống hệt nhau giữa 6.0.0 và 6.0.1.Để biết thông tin chi tiết, xem hotfix.
Lần sửa đổi cuối 20 tháng 11, 2026