Bỏ qua

Thêm tài liệu

Có thể bạn đang sở hữu phần mềm tốt nhất trên thế giới – nhưng nếu không ai biết cách sử dụng nó, thì có ý nghĩa gì? Tài liệu hướng dẫn luôn có thể được cải thiện – và chúng tôi cần sự giúp đỡ của bạn!

Mẫu đơn

Tài liệu của BeeWare Docs Tools được viết bằng MkDocs và Markdown. Chúng tôi hướng đến việc tuân theo khung Diataxis để tổ chức cấu trúc tài liệu.

Khung Diataxis mô tả bốn "hình thức" tài liệu:

  • Hướng dẫn - Một trải nghiệm học tập có hướng dẫn, với mục tiêu cụ thể là hoàn thành một dự án.
  • Hướng dẫn thực hiện - Những hướng dẫn giúp người đọc đạt được một mục tiêu hoặc kết quả cụ thể.
  • Hướng dẫn chủ đề - Một bài phân tích về một ý tưởng cụ thể, được trình bày sao cho các khái niệm cơ bản trở nên rõ ràng.
  • Tham khảo - Mô tả kỹ thuật về các API cụ thể hoặc các giao diện khác.

Trước khi bắt đầu đóng góp tài liệu, điều quan trọng là phải xác định hình thức nào là phù hợp nhất. Nhiều đề xuất tài liệu ban đầu thường được mô tả là yêu cầu về “một hướng dẫn về X” – nhưng trong hầu hết các trường hợp, điều thực sự cần thiết lại là hướng dẫn thực hành, hướng dẫn chuyên đề hoặc thông tin tham khảo được cải thiện.

Ví dụ, hãy xem xét nhiệm vụ viết tài liệu hướng dẫn làm bánh quy.

Hướng dẫn

Hướng dẫn là một bài giới thiệu, đặc biệt là dành cho người mới bắt đầu, với mục tiêu đưa người đọc từ điểm xuất phát ban đầu đến sản phẩm hoàn chỉnh. Loại tài liệu này đòi hỏi các hướng dẫn rất cụ thể và những lời giải thích chi tiết giúp người đọc hiểu rõ bối cảnh của từng bước trong hướng dẫn. Bạn không nên giả định bất kỳ điều gì về kinh nghiệm của người đọc với công cụ đang được giải thích, mặc dù có thể giả định rằng họ có một số kiến thức cơ bản về Python.

Hướng dẫn nên bao gồm các điểm kiểm tra định kỳ để người đọc có thể xác nhận rằng họ đã thực hiện thành công các bước được mô tả. Tại mỗi điểm kiểm tra, các tiêu chí đánh giá thành công cần được nêu rõ. Các trường hợp thất bại đã biết cần được trình bày rõ ràng, bao gồm giải thích về bất kỳ lỗi hoặc vấn đề nào mà người đọc có thể gặp phải. Những thay đổi phát sinh từ các thao tác mà người đọc đã thực hiện cần được chỉ ra, ngay cả khi chúng có vẻ hiển nhiên. Việc lặp lại được khuyến khích, đặc biệt nếu bạn đang cố gắng thiết lập một phương pháp hay nhất hoặc các quy trình chung. Nên tránh giải thích về các chi tiết bên trong, cũng như các con đường thay thế dẫn đến cùng một kết quả.

Một hướng dẫn làm bánh quy không chỉ đơn thuần là một công thức. Các hướng dẫn trong bài hướng dẫn cần phải dễ hiểu đối với những người chưa từng làm bánh trước đây (chẳng hạn như trẻ em), đồng thời cần giải thích những điều mà người làm bánh có kinh nghiệm thường coi là hiển nhiên, chẳng hạn như cách đánh bông đường và bơ, quy trình làm nóng lò nướng trước, hoặc thời gian cần để bánh nguội trước khi ăn. Mục tiêu của hướng dẫn không phải là tạo ra một chiếc bánh quy - mà là truyền đạt những kiến thức cơ bản về làm bánh. Chiếc bánh quy thành phẩm chính là món ăn ngon miệng thuyết phục người ta bắt đầu thực hiện hướng dẫn ngay từ đầu.

Hướng dẫn thực hiện

Một hướng dẫn thực hành nên tập trung vào một trường hợp sử dụng cụ thể trong thực tế và các kết quả thực tiễn, thay vì các giải thích lý thuyết. Khác với một bài hướng dẫn, bạn có thể giả định rằng người đọc đã có một số kiến thức cơ bản về các công cụ hiện có. Người đọc nên có thể làm theo hướng dẫn từ đầu đến cuối và đạt được mục tiêu, nhưng họ có thể cần một số kiến thức sẵn có để thực hiện điều đó. Hướng dẫn này nên bao gồm một bộ hướng dẫn cụ thể hoặc các bước logic cần tuân theo để đạt được mục tiêu của hướng dẫn.

Một công thức trong sách nấu ăn là một ví dụ điển hình về hướng dẫn thực hành. Có rất nhiều công thức làm bánh quy sô-cô-la, và chúng đều có những điểm chung, nhưng bất kỳ công thức cụ thể nào cũng phải có thể thực hiện từ đầu đến cuối và cho ra kết quả nhất quán. Một công thức làm bánh quy sô-cô-la tốt sẽ không đi sâu vào việc so sánh ưu nhược điểm của các loại đường hay bột khác nhau, cũng không cung cấp hướng dẫn chi tiết về kỹ thuật hay quy trình cơ bản; nó chỉ bao gồm nguyên liệu và hướng dẫn để nướng một mẻ bánh quy, giả định rằng người đọc đã có kiến thức cơ bản về nướng bánh.

Hướng dẫn chủ đề

Hướng dẫn chủ đề mô tả một chủ đề hoặc ý tưởng cụ thể. Nó có thể bao gồm mã ví dụ hoặc hướng dẫn, nhưng chủ yếu tập trung vào việc cung cấp cái nhìn tổng quan về một khái niệm chung. Nó có thể bao gồm các ý kiến và góc nhìn khác nhau, nhưng vẫn phải duy trì trọng tâm vào chủ đề cụ thể của hướng dẫn.

Một hướng dẫn chuyên đề về làm bánh quy có thể đi sâu vào lịch sử của bánh quy như một loại thực phẩm nướng, phân tích cách thức mà các quy trình công nghiệp hóa tạo ra những loại bánh quy khác biệt so với bánh quy tự làm tại nhà, hoặc gợi ý các cách để kết hợp bánh quy vào chế độ ăn uống cân bằng. Bản thân tài liệu này sẽ không phải là một hướng dẫn thực hành hữu ích nếu bạn muốn làm bánh quy, nhưng nó có thể cung cấp những kiến thức nền tảng giúp những người đã quen với việc làm bánh có thể tùy chỉnh thành công một công thức bánh quy sẵn có.

