19.6. Đóng góp cho Quyển sách

Những đóng góp từ cộng đồng giúp chúng tôi cải thiện cuốn sách này. Nếu bạn tìm thấy có lỗi đánh máy, đường dẫn hết hạn, hay phần nào đó mà bạn nghĩ chúng tôi thiếu trích dẫn, phần mã nguồn không được thanh thoát hay có chỗ giải thích không rõ ràng, xin vui lòng đóng góp và giúp chúng tôi hỗ trợ những độc giả khác. Trong khi với các quyển sách bình thường, khoảng cách giữa những lần xuất bản (đó là giữa các lần sửa lỗi đánh máy) có thể tính bằng năm, thì giờ đây chúng tôi chỉ cần vài giờ đến vài ngày để đưa một cải thiện vào bản dịch này. Để có thể đóng góp trực tiếp, bạn cần đăng một pull request lên GitHub của bản dịch này. Khi pull request của bạn được nhóm dịch gộp (merge) vào repo, bạn sẽ trở thành một người đóng góp (contributor). Một cách khác để bạn có thể đóng góp đơn giản hơn là tạo một issues mới và báo cáo vấn đề bạn tìm thấy, tạo một thảo luận mới để cùng trao đổi nhiều vấn đề hơn với nhóm dịch thuật.

19.6.1. Thay đổi nhỏ trong Văn bản

Đóng góp phổ biến nhất là chỉnh sửa một câu hoặc chữa lỗi đánh máy. Chúng tôi khuyến nghị bạn nên tìm tệp gốc trên github và trực tiếp chỉnh sửa tệp. Ví dụ, bạn có thể tìm tệp thông qua nút Find file (Fig. 19.6.1) để định vị tệp gốc, tệp ở đây là một tệp markdown. Sau đó bạn nhấn nút “Edit this file” ở góc trên bên phải để thay đổi tệp markdown này.

../_images/edit-file.png

Fig. 19.6.1 Chỉnh sửa tệp trên GitHub.

Sau khi hoàn thành, điền mô tả thay đổi của bạn vào ô “Propose file change” ở cuối trang và sau đó nhấn nút “Propose file change”. Trang sẽ được chuyển hướng đến một trang mới để bạn có thể kiểm tra lại thay đổi của bạn (Fig. 19.6.7). Nếu mọi thứ đều ổn, bạn có thể đăng một pull request bằng cách nhấn vào nút “Create pull request”.

19.6.2. Đề xuất một Thay đổi Lớn

Nếu bạn có dự định cập nhật một phần lớn văn bản hay mã nguồn thì bạn cần phải biết thêm một chút về định dạng mà cuốn sách này sử dụng. Tệp nguồn được dựa trên định dạng markdown với một tập các phần mở rộng thông qua gói d2lbook ví dụ như tham chiếu đến phương trình, hình ảnh, chương mục và trích dẫn. Bạn có thể sử dụng bất kỳ trình biên tập Markdown nào để mở các tệp này và thực hiện chỉnh sửa.

Nếu bạn muốn thay đổi mã nguồn, chúng tôi khuyến nghị các bạn sử dụng Jupyter để mở các tệp Markdown này như mô tả trong Section 19.1. Nhờ đó bạn có thể chạy và kiểm tra thay đổi của bạn. Xin vui lòng xóa toàn bộ các ô kết quả trước khi đăng thay đổi của bạn, hệ thống CI của chúng tôi sẽ thực thi phần bạn cập nhật để sinh kết quả.

Một số phần có thể hỗ trợ lập trình đa framework, bạn có thể sử dụng d2lbook để kích hoạt một framework cụ thể, khi đó phần lập trình các framework khác trở thành khối mã Markdown và sẽ không được thực thi khi bạn chạy“Run All” trong Jupyter. Nói cách khác, đầu tiên cài đặt d2lbook bằng cách chạy

pip install git+https://github.com/d2l-ai/d2l-book

Sau đó trong thư mục gốc d2l-en, bạn có thể kích hoạt một đoạn mã cụ thể bằng cách chạy một trong các lệnh sau:

