Triển khai một tính năng mới¶

Sau khi quy trình đề xuất kết thúc, bạn sẽ có trong tay bản thiết kế hoàn chỉnh cho tính năng mới. Điều đó có nghĩa là đã đến lúc bắt tay vào viết!

Nếu tính năng của bạn yêu cầu một cách triển khai dành riêng cho nền tảng cụ thể, quá trình đề xuất nên đã xác nhận rằng ý tưởng đó có thể được triển khai trên tất cả các nền tảng. Tuy nhiên, với tư cách là người lần đầu tiên triển khai một tính năng mới, bạn không có trách nhiệm triển khai tính năng mới đó cho tất cả các nền tảng. Bạn cần cung cấp một bản triển khai hoàn chỉnh cho ít nhất một nền tảng, bao gồm các bài kiểm tra. Đối với bất kỳ nền tảng nào khác, bạn sẽ cần cung cấp một bản triển khai "stub" - một bản triển khai chỉ cung cấp định nghĩa giao diện cơ bản, nhưng sẽ gây ra lỗi NotImplementedError hoặc hiển thị thông báo nhật ký rằng hành vi đó chưa được triển khai trên nền tảng đó.

Một phần quan trọng trong quá trình triển khai một tính năng mới là đảm bảo tính năng đó được ghi chép đầy đủ. Ít nhất, điều này có nghĩa là phải đảm bảo có tài liệu hướng dẫn API; tuy nhiên, có thể còn cần phải bổ sung thêm hướng dẫn thực hành hoặc hướng dẫn chuyên đề.

Đóng góp các tính năng mới¶

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.

macOSLinuxWindows

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:

macOSLinuxWindows

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:

macOSLinuxWindows

$ 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:

macOSLinuxWindows

$ 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:

macOSLinuxWindows

