Tài liệu

• Nguyên tắc nội dung
• Hướng dẫn và bảng tra cứu nhanh RST

Hướng dẫn giới thiệu này sẽ giúp bạn có được các công cụ và kiến thức cần thiết để đóng góp vào tài liệu.

Đọc phần giới thiệu về ngôn ngữ reStructuredText nếu bạn chưa quen với nó. Sau đó, có hai hướng để bắt đầu đóng góp vào tài liệu:

• Đối với các thay đổi nhỏ, chẳng hạn như thêm một đoạn văn hoặc sửa lỗi chính tả, chúng tôi khuyến nghị sử dụng giao diện GitHub. Đây là cách dễ dàng và nhanh chóng nhất để gửi thay đổi, phù hợp với những người không am hiểu kỹ thuật. Chuyển thẳng đến phần Đóng góp vào tài liệu để bắt đầu.

• Đối với các thay đổi phức tạp hơn, chẳng hạn như thêm một trang mới, bạn cần sử dụng Git và làm việc từ một bản sao cục bộ của tài liệu. Hãy làm theo hướng dẫn trong phần Thiết lập môi trường trước để chuẩn bị môi trường của bạn.

Xem thêm

Khám phá các cách khác để đóng góp cho Odoo

reStructuredText (RST)

Tài liệu được viết bằng reStructuredText (RST), một ngôn ngữ đánh dấu nhẹ bao gồm văn bản thông thường được bổ sung thêm các đánh dấu, cho phép chèn tiêu đề, hình ảnh, ghi chú, v.v. RST rất dễ sử dụng, ngay cả khi bạn chưa quen với nó.

Quan trọng

Hãy lưu ý các nguyên tắc về nội dung và RST của chúng tôi khi viết tài liệu. Điều này đảm bảo tài liệu luôn nhất quán và giúp việc phê duyệt thay đổi của đội ngũ Odoo trở nên dễ dàng hơn.

Thiết lập môi trường

Các hướng dẫn dưới đây giúp bạn chuẩn bị môi trường để thực hiện các thay đổi cục bộ đối với tài liệu và sau đó push chúng lên GitHub. Bỏ qua phần này và chuyển đến Đóng góp vào tài liệu nếu bạn đã hoàn thành bước này hoặc muốn thực hiện thay đổi từ giao diện GitHub.

1. Đầu tiên, tạo một tài khoản GitHub. Odoo sử dụng GitHub để quản lý mã nguồn các sản phẩm của mình, và đây cũng là nơi bạn sẽ gửi các thay đổi của mình.

2. Tạo một khóa SSH mới và đăng ký nó vào tài khoản GitHub của bạn.

3. Truy cập github.com/odoo/documentation và nhấp vào nút Fork ở góc trên bên phải để tạo một fork (your own copy) của repository vào tài khoản của bạn. Điều này tạo ra một bản sao của codebase mà bạn có thể thực hiện thay đổi mà không ảnh hưởng đến codebase chính. Bỏ qua bước này nếu bạn làm việc tại Odoo.

4. Cài đặt Git. Đây là một công cụ dòng lệnh (a text interface) cho phép theo dõi lịch sử các thay đổi được thực hiện đối với một tệp và, quan trọng hơn, làm việc trên nhiều phiên bản khác nhau của tệp đó cùng một lúc. Điều này có nghĩa là bạn không cần phải lo lắng về việc ghi đè lên công việc đang chờ xử lý của người khác khi thực hiện thay đổi.

   Kiểm tra rằng thư mục cài đặt của Git đã được thêm vào biến PATH của hệ thống.

   Linux and macOSWindows

   Làm theo hướng dẫn cập nhật biến PATH trên Linux và macOS với đường dẫn cài đặt của Git (mặc định là /usr/bin/git).

5. Cấu hình Git để xác định bạn là tác giả của những đóng góp trong tương lai. Nhập cùng địa chỉ email mà bạn đã sử dụng để đăng ký trên GitHub.

   $ git config --global user.name "Your Name"
   $ git config --global user.email "youremail@example.com"
   

6. Clone mã nguồn bằng Git và di chuyển vào repository cục bộ.

   $ git clone git@github.com:odoo/documentation.git
   $ cd documentation
   