d2lbook activate mxnet chapter_multilayer-perceptrons/mlp-scratch.md
d2lbook activate pytorch chapter_multilayer-perceptrons/mlp-scratch.md
d2lbook activate tensorflow chapter_multilayer-perceptrons/mlp-scratch.md

Trước khi đăng thay đổi của bạn lên, xin vui lòng xóa toàn bộ các ô kết quả và kích hoạt tất cả bằng

d2lbook activate all chapter_multilayer-perceptrons/mlp-scratch.md

Nếu bạn thêm một khối mã nguồn mới không có trong cách lập trình mặc định, tức MXNet, xin vui lòng sử dụng #@tab để đánh dấu khối này tại dòng đầu tiên. Ví dụ, #@tab pytorch cho khối mã PyTorch, #@tab tensorflow cho khối mã TensorFlow, hoặc #@tab all cho khối mã được dùng chung cho tất cả các cách lập trình. Bạn có thể tham khảo d2lbook để biết thêm thông tin.

19.6.3. Thêm một Phần Mới hoặc một Cách lập trình cho Framework Mới

Nếu bạn muốn tạo một chương mới, ví dụ như học tăng cường, hoặc thêm một cách lập trình cho một framework mới, ví dụ như TensorFlow, trước tiên xin vui lòng liên hệ với nhóm dịch, có thể bằng email hoặc sử dụng github issues.

19.6.4. Đăng một Thay đổi Lớn

Chúng tôi đề nghị bạn phải sử dụng quy trình git chuẩn để đăng một thay đổi lớn. Tóm lại, quy trình này hoạt động như mô tả trong Fig. 19.6.2.

../_images/contribute.svg

Fig. 19.6.2 Đóng góp cho quyển sách.

Chúng tôi sẽ hướng dẫn chi tiết từng bước. Nếu bạn quen thuộc với Git bạn có thể bỏ qua phần này. Để ngắn gọn chúng tôi giả sử người đóng góp có username là “astonzhang”.

19.6.4.1. Cài đặt Git

Cuốn sách mã nguồn mở của Git mô tả chi tiết cách cài đặt Git. Việc này có thể được thực hiện thông qua apt install git trên Ubuntu Linux, bằng cách cài đặt công cụ phát triển Xcode trên macOS, hoặc bằng cách sử dụng desktop client của GitHub. Nếu bạn không có tài khoản GitHub, bạn cần phải đăng ký một tài khoản.

19.6.4.2. Đăng nhập vào GitHub

Điền địa chỉ của repo chứa mã nguồn bản dịch cuốn sách này vào trình duyệt web của bạn. Chọn nút Fork trong khung đỏ ở phía trên bên phải của Fig. 19.6.3, để tạo một bản sao cho repo của cuốn sách này. Nó giờ đây là bản sao của bạn và bạn có thể tuỳ ý thay đổi nó.

../_images/git-fork.png

Fig. 19.6.3 Trang repo chứa mã nguồn.

Giờ thì repo chứa mã nguồn của cuốn sách đã được fork (tức sao chép) tới tên người dùng của bạn, ví dụ như astonzhang/d2l-en được chỉ ra phía trên bên trái của ảnh chụp màn hình Fig. 19.6.4.

../_images/git-forked.png

Fig. 19.6.4 Fork repo chứa mã nguồn.

19.6.4.3. Clone Repo

Để clone một repo (tức là tạo bản sao cục bộ) ta cần phải có địa chỉ của repo đó. Nút màu xanh trong Fig. 19.6.5 hiển thị địa chỉ này. Hãy đảm bảo rằng bản sao cục bộ của bạn cập nhật gần nhất với repo chính nếu bạn quyết định giữ bản fork này lâu dài. Còn bây giờ chỉ cần đơn giản làm theo các hướng dẫn trong Cài đặt để bắt đầu. Điểm khác biệt chính ở đây là bạn đang tải về bản fork của riêng bạn cho repo này.

../_images/git-clone.png

Fig. 19.6.5 Git clone.

# Replace your_github_username with your GitHub username
git clone https://github.com/your_github_username/d2l-vn.git

19.6.4.4. Chỉnh sửa Bản dịch và Đẩy lên