Tham khảo

Tài liệu tham khảo tập trung vào thông tin, mô tả các chi tiết cụ thể về cách thức hoạt động của một thư viện công cụ. Loại tài liệu này thường có thể được tạo ra trực tiếp từ mã nguồn, nhưng để có một tài liệu API chất lượng, có thể cần phải bổ sung thêm các giải thích và bối cảnh. Mặc dù đôi khi tài liệu này có thể bao gồm các ví dụ về cách sử dụng, nhưng nên tránh đưa ra các giải thích chi tiết.

Một cẩm nang tham khảo về làm bánh có thể mô tả các loại đường có thể sử dụng và nêu chi tiết các đặc tính của chúng khi dùng trong làm bánh. Tài liệu này sẽ trình bày các thông tin thực tế về đường, nhưng một bài phân tích sâu hơn về việc lựa chọn giữa các loại đường nên được đề cập trong một hướng dẫn thực hành hoặc cẩm nang chuyên đề. Thông tin dinh dưỡng được in trên hầu hết các sản phẩm thực phẩm đóng gói sẽ được coi là tài liệu tham khảo.

Phong cách tài liệu

Tài liệu của BeeWare Docs Tools tuân thủ các hướng dẫn được nêu trong hướng dẫn phong cách tài liệu. Hướng dẫn này bao gồm các quy tắc cơ bản về phong cách và định dạng, cũng như quy trình kiểm tra chính tả. Ngoài ra, hướng dẫn này còn đề cập đến các chi tiết về cú pháp Markdown, chẳng hạn như cú pháp liên kết tham chiếu, các mẹo khi làm việc với khối mã và cách xử lý hình ảnh.

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

Đề xuất tài liệu mới

Đề xuất một tính năng mới

Vậy là bạn đã có ý tưởng về việc cải tiến cho BeeWare Docs Tools - làm thế nào để gửi ý tưởng đó để được xem xét?

Hãy tìm hiểu kỹ

Bước đầu tiên là tìm kiếm trên hệ thống theo dõi vấn đề BeeWare Docs Tools để xem liệu ý tưởng đó đã từng được đề xuất trước đây hay chưa, thông qua các vấn đề liên quan đến tính năng (các vấn đề được gắn thẻ "enhancement"), vấn đề liên quan đến tài liệu (các vấn đề được gắn thẻ "documentation"), hoặc các chuỗi thảo luận. Nếu đã có, và bạn có bối cảnh hoặc ý tưởng mới để bổ sung, hãy đưa chúng vào chuỗi thảo luận hiện có. Nếu bạn cần hỗ trợ trong quá trình tìm kiếm, bạn có thể hỏi trong kênh #dev trên BeeWare Discord. Chúng tôi có thể chỉ cho bạn các chuỗi thảo luận hiện có, cung cấp bối cảnh mà bạn có thể chưa biết, hoặc kết nối ý tưởng của bạn với một ý tưởng khác có thể không liên quan ngay lập tức.

Thảo luận về ý tưởng này

Nếu bạn không tìm thấy bất kỳ tài liệu tham khảo nào liên quan đến ý tưởng của mình, hãy tạo một Chủ đề thảo luận. Hãy mô tả tổng quan về mục đích và trường hợp sử dụng của ý tưởng. Hãy nêu rõ những suy nghĩ của bạn về hình thức của tính năng này nếu được triển khai, chẳng hạn như cấu trúc chung của API, giao diện trực quan của tính năng hoặc tài liệu sẽ được bổ sung. Nếu có thể, bạn cũng nên bao gồm bất kỳ nghiên cứu nào bạn đã thực hiện về cách ý tưởng của bạn sẽ được thể hiện trên các nền tảng khác nhau.

Sau khi chủ đề thảo luận được mở, nhóm BeeWare và các thành viên khác trong cộng đồng sẽ phản hồi. Nhóm nòng cốt sẽ cố gắng đưa ra ít nhất là đánh giá ban đầu về ý tưởng của bạn trong vòng hai ngày làm việc. Nếu ý tưởng đó đặc biệt phức tạp, việc phân tích chi tiết hơn có thể mất đến một tuần. Các sự kiện như ngày lễ và hội nghị có thể khiến thời gian xử lý kéo dài hơn một chút.

Đây là cơ hội để bạn tham gia trao đổi về ý tưởng của mình. Chúng tôi có thể yêu cầu bạn cung cấp thêm chi tiết hoặc bối cảnh. Các thành viên khác trong cộng đồng cũng có thể tham gia vào cuộc thảo luận, đưa ra những góc nhìn, đề xuất hoặc ý kiến phản biện khác. Kết quả của cuộc thảo luận này sẽ quyết định các bước tiếp theo.

Điều quan trọng là phải hiểu rằng không phải ý tưởng nào cũng được chấp nhận. Lý do tại sao quy trình này bắt đầu bằng một bản đề xuất là để tránh trường hợp bạn bỏ ra rất nhiều công sức, chỉ để rồi phát hiện ra rằng có lý do khiến đề xuất thay đổi của bạn không được chấp nhận.

Điều này không có nghĩa là đó không phải là một ý tưởng hay! Có thể có những lý do kỹ thuật khiến ý tưởng đó không thể thực hiện được. Ví dụ, chúng ta có thể từ chối một ý tưởng nếu:

  • Sẽ rất khó hoặc không thể triển khai một cách đáng tin cậy trên tất cả các nền tảng được hỗ trợ; hoặc
  • Việc bảo trì sẽ rất khó khăn, hoặc việc bảo trì sẽ đòi hỏi phải sử dụng công nghệ hoặc phần mềm mà không phải ai cũng có thể tiếp cận được; hoặc
  • Nó phục vụ một nhóm đối tượng nhỏ, nhưng lại gây ra gánh nặng đáng kể cho những người dùng khác.

Nếu chúng tôi nhận thấy ý tưởng của bạn không phù hợp, điều đó không có nghĩa là bạn phải từ bỏ nó. Mặc dù chúng tôi có thể từ chối một ý tưởng cụ thể, nhưng chúng tôi có thể sẵn lòng hơn nhiều trong việc bổ sung một giao diện plugin hoặc điểm mở rộng khác, giúp bạn duy trì tính năng đó dưới dạng một thư viện bên ngoài. Nhờ đó, bạn vẫn có thể sử dụng tính năng này mà không phải lo lắng về các vấn đề bảo trì cụ thể hay những hạn chế của tính năng đó trở thành rào cản đối với chính dự án.

