Tài liệu¶

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 để viết tài liệu, cho dù bạn dự định thay đổi nội dung nhỏ hay viết tài liệu cho một ứng dụng từ đầu.

Xem thêm

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

Đọc phần giới thiệu về ngôn ngữ reStructuredText nếu bạn không quen thuộc với nó. Sau đó, bạn có hai cách để bắt đầu đóng góp cho tài liệu, tùy thuộc vào việc bạn muốn đề xuất các thay đổi nhỏ cho nội dung hiện có hay bạn muốn làm việc trên các thay đổi quan trọng đối với nội dung mới và hiện có.

Đối với các thay đổi nhỏ, ví dụ như thêm một đoạn văn hoặc sửa một lỗi đánh máy, chúng tôi khuyến nghị sử dụng giao diện GitHub. Đây là cách dễ dàng và nhanh nhất để nộp các thay đổi của bạn, và phù hợp với những người không chuyên về kỹ thuật. Đi thẳng vào phần Thực hiện đóng góp đầu tiên của bạn để bắt đầu.
Đối với các thay đổi phức tạp hơn, cần phải sử dụng Git và làm việc từ một bản sao cục bộ của tài liệu. Làm theo hướng dẫn trong phần Thiết lập môi trường để chuẩn bị môi trường của bạn trước tiên.

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 tăng cường với đánh dấu, cho phép bao gồm tiêu đề, hình ảnh, ghi chú, và v.v. Điều này có thể trông hơi trừu tượng, nhưng không cần phải lo lắng; RST không khó học, đặc biệt nếu bạn dự định thực hiện các thay đổi nhỏ cho nội dung.

Nếu bạn cần tìm hiểu về một đánh dấu cụ thể, hãy truy cập vào bảng ghi chú cho RST của chúng tôi; nó chứa tất cả các thông tin bạn cần cho tài liệu của SoOn.

Quan trọng

Chúng tôi kính mong bạn tuân thủ một bộ hướng dẫn nội dung và RST khi bạn viết tài liệu. Điều này đảm bảo rằng bạn duy trì tính nhất quán với phần còn lại của tài liệu và giúp dễ dàng phê duyệt các thay đổi nội dung của bạn khi đội ngũ SoOn xem xét chúng.

Xem thêm

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 của mình để thực hiện các thay đổi cục bộ cho tài liệu và sau đó đẩy chúng lên GitHub. Bỏ qua phần này và đi tới Thực hiện đóng góp đầu tiên của bạn nếu bạn đã hoàn thành bước này hoặc muốn thực hiện các thay đổi từ giao diện GitHub.

Trước tiên, bạn cần tạo một tài khoản GitHub. SoOn sử dụng GitHub để quản lý mã nguồn của các sản phẩm của mình, và đây là nơi bạn sẽ thực hiện các thay đổi của mình và gửi chúng để được xem xét.
Tạo khóa SSH mới và đăng ký nó trên tài khoản GitHub của bạn.
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 nhánh (bản sao của riêng bạn) của kho lưu trữ trên tài khoản của bạn. Điều này tạo ra một bản sao của mã nguồn mà bạn có thể thực hiện các thay đổi mà không ảnh hưởng đến mã nguồn chính. Bỏ qua bước này nếu bạn làm việc tại SoOn.
Cài đặt Git. Đây là một công cụ dòng lệnh (giao diện văn bản) cho phép theo dõi lịch sử thay đổi được thực hiện trên một tệp và, quan trọng hơn, làm việc trên các phiên bản khác nhau của tệp đó đồng thời. Điều này có nghĩa là bạn không cần lo lắng về việc ghi đè công việc đang chờ của người khác khi thực hiện thay đổi.