Giờ là lúc để chỉnh sửa bản dịch. Tốt nhất là chỉnh sửa các notebook trên Jupyter theo hướng dẫn trong Section 19.1. Tạo thay đổi và kiểm tra xem chúng ổn chưa. Giả sử bạn đã điều chỉnh một lỗi đánh máy trong tệp ~/d2l-vn/chapter_appendix_tools/how-to-contribute.md. Sau đó bạn có thể kiểm tra xem bạn đã sửa đổi những tệp nào.

Ở thời điểm này Git sẽ thông báo là tệp chapter_appendix_tools/how-to-contribute.md đã được sửa đổi.

mylaptop:d2l-vn me$ git status
On branch master
Your branch is up-to-date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   chapter_appendix_tools/how-to-contribute.md

Sau khi xác nhận đây là những sửa đổi bạn muốn, thực thi lệnh sau:

git add chapter_appendix_tools/how-to-contribute.md
git commit -m 'fix typo in git documentation'
git push

Đoạn mã được chỉnh sửa lúc này sẽ nằm trong bản fork cá nhân của bạn cho repo này. Để yêu cầu thay đổi thêm, bạn cần phải tạo một pull request đối với repo chính thức của bản dịch.

19.6.4.5. Pull Request

Như chỉ ra trong Fig. 19.6.6, đi tới bản fork của bạn trên GitHub và chọn “New pull request”. Thao tác này sẽ mở ra một cửa sổ hiển thị những điểm khác nhau giữa bản chỉnh sửa của bạn và bản hiện trong repo chính của cuốn sách.

../_images/git-newpr.png

Fig. 19.6.6 Pull Request.

19.6.4.6. Đăng Pull Request lên

Cuối cùng, đăng một pull request lên bằng cách nhấn vào nút như chỉ ra trong Fig. 19.6.7. Hãy đảm bảo mô tả các thay đổi bạn đã thực hiện trong pull request này. Việc này sẽ giúp nhóm dịch dễ dàng hơn trong việc kiểm tra và gộp vào bản dịch. Tuỳ thuộc vào các thay đổi, pull request này có thể được chấp thuận ngay lập tức, bác bỏ, hoặc khả năng cao hơn là bạn sẽ nhận được phản hồi trên các thay đổi này. Một khi bạn đã hợp nhất được chúng, chúc mừng bạn đã hoàn thành và hãy tiếp tục phát huy.

../_images/git-createpr.png

Fig. 19.6.7 Tạo Pull Request.

Pull request của bạn sẽ xuất hiện ở danh sách Pull requests trong repo chính. Chúng tôi sẽ làm mọi thứ có thể để xử lý nó nhanh chóng.

19.6.5. Tóm tắt

  • Bạn có thể sử dụng GitHub để đóng góp cho bản dịch này.
  • Bạn có thể chỉnh sửa tệp trực tiếp trên GitHub với những thay đổi nhỏ.
  • Với một thay đổi lớn, xin vui lòng tạo fork cho repo này, tạo chỉnh sửa cục bộ và chỉ đóng góp một khi bạn đã sẵn sàng.
  • Pull request là cách mà các đóng góp được gói lại. Cố gắng đừng đăng một pull request quá lớn do điều này khiến chúng khó hiểu và khó để hợp nhất. Tốt hơn là gửi nhiều pull request nhỏ.

19.6.6. Bài tập

  1. Star và tạo fork của repo d2l-vn.
  2. Tìm đoạn mã nào đó cần cải thiện và đăng một pull request.
  3. Tìm một trích dẫn mà chúng tôi bỏ sót và đăng một pull request.
  4. Thường thì trong thực hành, tốt hơn hết là khi tạo một pull request thì sử dụng một nhánh (branch) mới. Hãy học cách thực hiện việc này với Git branching.

19.6.7. Thảo luận

19.6.8. Những người thực hiện

Bản dịch trong trang này được thực hiện bởi:

  • Đoàn Võ Duy Thanh
  • Đỗ Trường Giang
  • Nguyễn Văn Cường
  • Nguyễn Mai Hoàng Long