Chuyển thành yêu cầu tính năng chính thức

Khi cuộc thảo luận đã đạt được sự đồng thuận về hình thức của một tính năng, bạn có thể tạo một yêu cầu tính năng mới trong hệ thống theo dõi vấn đề BeeWare Docs Tools, trong đó tóm tắt nội dung cuộc thảo luận và đính kèm liên kết đến cuộc thảo luận để cung cấp bối cảnh.

Bạn không cần phải tự mình triển khai đề xuất tính năng của mình; bạn có thể tạo một vấn đề (issue) kèm theo chi tiết về đề xuất của bạn. Tuy nhiên, việc chỉ đơn thuần đăng tải vấn đề đó không có nghĩa là nó sẽ được triển khai cho bạn. Bạn sẽ cần chờ đợi để xem liệu đề xuất đó có được ai đó quan tâm đến tính năng tương tự tiếp nhận hay không, dù đó là một thành viên khác trong cộng đồng hay đội ngũ phát triển chính; tuy nhiên, điều này không được đảm bảo sẽ xảy ra. Nếu bạn muốn đảm bảo tính năng được triển khai, bạn sẽ cần tự mình triển khai nó, hoặc trả tiền cho người khác để họ triển khai giúp bạn.

Nếu bạn quan tâm, bạn có thể bắt đầu triển khai tính năng mới của mình.

Thiết lập môi trường phát triển

Thiết lập môi trường phát triển

Để đóng góp cho BeeWare Docs Tools, bạn cần thiết lập một môi trường phát triển.

Điều kiện tiên quyết

Bạn cần cài đặt các phần mềm tiên quyết sau đây.

BeeWare Docs Tools yêu cầu Python 3.10+. Bạn cũng sẽ cần một công cụ để quản lý môi trường ảo (chẳng hạn như venv).

Bạn có thể kiểm tra phiên bản Python đã cài đặt bằng cách chạy lệnh sau:

$ python3 --version

Nếu bạn đã cài đặt nhiều phiên bản Python, bạn có thể cần thay thế python3 bằng số phiên bản cụ thể (ví dụ: python3.13)

Chúng tôi khuyên bạn nên tránh sử dụng các phiên bản Python mới ra mắt gần đây (tức là các phiên bản có số phiên bản phụ là ".0" hoặc ".1", ví dụ như 3.14.0). Lý do là các công cụ cần thiết để hỗ trợ Python trên macOS thường chậm cập nhật và thường chưa có sẵn cho các phiên bản Python ổn định mới ra mắt.

BeeWare Docs Tools yêu cầu Python 3.10+. Bạn cũng sẽ cần một công cụ để quản lý môi trường ảo (chẳng hạn như venv).

Bạn có thể kiểm tra phiên bản Python đã cài đặt bằng cách chạy lệnh sau:

$ python3 --version

Nếu bạn đã cài đặt nhiều phiên bản Python, bạn có thể cần thay thế python3 bằng số phiên bản cụ thể (ví dụ: python3.13)

Chúng tôi khuyên bạn nên tránh sử dụng các phiên bản Python mới được phát hành gần đây (tức là các phiên bản có số phiên bản phụ là ".0" hoặc ".1", ví dụ như 3.14.0). Lý do là các công cụ cần thiết để hỗ trợ Python trên Linux thường chậm cập nhật và thường chưa có sẵn cho các phiên bản Python ổn định mới được phát hành.

BeeWare Docs Tools yêu cầu Python 3.10+. Bạn cũng sẽ cần một công cụ để quản lý môi trường ảo (chẳng hạn như venv).

Bạn có thể kiểm tra phiên bản Python đã cài đặt bằng cách chạy lệnh sau:

C:\...>py -3 --version

Nếu bạn đã cài đặt nhiều phiên bản Python, bạn có thể cần thay thế -3 bằng số phiên bản cụ thể (ví dụ: -python3.13)

Chúng tôi khuyên bạn nên tránh sử dụng các phiên bản Python mới được phát hành gần đây (tức là các phiên bản có số phiên bản phụ là ".0" hoặc ".1", ví dụ như 3.14.0). Lý do là các công cụ cần thiết để hỗ trợ Python trên Windows thường chậm cập nhật và thường không có sẵn cho các phiên bản Python ổn định mới được phát hành.

Thiết lập môi trường phát triển

Cách được khuyến nghị để thiết lập môi trường phát triển cho BeeWare Docs Tools là sử dụng một môi trường ảo, sau đó cài đặt phiên bản phát triển của BeeWare Docs Tools cùng các phụ thuộc của nó.

Sao chép kho lưu trữ BeeWare Docs Tools

Tiếp theo, hãy truy cập trang BeeWare Docs Tools trên GitHub, và nếu bạn chưa làm, hãy sao chép kho lưu trữ vào tài khoản của bạn. Tiếp theo, nhấp vào nút "<> Code" trên bản sao của bạn. Nếu bạn đã cài đặt ứng dụng GitHub Desktop trên máy tính, bạn có thể chọn "Open with GitHub Desktop"; nếu không, hãy sao chép URL HTTPS được cung cấp và sử dụng nó để sao chép kho lưu trữ vào máy tính của bạn bằng dòng lệnh:

Sao chép kho lưu trữ BeeWare Docs Tools, sau đó:

$ git clone https://github.com/<tên người dùng của bạn>/beeware-docs-tools.git

(thay thế bằng tên người dùng GitHub của bạn)

Sao chép kho lưu trữ BeeWare Docs Tools, sau đó:

$ git clone https://github.com/<tên người dùng của bạn>/beeware-docs-tools.git

(thay thế bằng tên người dùng GitHub của bạn)

Sao chép kho lưu trữ BeeWare Docs Tools, sau đó:

C:\...>git clone https://github.com/<tên người dùng của bạn>/beeware-docs-tools.git

(thay thế bằng tên người dùng GitHub của bạn)

Thiết lập kho lưu trữ nguồn

Sau khi sao chép nhánh của bạn, hãy thêm kho lưu trữ BeeWare làm kho lưu trữ từ xa upstream. Điều này giúp bản sao cục bộ của bạn có liên kết đến kho lưu trữ gốc, từ đó giúp việc đồng bộ hóa các bản cập nhật theo thời gian trở nên dễ dàng hơn.

Bạn cũng cần các thẻ từ upstream để các công cụ như Toga và Briefcase có thể xác định chính xác số phiên bản:

$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware-docs-tools.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware-docs-tools.git
C:\...>git fetch --tags upstream

Nếu bạn muốn bản fork của mình cũng bao gồm các thẻ đó, bạn có thể đẩy chúng lên:

$ git push --tags