(.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:

macOSLinuxWindows

(.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:

macOSLinuxWindows

(.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.

Triển khai tính năng mới

Viết, chạy và kiểm thử mã nguồn¶

Để sửa lỗi hoặc triển khai một tính năng, bạn sẽ cần phải viết một số đoạn mã mới.

Để bắt đầu viết mã, hãy đảm bảo rằng bạn đã thiết lập xong môi trường phát triển và đang làm việc trên một nhánh

Chúng tôi có một hướng dẫn phong cách viết mã nêu rõ các nguyên tắc viết mã cho BeeWare.

Phát triển hướng kiểm thử¶

Một cách hiệu quả để đảm bảo mã nguồn của bạn sẽ hoạt động đúng như mong đợi là trước tiên hãy viết một trường hợp kiểm thử để kiểm tra chức năng đó. Trường hợp kiểm thử này ban đầu sẽ không thành công, vì đoạn mã cần kiểm tra vẫn chưa được triển khai. Sau đó, bạn có thể thực hiện các thay đổi cần thiết để trường hợp kiểm thử này thành công, và từ đó biết chắc rằng những gì bạn đã viết đang giải quyết đúng vấn đề mà bạn mong đợi.

Chạy mã của bạn¶

Sau khi đã viết xong mã, bạn cần đảm bảo rằng nó hoạt động bình thường. Bạn sẽ phải chạy mã thủ công để kiểm tra xem nó có hoạt động đúng như mong đợi hay không. Nếu chưa làm, bạn nên viết một trường hợp kiểm thử cho các thay đổi của mình; như đã đề cập ở trên, trường hợp kiểm thử này sẽ báo lỗi nếu mã của bạn bị bỏ qua (commented out) hoặc không tồn tại.

Bạn sẽ thêm trường hợp kiểm thử của mình vào bộ kiểm thử để nó có thể được chạy cùng với các bài kiểm thử khác. Bước tiếp theo là chạy bộ kiểm thử.

Chạy các bài kiểm tra và độ bao phủ¶

BeeWare Docs Tools sử dụng tox để quản lý quy trình kiểm thử và pytest cho bộ kiểm thử của riêng mình.

Lệnh tox mặc định bao gồm việc thực thi:

các hook trước khi commit
towncrier Kiểm tra ghi chú phát hành
kiểm tra cú pháp tài liệu
bộ kiểm thử cho các phiên bản Python hiện có
báo cáo độ bao phủ mã

Đây chính là quy trình mà CI thực hiện khi bạn gửi yêu cầu pull.

Để chạy toàn bộ bộ kiểm thử, hãy thực hiện lệnh sau:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Việc chạy toàn bộ bộ kiểm thử có thể mất một thời gian. Bạn có thể tăng tốc đáng kể bằng cách chạy tox song song, bằng cách chạy tox p (hoặc tox run-parallel). Khi chạy bộ kiểm thử song song, bạn sẽ nhận được ít thông tin phản hồi hơn về tiến trình của bộ kiểm thử trong khi chạy, nhưng vẫn sẽ nhận được bản tóm tắt về bất kỳ vấn đề nào được phát hiện vào cuối quá trình chạy kiểm thử. Bạn sẽ thấy một số kết quả cho biết các bài kiểm thử đã được chạy. Bạn có thể thấy các bài kiểm tra SKIPPED, nhưng không bao giờ nhận được kết quả kiểm tra FAIL hoặc ERROR. Chúng tôi chạy bộ kiểm tra đầy đủ trước khi hợp nhất mọi bản vá. Nếu quá trình đó phát hiện bất kỳ vấn đề nào, chúng tôi sẽ không hợp nhất bản vá. Nếu bạn phát hiện lỗi hoặc thất bại trong kiểm tra, hoặc là có điều gì đó bất thường trong môi trường kiểm tra của bạn, hoặc bạn đã phát hiện một trường hợp ngoại lệ mà chúng tôi chưa từng gặp trước đây - dù là trường hợp nào, hãy cho chúng tôi biết!

Ngoài việc các bài kiểm tra đã vượt qua, điều này cũng nên cho thấy độ bao phủ kiểm tra 100%.

Chạy các biến thể thử nghiệm¶

Chạy các bài kiểm tra cho nhiều phiên bản Python¶

Theo mặc định, nhiều lệnh tox sẽ cố gắng chạy bộ kiểm thử nhiều lần, mỗi lần tương ứng với một phiên bản Python được BeeWare Docs Tools hỗ trợ. Tuy nhiên, để thực hiện điều này, mỗi phiên bản Python phải được cài đặt trên máy tính của bạn và có thể được quá trình [phát hiện]tox Python của (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery) tìm thấy. Nói chung, nếu một phiên bản Python có sẵn thông qua PATH, thì tox sẽ có thể tìm thấy và sử dụng nó.

Chỉ chạy bộ kiểm thử¶

Nếu bạn đang liên tục cải tiến một tính năng mới, bạn không cần phải chạy toàn bộ bộ kiểm thử; bạn có thể chỉ chạy các bài kiểm thử đơn vị. Để thực hiện việc này, hãy chạy lệnh:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Chạy một tập hợp con các bài kiểm tra¶

Theo mặc định, tox sẽ chạy tất cả các bài kiểm thử trong bộ kiểm thử đơn vị. Khi bạn đang phát triển bài kiểm thử mới, việc chỉ chạy duy nhất bài kiểm thử đó có thể rất hữu ích. Để thực hiện điều này, bạn có thể truyền bất kỳ chỉ định pytest nào làm tham số cho tox. Các đường dẫn kiểm thử này được tính theo thư mục briefcase. Ví dụ: để chỉ chạy các bài kiểm thử trong một tệp duy nhất, hãy chạy:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Bạn vẫn sẽ nhận được báo cáo độ bao phủ khi chạy một phần của bộ kiểm thử — nhưng kết quả độ bao phủ sẽ chỉ liệt kê các dòng mã đã được thực thi bởi các bài kiểm thử cụ thể mà bạn đã chạy.

Chạy bộ kiểm thử cho một phiên bản Python cụ thể¶

Theo mặc định, tox -e py sẽ chạy bằng trình thông dịch nào được xác định là python trên máy của bạn. Nếu bạn đã cài đặt nhiều phiên bản Python và muốn kiểm tra một phiên bản cụ thể trong số các phiên bản đã cài đặt, bạn có thể chỉ định phiên bản Python cụ thể để sử dụng. Ví dụ: để chạy bộ kiểm thử trên Python 3.10, hãy chạy lệnh:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

Có thể chạy một tập con các bài kiểm tra bằng cách thêm -- và thông số kỹ thuật của bài kiểm tra vào dòng lệnh.

Chạy bộ kiểm thử mà không tính độ bao phủ (nhanh)¶

Theo mặc định, tox sẽ chạy bộ kiểm thử pytest ở chế độ một luồng. Bạn có thể tăng tốc độ thực thi bộ kiểm thử bằng cách chạy bộ kiểm thử song song. Chế độ này không tạo ra các tệp độ bao phủ do sự phức tạp trong việc thu thập dữ liệu độ bao phủ trong các tiến trình được khởi tạo. Để chạy một phiên bản Python duy nhất ở chế độ "nhanh", hãy thực thi lệnh:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Có thể chạy một tập con các bài kiểm thử bằng cách thêm -- và thông số kỹ thuật của bài kiểm thử vào dòng lệnh; có thể sử dụng một phiên bản Python cụ thể bằng cách thêm phiên bản đó vào mục tiêu kiểm thử (ví dụ: py310-fast để chạy nhanh trên Python 3.10).

Độ bao phủ mã¶

BeeWare Docs Tools duy trì độ bao phủ nhánh 100% trong cơ sở mã của mình. Khi bạn thêm hoặc sửa đổi mã trong dự án, bạn phải thêm mã kiểm thử để đảm bảo độ bao phủ cho mọi thay đổi mà bạn thực hiện.

Tuy nhiên, BeeWare Docs Tools nhắm đến nhiều nền tảng cũng như nhiều phiên bản Python, do đó không thể xác minh độ bao phủ đầy đủ trên một nền tảng và phiên bản Python duy nhất. Để giải quyết vấn đề này, một số quy tắc độ bao phủ có điều kiện được định nghĩa trong phần tool.coverage.coverage_conditional_plugin.rules của pyproject.toml (ví dụ: no-cover-if-is-windows có thể được sử dụng để đánh dấu một khối mã sẽ không được thực thi khi chạy bộ kiểm thử trên Windows). Các quy tắc này được sử dụng để xác định các phần mã chỉ được bao phủ trên các nền tảng hoặc phiên bản Python cụ thể.

Điều cần lưu ý là việc báo cáo độ bao phủ giữa các phiên bản Python có thể gặp một số vấn đề. Ví dụ, nếu các tệp độ bao phủ được tạo ra bằng một phiên bản Python nhưng việc báo cáo lại được thực hiện trên một phiên bản khác, báo cáo có thể chứa các kết quả dương tính giả liên quan đến các nhánh bị bỏ sót. Do đó, khi báo cáo độ bao phủ, nên luôn sử dụng phiên bản Python cũ nhất đã được dùng để tạo ra các tệp độ bao phủ.

Hiểu về kết quả bảo hiểm¶

Ở phần cuối của kết quả kiểm tra độ bao phủ, cần có một báo cáo về dữ liệu độ bao phủ đã thu thập được:

Name    Stmts   Miss Branch BrPart   Cover   Missing
 ---------------------------------------------------
 TOTAL    7540      0   1040      0  100.0%

Điều này cho thấy bộ kiểm thử đã thực thi mọi nhánh có thể có trong mã nguồn. Điều này không đảm bảo 100% rằng không có lỗi, nhưng nó có nghĩa là chúng ta đang kiểm tra từng dòng mã trong cơ sở mã.

Nếu bạn thực hiện thay đổi đối với cơ sở mã, có thể sẽ xuất hiện lỗ hổng trong phạm vi kiểm tra. Khi điều này xảy ra, báo cáo phạm vi kiểm tra sẽ cho bạn biết những dòng mã nào không được thực thi. Ví dụ, giả sử chúng ta đã thực hiện một thay đổi đối với some/interesting_file.py, bổ sung một số logic mới. Báo cáo phạm vi kiểm tra có thể trông như sau:

Name                                 Stmts   Miss Branch BrPart  Cover   Missing
 -------------------------------------------------------------------------------
 src/some/interesting_file.py           111      1     26      0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTAL                                 7540      1   1726      0  99.9%

Điều này cho thấy rằng dòng 170, các dòng 302–307 và một lệnh nhảy từ dòng 320 sang dòng 335 không được bộ kiểm thử thực thi. Bạn cần thêm các bài kiểm thử mới (hoặc sửa đổi bài kiểm thử hiện có) để khôi phục độ bao phủ này.

Báo cáo về nền tảng chủ và phiên bản Python¶

Bạn có thể tạo báo cáo độ bao phủ cho nền tảng và phiên bản Python của mình. Ví dụ: để chạy bộ kiểm thử và tạo báo cáo độ bao phủ trên Python 3.10, hãy thực thi lệnh:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Báo cáo phạm vi hỗ trợ cho nền tảng chủ¶

Nếu tất cả các phiên bản Python được hỗ trợ đều có sẵn cho tox, thì có thể báo cáo mức độ bao phủ cho nền tảng máy chủ bằng cách chạy:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Báo cáo phạm vi phủ sóng bằng HTML¶

Có thể tạo báo cáo độ bao phủ HTML bằng cách thêm -html vào bất kỳ tên môi trường độ bao phủ tox nào, ví dụ:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Không chỉ đơn thuần là viết các bài kiểm thử!¶

Mặc dù chúng tôi đảm bảo rằng tất cả mã nguồn đều được kiểm thử, nhưng nhiệm vụ này không chỉ đơn thuần là duy trì mức độ kiểm thử đó. Một phần của nhiệm vụ là kiểm tra mã nguồn trong quá trình phát triển. Bạn có thể viết một bộ kiểm thử toàn diện cho một chiếc áo phao bằng bê tông… nhưng chiếc áo phao bằng bê tông đó vẫn sẽ vô dụng đối với mục đích mà nó được thiết kế!

Khi phát triển các bài kiểm thử, bạn cũng nên kiểm tra xem mô-đun cốt lõi có nhất quán về mặt nội bộ hay không. Nếu bạn phát hiện bất kỳ tên phương thức nào không nhất quán bên trong (ví dụ: một phương thức được gọi là on_select trong một mô-đun, nhưng lại được gọi là on_selected trong mô-đun khác), hoặc nơi dữ liệu không được xử lý một cách nhất quán, hãy đánh dấu vấn đề đó và thông báo cho chúng tôi bằng cách tạo một ticket. Hoặc, nếu bạn tự tin rằng mình biết cần phải làm gì, hãy tạo một pull request để khắc phục vấn đề mà bạn đã phát hiện.

Khi mọi thứ đã hoạt động bình thường, bạn có thể gửi yêu cầu pull kèm theo các thay đổi của mình.

Tạo tài liệu

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:

macOSLinuxWindows

(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ộ:

macOSLinuxWindows

(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ó:

macOSLinuxWindows

(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:

macOSLinuxWindows

(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:

macOSLinuxWindows

(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ã:

macOSLinuxWindows

(.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.

macOSLinuxWindows

(.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.

macOSLinuxWindows

(.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.

Triển khai một tính năng mới¶

Đóng góp các tính năng mới¶

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

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

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

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

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

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

Cài đặt BeeWare Docs Tools¶

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

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ánh tình trạng mở rộng phạm vi¶

Viết, chạy và kiểm thử mã nguồn¶

Phát triển hướng kiểm thử¶

Chạy mã của bạn¶

Chạy các bài kiểm tra và độ bao phủ¶

Chạy các biến thể thử nghiệm¶

Chạy các bài kiểm tra cho nhiều phiên bản Python¶

Chỉ chạy bộ kiểm thử¶

Chạy một tập hợp con các bài kiểm tra¶

Chạy bộ kiểm thử cho một phiên bản Python cụ thể¶

Chạy bộ kiểm thử mà không tính độ bao phủ (nhanh)¶

Độ bao phủ mã¶

Hiểu về kết quả bảo hiểm¶

Báo cáo về nền tảng chủ và phiên bản Python¶

Báo cáo phạm vi hỗ trợ cho nền tảng chủ¶

Báo cáo phạm vi phủ sóng bằng HTML¶

Không chỉ đơn thuần là viết các bài kiểm thử!¶

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

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

Bản dựng cục bộ¶

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

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

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

Viết tài liệu¶

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

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

Viết tài liệu¶

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

Gửi yêu cầu pull¶

Sử dụng lệnh pre-commit¶

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

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

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

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¶