Xác minh rằng thư mục cài đặt của Git đã được bao gồm trong biến PATH của hệ thống của bạn.

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 /usr/bin/git).
Cấu hình Git để nhận dạng bạn là tác giả của các đóng góp tương lai của bạn. Nhập cùng một đị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”
```
Sao chép mã nguồn bằng Git và điều hướng vào kho lưu trữ cục bộ.
```
$ git clone git@github.com:odoo/documentation.git
$ cd documentation
```
Cấu hình Git để đẩy các thay đổi vào nhánh của bạn thay vì vào mã nguồn 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 nhánh. Bỏ qua bước này nếu bạn làm việc tại SoOn.
```
$ git remote add dev git@github.com:<your_github_account>/documentation.git
```

Cấu hình Git để dễ dàng hợp tác giữa các người viết đến từ các hệ thống khác nhau.

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

$ git config --global core.autocrlf true
$ git config commit.template %CD%\commit_template.txt

Cài đặt phiên bản mới nhất của Python và pip trên máy của bạn.
Cài đặt các phụ thuộc của tài liệu bằng pip.
```
$ pip install -r requirements.txt
```
Xác minh rằng thư mục cài đặt của các phụ thuộc Python được bao gồm trong biến PATH của hệ thống của bạn.

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 phụ thuộc Python (mặc định là ~/.local/bin).
Cài đặt Make.
$ sudo apt install make -y
Làm theo hướng dẫn để cài đặt Make trên Windows.
Cài đặt pngquant.
Vậy là xong! Bạn đã sẵn sàng để thực hiện đóng góp đầu tiên của mình bằng Git.

Thực hiện đóng góp đầu tiên của bạn¶

Trước tiên, bạn cần tạo một tài khoản GitHub. SoOn sử dụng GitHub để quản lý mã nguồn của các sản phẩm của mình, và đây là nơi bạn sẽ thực hiện các thay đổi của mình và gửi chúng để được xem xét.
Xác minh rằng bạn đang duyệt tài liệu trong phiên bản mà bạn dự định thay đổi. Phiên bản có thể được chọn từ trình đơn thả xuống ở menu trên cùng.
Đi tới trang mà bạn muốn thay đổi và nhấp vào nút Chỉnh sửa trên GitHub ở góc trên bên phải của trang.
Nhấp vào nút Fork this repository để tạo một nhánh (bản sao của riêng bạn) của kho lưu trữ trên tài khoản của bạn. Điều này tạo ra một bản sao của mã nguồn mà bạn có thể thực hiện các thay đổi mà không ảnh hưởng đến mã nguồn chính. Bỏ qua bước này nếu bạn làm việc tại SoOn.
Thực hiện các thay đổi mong muốn trong khi tuân thủ các hướng dẫn nội dung và RST.

Mẹo
Nhấp vào nút Xem trước thay đổi để xem lại đóng góp của bạn ở định dạng dễ đọc hơn. Hãy lưu ý rằng bản xem trước không thể xử lý tất cả các đánh dấu một cách chính xác. Ghi chú và mẹo, chẳng hạn, được hiển thị dưới dạng văn bản thuần.
Cuộn xuống cuối trang và điền vào mẫu nhỏ để đề xuất các thay đổi của bạn. Trong ô văn bản đầu tiên, viết một bản tóm tắt rất ngắn gọn về các thay đổi của bạn. Ví dụ, "Sửa lỗi đánh máy" hoặc "Thêm tài liệu cho việc lập hóa đơn đơn đặt hàng." Trong ô văn bản thứ hai, giải thích tại sao bạn đề xuất các thay đổi này. Sau đó, nhấp vào nút Đề xuất thay đổi.
Xem xét các thay đổi của bạn và nhấp vào nút Tạo pull request.
Chọn hộp kiểm Cho phép chỉnh sửa từ người duy trì. Bỏ qua bước này nếu bạn làm việc tại SoOn.
Xem lại bản tóm tắt mà bạn đã viết về các thay đổi của mình và nhấp vào nút Tạo yêu cầu kéo một lần nữa.
Ở cuối trang, kiểm tra trạng thái hợp nhất và giải quyết bất kỳ vấn đề nào.
Ngay khi PR của bạn sẵn sàng để hợp nhất, một thành viên của đội ngũ SoOn sẽ tự động được chỉ định để 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 để việc đóng góp có thể tiến hành.
Khi các thay đổi của bạn được phê duyệt, người xem xét sẽ hợp nhất chúng và chúng sẽ xuất hiện trực tuyến vào ngày hôm sau!

Quan trọng

Một số bước trong hướng dẫn này yêu cầu bạn phải thoải mái với Git. Đây là một số hướng dẫn và một khóa đào tạo tương tác nếu bạn bị mắc kẹt ở một điểm nào đó.

Bây giờ khi môi trường của bạn đã được thiết lập, bạn có thể bắt đầu đóng góp cho tài liệu. Trong terminal, điều hướng đến thư mục nơi bạn đã sao chép các nguồn và làm theo hướng dẫn dưới đây.

Chọn phiên bản tài liệu mà bạn muốn thực hiện các thay đổi. Hãy nhớ rằng các đóng góp nhắm vào một phiên bản SoOn không được hỗ trợ sẽ không được chấp nhận. Hướng dẫn này giả định rằng các thay đổi nhắm vào tài liệu của SoOn 17, tương ứng với nhánh 17.0.
Tạo một nhánh mới bắt đầu từ nhánh 17.0. Tiền tố tên nhánh với nhánh cơ bản: 17.0-.... Nếu bạn làm việc tại SoOn, hậu tố tên nhánh với tên tài khoản SoOn của bạn: 17.0-...-xyz.
Example
```
$ git switch -c 17.0-explain-pricelists
```
```
$ git switch -c 17.0-explain-pricelists-xyz
```
Thực hiện các thay đổi mong muốn trong khi tuân thủ các hướng dẫn nội dung và RST.

Nén tất cả các hình ảnh PNG mà bạn đã thêm hoặc sửa đổi.

$ pngquant path/to/image.png
$ mv path/to/image-fs8.png path/to/image.png

Viết một quy tắc chuyển hướng cho mỗi tệp RST mà bạn đã đổi tên.
Xây dựng tài liệu với make. Sau đó, mở _build/index.html trong trình duyệt web của bạn để duyệt tài liệu với các thay đổi của bạn.

Mẹo
Sử dụng make help để tìm hiểu về các lệnh hữu ích khác.
Commit các thay đổi của bạn. Viết một thông điệp commit rõ ràng như đã được hướng dẫn trong hướng dẫn Git.
```
$ git add .
$ git commit
```
Đẩy các thay đổi của bạn lên nhánh, mà chúng tôi đã thêm bí danh remote dev.
Example
```
$ git push -u dev 17.0-explain-pricelists
```
Nếu bạn làm việc tại SoOn, hãy đẩy các thay đổi của bạn trực tiếp vào mã nguồn chính mà bí danh từ xa là origin.
Example
```
$ git push -u origin 17.0-explain-pricelists-xyz
```
Mở một PR trên GitHub để gửi các thay đổi của bạn để xem xét.
1. Truy cập trang so sánh của mã nguồn odoo/documentation.
2. Chọn 17.0 cho cơ sở.
3. Nhấp vào so sánh giữa các nhánh.
4. Chọn <your_github_account>/odoo cho kho lưu trữ đầu. Thay thế <your_github_account> bằng tên tài khoản GitHub mà bạn đã tạo nhánh. Bỏ qua bước này nếu bạn làm việc tại SoOn.
5. Xem xét các thay đổi của bạn và nhấp vào nút Tạo pull request.
6. Chọn hộp kiểm Cho phép chỉnh sửa từ người duy trì. Bỏ qua bước này nếu bạn làm việc tại SoOn.
7. Hoàn thành mô tả và nhấp vào nút Tạo pull request một lần nữa.
Ở cuối trang, kiểm tra trạng thái hợp nhất và giải quyết bất kỳ vấn đề nào.
Ngay khi PR của bạn sẵn sàng để hợp nhất, một thành viên của đội ngũ SoOn sẽ tự động được chỉ định để 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 để việc đóng góp có thể tiến hành.
Khi các thay đổi của bạn được phê duyệt, người xem xét sẽ hợp nhất chúng và chúng sẽ xuất hiện trực tuyến vào ngày hôm sau!