Điều này có thể hữu ích nếu sau này bạn tạo một bản sao mới và muốn các thẻ có sẵn từ bản phân nhánh của bạn.

Tạo một môi trường ảo

Để thiết lập môi trường ảo và nâng cấp pip, hãy chạy lệnh:

$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware-docs-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware-docs-tools
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Lệnh của bạn hiện đã có tiền tố (.venv) ở phía trước.

Cài đặt BeeWare Docs Tools

Giờ đây, khi bạn đã có mã nguồn, bạn có thể thực hiện cài đặt có thể chỉnh sửa của BeeWare Docs Tools vào môi trường phát triển của mình. Hãy chạy lệnh sau:

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Bật tính năng pre-commit

BeeWare Docs Tools sử dụng một công cụ có tên là pre-commit để phát hiện các lỗi đơn giản và chuẩn hóa định dạng mã nguồn. Công cụ này hoạt động bằng cách cài đặt một git hook để tự động chạy một loạt các công cụ kiểm tra mã nguồn trước khi hoàn tất bất kỳ commit Git nào. Để kích hoạt pre-commit, hãy chạy lệnh:

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Bây giờ bạn đã sẵn sàng để bắt đầu khám phá BeeWare Docs Tools!

Làm việc từ một chi nhánh

Hãy làm việc trên nhánh tính năng, không phải nhánh main của bạn

Trước khi bắt đầu thực hiện thay đổi, hãy đảm bảo rằng bạn đã tạo một nhánh. Theo mặc định, khi bạn sao chép (clone) bản sao (fork) của kho lưu trữ, bạn sẽ được chuyển đến nhánh main của kho lưu trữ đó. Đây là bản sao chính xác của nhánh BeeWare Docs Tools trong kho lưu trữ main.

Mặc dù bạn có thể gửi yêu cầu pull từ nhánh main của mình, nhưng tốt nhất là bạn không nên làm như vậy. Nếu bạn gửi một yêu cầu pull gần như hoàn chỉnh, thành viên nhóm cốt lõi chịu trách nhiệm xem xét yêu cầu pull của bạn có thể sẽ trực tiếp thực hiện các thay đổi cần thiết, thay vì đưa ra phản hồi yêu cầu bạn chỉnh sửa một số chi tiết nhỏ. Tuy nhiên, nếu bạn gửi yêu cầu pull từ nhánh main của mình, những người xem xét sẽ không thể thực hiện bất kỳ chỉnh sửa nào.

Việc làm việc trên nhánh chính cũng sẽ gây khó khăn cho bạn sau khi bạn hoàn thành yêu cầu pull đầu tiên. Nếu bạn muốn thực hiện yêu cầu pull thứ hai, bạn sẽ cần có một bản sao "sạch" của nhánh chính trong dự án nguồn để làm cơ sở cho đóng góp thứ hai của mình; nếu bạn đã thực hiện đóng góp đầu tiên từ nhánh main, bạn sẽ không còn bản sao sạch đó nữa.

Thay vào đó, bạn nên thực hiện các thay đổi trên một chi nhánh tính năng. Chi nhánh tính năng có tên đơn giản để xác định thay đổi mà bạn đã thực hiện. Ví dụ: nếu bạn đang sửa một lỗi gây ra sự cố xây dựng trên Windows 11, bạn có thể tạo một nhánh tính năng fix-win11-build. Nếu lỗi của bạn liên quan đến một vấn đề cụ thể đã được báo cáo, việc tham chiếu số vấn đề đó trong tên nhánh cũng là điều phổ biến (ví dụ: fix-1234).

Để tạo nhánh tính năng fix-win11-build, hãy chạy lệnh:

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
Tránh tình trạng mở rộng phạm vi

Tránh tình trạng mở rộng phạm vi

"Sự mở rộng phạm vi" xảy ra khi danh sách các vấn đề được giải quyết hoặc các tính năng được triển khai trong một đóng góp cụ thể tăng lên đáng kể so với dự định ban đầu khi bắt đầu công việc. Bạn bắt đầu với một vấn đề đơn giản; sau đó phát hiện ra một vấn đề có liên quan chặt chẽ và quyết định đưa cả bản sửa lỗi đó vào; rồi đến vấn đề thứ ba… và trước khi bạn kịp nhận ra, bạn đã có một yêu cầu kéo (pull request) giải quyết 5 vấn đề và bổ sung 3 tính năng mới, bao gồm hàng chục tệp tin.

Việc phạm vi dự án bị mở rộng là điều ai cũng từng gặp phải. Đây là một khái niệm quá đỗi quen thuộc với các nhà phát triển dày dạn kinh nghiệm; ai trong chúng ta cũng đã từng trải qua điều này nhiều lần và phải đối mặt với tất cả những vấn đề đi kèm.

Có những lý do rất thực tế để tránh tình trạng mở rộng phạm vi. Càng đóng góp lớn, việc xử lý càng trở nên khó khăn. Việc xác định các trường hợp ngoại lệ hoặc các vấn đề tiềm ẩn cũng trở nên phức tạp hơn, điều này có nghĩa là chất lượng tổng thể của đóng góp có thể bị giảm sút. Việc đánh giá cũng trở nên khó khăn hơn khi người đánh giá phải xử lý nhiều bối cảnh, có thể không liên quan đến nhau. Một đóng góp lớn hơn đồng nghĩa với nhiều bình luận đánh giá hơn, và với tư cách là người đóng góp, bạn có thể gặp khó khăn khi theo dõi nhiều chuỗi bình luận đánh giá. Ngay cả trải nghiệm GitHub của bạn cũng sẽ bị ảnh hưởng - giao diện người dùng của GitHub sẽ chậm lại khi kích thước của PR tăng lên, đồng nghĩa với việc điều hướng các tệp qua giao diện GitHub và cố gắng để lại bình luận đánh giá sẽ ngày càng khó khăn hơn.

Bất cứ khi nào bạn thấy có lý do để bổ sung bất kỳ nội dung nào vào bản đóng góp của mình mà nội dung đó không được nêu rõ trong đề xuất ban đầu hoặc báo cáo lỗi, bạn nên cân nhắc xem liệu mình có đang đi vào tình trạng mở rộng phạm vi (scope creep) hay không. Có hai tính năng riêng biệt có thể được triển khai độc lập không? Có thể triển khai một tính năng với một hạn chế hoặc lỗi đã biết, và sửa lỗi đó trong một pull request tiếp theo không? Có phần nào của việc sửa lỗi độc lập với phần khác không? Nếu một phần của thay đổi có thể được loại bỏ mà không làm thay đổi đóng góp ban đầu, thì có lẽ nên loại bỏ nó.