7. Cấu hình Git để push các thay đổi lên fork của bạn thay vì lên codebase chính. Trong các lệnh dưới đây, thay thế <your_github_account> bằng tên tài khoản GitHub mà bạn đã tạo fork. Bỏ qua bước này nếu bạn làm việc tại Odoo.

   $ git remote add dev git@github.com:<your_github_account>/documentation.git
   

8. Cấu hình Git để tạo điều kiện thuận lợi cho việc cộng tác giữa những người viết đến từ các hệ thống khác nhau.

   Linux and macOSWindows

   $ git config --global core.autocrlf input
   $ git config commit.template `pwd`/commit_template.txt
   

9. Cài đặt phiên bản mới nhất của Python và pip.

10. Cài đặt các Python dependency của tài liệu bằng pip.

    $ pip install -r requirements.txt
    

    Kiểm tra rằng thư mục cài đặt của các Python dependency đã được thêm vào biến PATH của hệ thống.

    Linux and macOSWindows

    Làm theo hướng dẫn cập nhật biến PATH trên Linux và macOS với đường dẫn cài đặt của các Python dependency (mặc định là ~/.local/bin).

11. Cài đặt Make.

    LinuxmacOSWindows

    $ sudo apt install make -y
    

12. Cài đặt pngquant.

13. Giờ đây bạn đã sẵn sàng để thực hiện đóng góp đầu tiên của mình với Git.

Đóng góp vào tài liệu

Contribute from the GitHub interfaceContribute with Git

1. Đầu tiên, tạo một tài khoản GitHub. Odoo sử dụng GitHub để quản lý mã nguồn các sản phẩm của mình, và đây cũng là nơi bạn sẽ gửi các thay đổi của mình.

2. Kiểm tra rằng bạn đang xem tài liệu ở phiên bản mà bạn muốn thay đổi. Phiên bản có thể được chọn từ danh sách thả xuống ở menu trên cùng.

3. Truy cập trang mà bạn muốn thay đổi và nhấp vào nút Edit on GitHub ở góc trên bên phải của trang.

4. Nhấp vào nút Fork this repository để tạo một fork (your own copy) của repository vào tài khoản của bạn. Điều này tạo ra một bản sao của codebase mà bạn có thể thực hiện thay đổi mà không ảnh hưởng đến codebase chính. Bỏ qua bước này nếu bạn làm việc tại Odoo.

   

5. Thực hiện các thay đổi mong muốn, đồng thời chú ý tuân theo các nguyên tắc về nội dung và RST.

   Mẹo

   Nhấp vào nút Preview changes để xem lại đóng góp của bạn ở định dạng dễ đọc hơn. Lưu ý rằng bản xem trước không thể xử lý chính xác tất cả các đánh dấu. Ví dụ, các ghi chú và mẹo sẽ được hiển thị dưới dạng văn bản thuần túy.

6. Cuộn xuống cuối trang và điền vào biểu mẫu nhỏ để đề xuất thay đổi của bạn. Trong ô văn bản đầu tiên, hãy viết một tóm tắt rất ngắn gọn về các thay đổi của bạn. Ví dụ: "Fix a typo" hoặc "Add documentation for invoicing of sales orders." Trong ô văn bản thứ hai, hãy giải thích lý do bạn đề xuất những thay đổi này. Sau đó, nhấp vào nút Propose changes.

   

7. Xem lại các thay đổi của bạn và nhấp vào nút Create pull request.

8. Đánh dấu vào ô Allow edits from maintainer. Bỏ qua bước này nếu bạn làm việc tại Odoo.

9. Xem lại phần tóm tắt mà bạn đã viết về các thay đổi của mình và nhấp lại vào nút Create pull request.

10. Ở cuối trang, kiểm tra trạng thái khả năng merge và xử lý mọi vấn đề phát sinh.

11. Ngay khi PR của bạn sẵn sàng để merge, một thành viên của đội ngũ Odoo sẽ tự động được phân công để xem xét. Nếu người xem xét có câu hỏi hoặc nhận xét, họ sẽ đăng chúng dưới dạng bình luận và bạn sẽ được thông báo qua email. Những bình luận đó phải được giải quyết thì đóng góp mới có thể tiếp tục.

12. Sau khi các thay đổi của bạn được phê duyệt, người xem xét sẽ merge chúng và chúng sẽ xuất hiện trực tuyến vào ngày hôm sau.