5 phút đọc
Kho chứa mã nguồn nextcloud/documentation là nơi quản lý và xuất bản toàn bộ tài liệu hướng dẫn chính thức của dự án Nextcloud tại địa chỉ docs.nextcloud.com. Theo dữ liệu ghi nhận, dự án hiện đạt 633 lượt stars, 2.554 lượt forks, sử dụng ngôn ngữ chính là JavaScript và có mốc cập nhật ghi nhận ngày 16/10/2026. Tất cả nội dung tài liệu trong kho lưu trữ này được phát hành theo giấy phép bản quyền Creative Commons Attribution 3.0 Unported (CC BY 3.0).
Quy tắc phân nhánh và nguyên tắc ổn định liên kết
Dự án nextcloud/documentation lưu trữ ba bộ tài liệu hướng dẫn (manuals). Để tham gia đóng góp, cộng tác viên cần làm việc trên đúng nhánh tương ứng: các nhánh ổn định (stable-branches) dành cho từng phiên bản phát hành cụ thể (ví dụ: 14.0 hoặc 15.0), trong khi nhánh master dành cho phiên bản mới nhất. Trường hợp nội dung chỉnh sửa liên quan đến nhiều phiên bản tài liệu, người đóng góp cần thực hiện quy trình backport tương ứng.
Một điểm đáng lưu ý trong quy định quản lý dự án là nguyên tắc ổn định liên kết tương tự như tính ổn định của API (API stability). Đội ngũ phát triển yêu cầu tuyệt đối không đổi tên hoặc di chuyển các trang tài liệu sau khi đã tạo, bởi có rất nhiều nguồn bên ngoài và máy tìm kiếm đang liên kết trực tiếp đến các đường dẫn này. Việc đổi tên hoặc di chuyển trang chỉ được phép trong những trường hợp ngoại lệ và bắt buộc phải đi kèm thiết lập chuyển hướng (redirect).
Về quy chuẩn định dạng văn bản:
- Các tập tin nguồn được viết bằng cú pháp reStructuredText (.rst) thông qua bộ tạo tài liệu Sphinx Documentation Generator.
- Chiều dài mỗi dòng văn bản được ngắt ở mức tối đa 120 ký tự (trừ các trường hợp đặc biệt như URL dài, mã ví dụ hoặc ô trong bảng).
- Tập tin
configuration_server/config_sample_php_parameters.rstlà tệp tự động tạo từ tập tin gốcconfig.sample.phpthuộc kho mã nguồnnextcloud/server. Mọi thay đổi đối với thông số cấu hình này phải được thực hiện trực tiếp tại khonextcloud/server.
Môi trường phát triển và bộ công cụ xây dựng Sphinx
Người đóng góp có thể thực hiện chỉnh sửa trực tiếp các tệp .rst trên giao diện GitHub đối với các lỗi nhỏ. Tuy nhiên, đối với các thay đổi lớn, dự án khuyến nghị thiết lập môi trường phát triển cục bộ với đầy đủ công cụ Sphinx để biên dịch và kiểm tra lỗi trước khi gửi Pull Request (PR).
Hệ sinh thái công cụ hỗ trợ người viết tài liệu bao gồm:
- Documatt Snippets: Công cụ chỉnh sửa trực tuyến giúp người mới làm quen với cú pháp reStructuredText và Sphinx, cung cấp khả năng xem trước (preview) chính xác hơn so với trình xem trước mặc định của GitHub.
- sphinx-autobuild: Gói mở rộng cài đặt qua
pipgiúp tự động theo dõi các thay đổi của tệp và tải lại giao diện xem trước HTML. Người dùng có thể kích hoạt môi trường bằng lệnhpipenv shell. - DevContainer và GitHub Codespaces: Repository tích hợp sẵn cấu hình VSCode DevContainer đầy đủ tính năng. Người phát triển có thể dùng các câu lệnh
make(xây dựng toàn bộ tài liệu),make html(xây dựng bản HTML) hoặcmake pdf(xây dựng bản PDF). Khi kết hợp lệnhmake SPHINXBUILD=sphinx-autobuild htmlvới tính năng chuyển tiếp cổng (port forwarding), người dùng có thể tự động làm mới trang xem trước HTML.
Do các công cụ biên dịch PDF mang lại số lượng phụ thuộc (dependencies) rất lớn từ LaTeX và các bộ công cụ liên quan, dự án khuyến cáo người dùng không nên cài đặt thủ công các công cụ này trực tiếp trên máy cục bộ mà nên tận dụng DevContainer hoặc GitHub Codespaces.
Quy trình đóng góp, xác thực DCO và công tác dịch thuật
Để đóng góp nội dung, thành viên cần có tài khoản GitHub, tiến hành fork kho lưu trữ, tạo nhánh mới từ master hoặc nhánh stable tương ứng, sau đó gửi Pull Request. Dự án áp dụng quy định bắt buộc về việc ký xác nhận commit (sign-off commits) nhằm tuân thủ Chứng nhận Nguồn gốc Nhà phát triển (Developer Certificate of Origin – DCO).
Mỗi thông điệp commit phải chứa tên và địa chỉ email của người đóng góp. Khung làm việc yêu cầu địa chỉ email trong cấu hình Git phải trùng khớp hoàn toàn với email trên tài khoản GitHub (bao gồm cả địa chỉ email ẩn danh dạng github.username@users.noreply.github.com).
Bên cạnh việc soạn thảo nội dung bằng tiếng Anh, repository cũng cung cấp tài liệu hướng dẫn riêng dành cho các nhà phát triển muốn hỗ trợ và đơn giản hóa quy trình dịch thuật đa ngôn ngữ cho hệ thống tài liệu Nextcloud.
Những khía cạnh chưa được chi tiết hóa trong tài liệu nguồn
Dù tài liệu cung cấp cái nhìn chi tiết về quy chuẩn kỹ thuật và quy trình đóng góp, một số thông tin cụ thể vẫn chưa được đề cập rõ trong phần văn bản nguồn thu thập được, bao gồm:
- Tên gọi cụ thể và nội dung chi tiết của từng bộ sổ tay trong số ba bộ tài liệu hướng dẫn (three manuals) mà repository này lưu trữ.
- Danh sách chi tiết các ứng dụng máy khách (client apps) và quy tắc phân nhánh riêng cho từng ứng dụng đó.
- Thông tin chi tiết về nền tảng dịch thuật bên thứ ba hoặc công cụ tự động hóa được tích hợp cho các dịch giả.
Nguồn tham khảo: Xem bài gốc