Phát triển phần mềm luôn là một quá trình cải tiến từng bước. Mỗi đóng góp riêng lẻ nên giúp cơ sở mã trở nên tốt hơn sau khi được hợp nhất, nhưng việc để lại các lỗi hoặc một phần của tính năng để cải thiện trong tương lai là hoàn toàn chấp nhận được. Điều đó có thể có nghĩa là chia một yêu cầu kéo (pull request) thành nhiều phần có thể được xem xét độc lập, hoặc tạo một vấn đề (issue) để người khác có thể điều tra và giải quyết vấn đề.

Việc giới hạn phạm vi của mỗi bài viết sẽ có lợi cho tất cả những người liên quan, bao gồm cả bạn. Các nhà phản biện của bạn, và cả chính bạn, sẽ đánh giá cao điều này.

Tài liệu xây dựng

Tài liệu xây dựng

Trước khi thực hiện bất kỳ thay đổi nào đối với tài liệu của BeeWare Docs Tools, bạn nên xác nhận rằng bạn có thể biên dịch được tài liệu hiện có.

Trước khi bắt đầu soạn thảo tài liệu, hãy đảm bảo rằng bạn đã thiết lập xong môi trường phát triển.

Bạn phải cài đặt trình thông dịch Python 3.13 và đảm bảo nó có trong đường dẫn (tức là python3.13 phải khởi chạy trình thông dịch Python 3.13).

BeeWare Docs Tools sử dụng tox để tạo tài liệu. Các lệnh tox sau đây phải được thực thi từ cùng vị trí với tệp tox.ini, nằm trong thư mục gốc của dự án.

Xem trước tài liệu trực tiếp

Để hỗ trợ việc chỉnh sửa tài liệu nhanh chóng, BeeWare Docs Tools có chế độ "xem trước trực tiếp".

Bản xem trước trực tiếp sẽ được tạo ra kèm theo các cảnh báo!

Dịch vụ trực tiếp (live serve) cho phép bạn thực hiện các lần cập nhật tài liệu một cách linh hoạt. Trong quá trình cập nhật, bạn có thể gặp phải lỗi định dạng. Các lỗi được đánh dấu là WARNING sẽ khiến quá trình xây dựng tiêu chuẩn bị lỗi; tuy nhiên, dịch vụ trực tiếp được cấu hình để hiển thị cảnh báo trong cửa sổ console mà vẫn tiếp tục quá trình xây dựng. Điều này giúp bạn thực hiện các lần cập nhật mà không cần phải khởi động lại bản xem trước trực tiếp.

Một WARNING khác với một ERROR. Nếu bạn gây ra một sự cố được coi là một ERROR, máy chủ trực tuyến sẽ gặp sự cố và cần phải khởi động lại. Máy chủ sẽ không khởi động lại cho đến khi sự cố WARNING được khắc phục.

Để khởi động máy chủ trực tuyến:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Quá trình này sẽ tạo tài liệu, khởi động máy chủ web để cung cấp tài liệu và theo dõi hệ thống tệp để phát hiện bất kỳ thay đổi nào đối với tệp nguồn của tài liệu.

Sau khi máy chủ được khởi động, bạn sẽ thấy nội dung tương tự như sau trong kết quả hiển thị trên bảng điều khiển:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

Mở trình duyệt và truy cập vào URL được cung cấp. Bây giờ bạn có thể bắt đầu cập nhật tài liệu. Nếu phát hiện có thay đổi, tài liệu sẽ được xây dựng lại và bất kỳ trình duyệt nào đang xem trang đã được sửa đổi sẽ tự động được làm mới.

docs-live là bước đầu tiên

Việc chạy docs-live trên máy chủ trực tiếp chỉ dành cho các lần thử nghiệm ban đầu. Bạn luôn nên chạy bản dựng cục bộ trước khi gửi yêu cầu pull.

Bản dựng cục bộ

Sau khi hoàn tất quá trình lặp, bạn cần thực hiện việc biên dịch tài liệu tại máy cục bộ. Quy trình biên dịch này được thiết kế để báo lỗi nếu phát hiện bất kỳ vấn đề nào liên quan đến mã đánh dấu. Điều này giúp bạn phát hiện ra những lỗi mà bạn có thể đã bỏ sót khi kiểm tra trên máy chủ trực tuyến.

Tạo bản dựng cục bộ

Để tạo bản dựng cục bộ:

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Kết quả của quá trình xây dựng này sẽ được lưu trong thư mục _build ở thư mục gốc của dự án.

Tạo bản dựng đã dịch tại địa phương

Tài liệu của BeeWare Docs Tools đã được dịch sang nhiều ngôn ngữ. Các bản cập nhật đối với tài liệu tiếng Anh có thể gây ra sự cố trong các bản dịch sang các ngôn ngữ khác. Điều quan trọng là phải kiểm tra xem tất cả các bản dịch đều hoạt động bình thường trước khi gửi yêu cầu pull.

Để tạo bản dựng bao gồm tất cả các bản dịch hiện có:

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Kết quả của mỗi lần biên dịch ngôn ngữ sẽ được lưu trong thư mục _build/html/<languagecode> tương ứng, trong đó <languagecode> là mã ngôn ngữ gồm hai hoặc năm ký tự liên quan đến ngôn ngữ cụ thể đó (ví dụ: fr cho tiếng Pháp, it cho tiếng Ý, v.v.).

Nếu bạn phát hiện ra vấn đề với một bản dựng cụ thể, bạn có thể chạy riêng bản dựng đó bằng cách thực thi tox -e docs-<languagecode>. Ví dụ: để chỉ xây dựng tài liệu tiếng Pháp, hãy thực thi:

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Kết quả của quá trình biên dịch đơn ngôn ngữ sẽ được lưu trong thư mục _build.

Kiểm tra cú pháp tài liệu

Quá trình biên dịch sẽ phát hiện các lỗi Markdown, nhưng BeeWare Docs Tools thực hiện thêm một số kiểm tra về phong cách và định dạng, được gọi là "linting". Để chạy các kiểm tra lint:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Điều này sẽ đảm bảo tài liệu không chứa:

  • liên kết hỏng
  • các từ viết sai chính tả

Nếu một cách viết đúng của một từ bị nhận diện là sai chính tả, hãy thêm từ đó vào danh sách trong docs/spelling_wordlist. Thao tác này sẽ thêm từ đó vào từ điển của trình kiểm tra chính tả. Khi thêm vào danh sách này, hãy lưu ý:

  • Chúng tôi ưu tiên cách viết theo chuẩn Mỹ, nhưng vẫn linh hoạt chấp nhận một số thuật ngữ thông dụng đặc thù trong lĩnh vực lập trình (ví dụ: "apps") và việc biến danh từ thành động từ (ví dụ: "scrollable")
  • Khi đề cập đến tên sản phẩm, cần tuân thủ quy tắc viết hoa theo quy định của sản phẩm đó. (Ví dụ: "macOS", "GTK", "pytest", "Pygame", "PyScript").
  • Nếu một thuật ngữ được sử dụng "như một đoạn mã", thì nó nên được đặt trong dấu ngoặc kép (like this) thay vì được thêm vào từ điển.

Sau khi đã tạo thành công tài liệu, bạn đã sẵn sàng để viết tài liệu.

Viết tài liệu

Viết tài liệu

Dưới đây là các bước bạn cần thực hiện để đóng góp tài liệu cho BeeWare Docs Tools.

Trước khi bắt đầu viết tài liệu, hãy đảm bảo rằng bạn có thể tạo tài liệu và đang làm việc trên một nhánh.

Cập nhật tài liệu hiện có

Nếu bạn đang chỉnh sửa các tài liệu hiện có, bạn cần tìm tệp trong thư mục /docs/en. Cấu trúc tệp tuân theo cấu trúc trang, do đó bạn có thể tìm tệp bằng cách sử dụng URL của tài liệu.

Thêm tài liệu mới

Nếu bạn đang thêm một tài liệu mới, bạn sẽ cần thực hiện thêm một vài bước nữa.

Bạn cần tạo tài liệu tại vị trí thích hợp trong thư mục docs/en. Để tiện thảo luận, chúng ta sẽ giả định rằng bạn đang thêm một tài liệu mới có tên tệp là new_doc.md.

Sau đó, bạn cần cập nhật tệp docs/en/SUMMARY.md để thêm tệp mới của bạn vào. Tệp SUMMARY.md được tổ chức sao cho phản ánh cơ bản cấu trúc thư mục docs/en, nhưng quan trọng hơn, nó quyết định trực tiếp cấu trúc của thanh bên trái. Nếu bạn tìm thấy phần mà bạn định thêm tệp new_doc.md, bạn không cần thay đổi bất cứ điều gì trong tệp SUMMARY.md nếu thấy đường dẫn có ký hiệu đại diện được liệt kê. Ví dụ:

- ./path/to/directory/*

Nếu phần mà bạn định chèn new_doc.md là một danh sách các liên kết Markdown riêng lẻ, bạn sẽ cần thêm một liên kết cụ thể đến liên kết của mình. Ví dụ:

- [Tài liệu mới của tôi](new_doc.md)

Viết tài liệu

Bây giờ bạn có thể mở tệp mong muốn trong trình soạn thảo của mình và bắt đầu viết.

Chúng tôi có một hướng dẫn phong cách tài liệu nêu rõ các nguyên tắc về việc soạn thảo tài liệu cho BeeWare.

Khi bạn đã hài lòng với tài liệu mới của mình, bạn có thể gửi yêu cầu pull kèm theo các thay đổi đề xuất.

Thêm ghi chú thay đổi

Thêm thông tin thay đổi vào ghi chú phát hành

BeeWare Docs Tools sử dụng towncrier để hỗ trợ việc soạn thảo ghi chú phát hành cho mỗi bản phát hành. Khi bạn gửi yêu cầu pull, yêu cầu đó phải bao gồm một ghi chú thay đổi - ghi chú thay đổi này sẽ trở thành mục trong ghi chú phát hành mô tả những thay đổi đã được thực hiện.

Mỗi yêu cầu kéo (pull request) phải bao gồm ít nhất một tệp trong thư mục changes/ chứa mô tả ngắn gọn về thay đổi được thực hiện bởi yêu cầu kéo đó. Ghi chú thay đổi phải ở định dạng Markdown, trong một tệp có tên theo định dạng <id>.<fragment type>.md. Nếu thay đổi bạn đề xuất nhằm sửa lỗi hoặc triển khai tính năng đã có số vấn đề (issue number) tương ứng, thì ID sẽ là số của phiếu đó. Nếu thay đổi không có vấn đề tương ứng, số PR có thể được sử dụng làm ID. Bạn sẽ không biết số PR này cho đến khi đẩy yêu cầu kéo, do đó lần chạy CI đầu tiên sẽ không qua được kiểm tra towncrier; hãy thêm ghi chú thay đổi và đẩy bản cập nhật PR, sau đó CI sẽ chạy thành công.

Có năm loại đoạn văn:

  • feature: Bản PR bổ sung một tính năng hoặc khả năng mới mà trước đây chưa có (ví dụ: bổ sung hỗ trợ cho một định dạng gói mới, hoặc một tính năng mới trong một định dạng gói hiện có);
  • bugfix: Bản cập nhật này khắc phục một lỗi trong phiên bản hiện tại;
  • doc: Bản tin báo chí là một bước cải tiến đáng kể đối với tài liệu;
  • removal; Bản PR này mang lại một thay đổi không tương thích ngược trong API BeeWare Docs Tools; hoặc
  • misc; Một thay đổi nhỏ hoặc mang tính hành chính (ví dụ: sửa lỗi chính tả, làm rõ một chi tiết ngôn ngữ nhỏ hoặc cập nhật phiên bản phụ thuộc) mà không cần phải thông báo trong ghi chú phát hành.

Mô tả trong ghi chú thay đổi này nên là một bản tóm tắt "tiếp thị" ở cấp độ cao về thay đổi đó từ góc độ của người dùng, chứ không phải là một mô tả kỹ thuật chuyên sâu hay chi tiết triển khai. Nó khác biệt với thông điệp cam kết (commit message) – thông điệp cam kết mô tả những gì đã được thực hiện để các nhà phát triển sau này có thể theo dõi lý do đằng sau một thay đổi; trong khi đó, ghi chú thay đổi là mô tả dành cho người dùng, những người có thể không am hiểu về cơ chế hoạt động bên trong.

Ví dụ: nếu bạn sửa một lỗi liên quan đến việc đặt tên dự án, nội dung thông báo cam kết có thể như sau:

Áp dụng quy tắc kiểm tra biểu thức chính quy nghiêm ngặt hơn để không cho phép tên dự án bắt đầu bằng số.

Ghi chú thay đổi tương ứng sẽ có nội dung như sau:

Tên dự án không được bắt đầu bằng số nữa.

Một số yêu cầu kéo (PR) có thể giới thiệu nhiều tính năng và sửa nhiều lỗi, hoặc đưa ra nhiều thay đổi không tương thích ngược. Trong trường hợp đó, PR có thể có nhiều tệp ghi chú thay đổi. Nếu bạn cần liên kết hai loại ghi chú thay đổi với cùng một ID, bạn có thể thêm một hậu tố số. Ví dụ: nếu PR 789 thêm một tính năng được mô tả trong ticket 123, khắc phục một lỗi được mô tả trong ticket 234, và cũng thực hiện hai thay đổi không tương thích ngược, bạn có thể có 4 tệp ghi chú thay đổi:

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

Để biết thêm thông tin về towncrier và các loại đoạn tin, hãy xem Đoạn tin tức. Bạn cũng có thể xem các ví dụ hiện có về đoạn tin tức trong thư mục changes của kho lưu trữ BeeWare Docs Tools. Nếu thư mục này trống, có thể là do BeeWare Docs Tools vừa phát hành một phiên bản mới; các tệp ghi chú thay đổi sẽ bị xóa và hợp nhất để cập nhật ghi chú phát hành với mỗi phiên bản. Bạn có thể xem tệp đó để biết kiểu bình luận được yêu cầu; bạn có thể xem các PR được hợp nhất gần đây để biết cách định dạng ghi chú thay đổi của mình.

Gửi yêu cầu pull

Gửi yêu cầu pull

Bây giờ bạn đã lưu tất cả các thay đổi, bạn đã sẵn sàng gửi yêu cầu hợp nhất. Để đảm bảo quá trình đánh giá diễn ra suôn sẻ, bạn nên thực hiện một số bước sau.

Sử dụng lệnh pre-commit

Khi bạn thực hiện bất kỳ thay đổi nào, pre-commit sẽ tự động chạy. Nếu phát hiện bất kỳ vấn đề nào trong lần commit đó, quá trình commit sẽ bị thất bại. Trong phạm vi có thể, pre-commit sẽ thực hiện các thay đổi cần thiết để khắc phục các vấn đề đã phát hiện. Trong ví dụ sau, kiểm tra ruff đã phát hiện một vấn đề về định dạng mã:

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

Trong trường hợp này, ruff đã tự động khắc phục sự cố; do đó, bạn có thể thêm lại bất kỳ tệp nào đã bị sửa đổi do quá trình kiểm tra trước khi cam kết, rồi cam kết lại thay đổi đó. Tuy nhiên, một số kiểm tra sẽ yêu cầu bạn thực hiện các chỉnh sửa thủ công. Sau khi đã thực hiện những thay đổi đó, hãy thêm lại các tệp đã được sửa đổi và cam kết lại.

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Khi quá trình hoàn tất, bạn sẽ thấy một thông báo cho biết bản commit đã được hoàn tất, và trong git log, bản commit này sẽ hiển thị là bản cập nhật mới nhất. Bây giờ bạn đã sẵn sàng để đẩy lên GitHub.

Đẩy các thay đổi của bạn lên GitHub và tạo yêu cầu kéo

Lần đầu tiên bạn đẩy mã lên GitHub, bạn sẽ nhận được một liên kết dẫn trực tiếp đến trang GitHub để tạo yêu cầu kéo mới. Hãy truy cập liên kết đó và tạo yêu cầu kéo của bạn.

Dưới đây là một ví dụ về những gì bạn sẽ thấy trên push, với URL được đánh dấu.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare Docs Tools.git
 * [new branch]      fix-win11-build -> fix-win11-build

Nếu bạn đã từng đẩy nhánh hiện tại lên GitHub, bạn sẽ không nhận được liên kết đó lần nữa. Tuy nhiên, vẫn có những cách khác để lấy liên kết tạo yêu cầu kéo (PR):

  • Truy cập vào kho lưu trữ nguồn, nhấp vào "Yêu cầu kéo" rồi chọn "Yêu cầu kéo mới", sau đó chọn nhánh mà bạn muốn gửi yêu cầu kéo từ đó.
  • Nếu bạn vừa thực hiện push gần đây, hãy truy cập vào kho lưu trữ nguồn, tìm biểu ngữ ở phía trên danh sách các tệp cho biết kho lưu trữ này "vừa có các lần push gần đây", rồi nhấp vào nút "So sánh & gửi yêu cầu pull".
  • Sử dụng lệnh gh pr create --web của GitHub CLI để mở trình duyệt web đến trang tạo PR.

GitHub CLI: gh

GitHub cung cấp GitHub CLI, cho phép bạn truy cập nhiều tính năng của GitHub từ dòng lệnh thông qua lệnh gh. Tài liệu hướng dẫn GitHub CLI giới thiệu chi tiết về tất cả các tính năng này.

gh pr create

Không sử dụng lệnh gh pr create đơn thuần để tạo yêu cầu kéo (pull request). Các dự án BeeWare sử dụng một mẫu cho các yêu cầu kéo, và chúng tôi yêu cầu tất cả các đóng góp phải tuân theo mẫu này. Lệnh gh pr create sẽ khiến mẫu này không được áp dụng.

Nội dung yêu cầu kéo

Tiêu đề của yêu cầu kéo (pull request) phải mang tính thông tin, rõ ràng và súc tích. Hãy cố gắng giữ cho tiêu đề ngắn gọn nếu có thể, nhưng nếu cần thiết, tiêu đề dài hơn cũng được chấp nhận. Một tiêu đề PR tốt nên giúp người đọc không có thông tin nền tảng nào cũng có thể hiểu được một cách tương đối rõ ràng lỗi hoặc tính năng nào được khắc phục hoặc triển khai trong yêu cầu kéo của bạn.

Yêu cầu kéo của bạn phải tuân theo mẫu yêu cầu kéo của BeeWare. Nếu bạn đã tạo yêu cầu kéo thông qua giao diện web của GitHub, mẫu này sẽ được cung cấp làm điểm khởi đầu cho phần mô tả của yêu cầu kéo. Nếu bạn vô tình tạo yêu cầu kéo mà không sử dụng mẫu này, bạn có thể chỉnh sửa yêu cầu kéo để thêm nội dung mẫu vào — nhưng nội dung mẫu phải được cung cấp và điền đầy đủ theo đúng quy định.

Mô tả PR phải phản ánh rõ ràng những thay đổi trong PR. Một người không có bất kỳ thông tin nền nào cũng phải có thể đọc mô tả của bạn và hiểu được tương đối đầy đủ lý do tại sao thay đổi đó được thực hiện. Hãy tránh sử dụng các câu đùa, thành ngữ, ngôn ngữ thông tục và các định dạng không cần thiết, chẳng hạn như viết toàn bộ bằng chữ in hoa hoặc lạm dụng dấu câu; đây là một lời giải thích đơn giản về những gì đang diễn ra trong PR của bạn, và việc tránh những điều đó sẽ giúp mô tả trở nên dễ tiếp cận hơn với người khác.

Nếu có bất kỳ trường hợp tái hiện lỗi nào, hoặc bất kỳ quy trình kiểm thử nào mà bạn đã sử dụng nhưng chưa được đưa vào các thay đổi trong PR, thì cần phải giải thích và bổ sung chúng vào PR. Phần giải thích cần nêu rõ cách thực hiện các quy trình đó, cũng như các bước cần thực hiện để tái hiện kết quả mong muốn.

Nếu yêu cầu kéo (pull request) của bạn sẽ giải quyết vấn đề #1234, bạn nên thêm văn bản Fixes #1234 vào phần mô tả của yêu cầu kéo. Điều này sẽ khiến vấn đề được tự động đóng lại khi yêu cầu kéo được hợp nhất. Bạn có thể tham chiếu đến các cuộc thảo luận, vấn đề hoặc yêu cầu kéo khác bằng cách sử dụng cú pháp #1234 tương tự. Bạn có thể tham chiếu đến một vấn đề trên kho lưu trữ khác bằng cách thêm dấu gạch ngang (-) trước số — ví dụ: python/cpython#1234 sẽ tham chiếu đến vấn đề 1234 trên kho lưu trữ CPython.

Các công cụ AI đặc biệt dễ tạo ra các thông điệp yêu cầu kéo (pull request) dài dòng và không hữu ích. Nếu bạn sử dụng công cụ AI để tạo yêu cầu kéo, bạn phải chịu trách nhiệm đảm bảo rằng phần mô tả của yêu cầu kéo phải súc tích và chỉ chứa thông tin hữu ích cho quá trình đánh giá. Ví dụ, bạn không cần phải bao gồm chi tiết về "quy trình kiểm thử" mô tả cách chạy bộ kiểm thử, hoặc "lý do" tại sao lỗi cần được sửa. Nội dung yêu cầu kéo quá dài dòng có thể dẫn đến việc yêu cầu kéo của bạn bị đóng mà không được xem xét, vì chúng không tôn trọng nguồn lực hạn chế của nhóm cốt lõi.

Mẫu yêu cầu kéo (Pull Request) của BeeWare

Mẫu yêu cầu kéo (pull request) của BeeWare [(https://github.com/beeware/.github/blob/main/.github/pull_request_template.md)] không phải là tùy chọn. Chúng tôi yêu cầu tất cả các yêu cầu kéo phải tuân theo mẫu này. Yêu cầu kéo của bạn sẽ không được xem xét nếu thiếu phần "Danh sách kiểm tra PR" hoặc các câu trả lời của bạn cho các câu hỏi có ô chọn là không đầy đủ hoặc không nhất quán. Nếu bạn đã sử dụng công cụ AI để tạo yêu cầu kéo, bạn phải đánh dấu vào ô tương ứng và cung cấp chi tiết tại dòng "Được hỗ trợ bởi:".

Tích hợp liên tục

Tích hợp liên tục (hay CI) là quá trình thực hiện các kiểm tra tự động đối với yêu cầu kéo (pull request) của bạn. Quá trình này có thể bao gồm các kiểm tra đơn giản như đảm bảo mã nguồn được định dạng đúng; nhưng cũng bao gồm việc chạy bộ kiểm thử và tạo tài liệu.

Có rất nhiều thay đổi có thể dẫn đến lỗi CI. Nói chung, chúng tôi sẽ không xem xét các yêu cầu kéo (pull request) không vượt qua CI. Nếu bạn tạo một yêu cầu kéo và CI báo lỗi, chúng tôi sẽ không bắt đầu xem xét cho đến khi nó vượt qua. Nếu những thay đổi của bạn dẫn đến lỗi, bạn có trách nhiệm tìm hiểu nguyên nhân và khắc phục sự cố.

Khi CI không thành công, các liên kết về lỗi sẽ xuất hiện ở cuối trang PR, dưới tiêu đề "Một số kiểm tra không thành công". Bạn sẽ thấy danh sách các kiểm tra không thành công, danh sách này sẽ xuất hiện ở đầu danh sách tất cả các kiểm tra nếu có các kiểm tra thành công khác. Nếu bạn nhấp vào liên kết lỗi, bạn sẽ được chuyển đến nhật ký. Nhật ký thường cung cấp tất cả thông tin bạn cần để xác định nguyên nhân gây ra lỗi. Hãy đọc kỹ nhật ký và cố gắng tìm hiểu lý do tại sao lỗi xảy ra, sau đó thực hiện các bước cần thiết để khắc phục nó.

Đôi khi, quá trình kiểm tra CI có thể thất bại vì những lý do không liên quan đến những thay đổi của bạn. Điều này có thể do sự cố trên máy chủ chạy quá trình kiểm tra CI, hoặc do quá trình kiểm tra CI không ổn định. Nếu bạn thấy quá trình kiểm tra thất bại và khá chắc chắn rằng điều này không liên quan đến những thay đổi của bạn, hãy thêm một bình luận vào PR của bạn để nêu rõ điều này, và chúng tôi sẽ kiểm tra vấn đề.

Để khởi chạy một chu trình CI mới, bạn cần đẩy các thay đổi mới lên nhánh của mình.

Nếu bạn gặp khó khăn trong việc giúp CI chạy thành công, hãy để lại bình luận trên PR để thông báo cho chúng tôi biết và chúng tôi sẽ cố gắng hết sức để hỗ trợ bạn.

Các kiểm tra pre-commit và towncrier

Nếu bất kỳ kiểm tra nào trong số pre-commit hoặc towncrier không thành công, điều này sẽ ngăn chặn hầu hết các kiểm tra CI còn lại không thể chạy. Bạn cần khắc phục các vấn đề liên quan trước khi toàn bộ các kiểm tra có thể được thực thi.

Chúng tôi có nguồn lực CI hạn chế. Điều quan trọng cần lưu ý là mỗi khi bạn đẩy mã lên nhánh, hệ thống CI sẽ tự động khởi chạy. Nếu bạn định thực hiện nhiều thay đổi, tốt nhất nên thực hiện các thay đổi đó trên máy cục bộ, sau đó đẩy tất cả cùng một lúc. Hệ thống CI sẽ chỉ chạy trên bản cam kết mới nhất trong đợt đẩy đó, giúp giảm thiểu tải cho hệ thống CI của chúng tôi.

Quá trình gửi PR của bạn chỉ được coi là hoàn tất khi nó vượt qua kiểm tra tích hợp (CI), hoặc bạn có thể đưa ra lời giải thích về lý do tại sao nó không vượt qua.

Khi gửi yêu cầu pull, bạn cần đính kèm ghi chú thay đổi trước khi yêu cầu đó có thể được xem xét.