Bỏ qua

Sử dụng các công cụ

Một trong những phản hồi quý giá nhất mà chúng tôi có thể nhận được là từ những người đang thử sử dụng các công cụ BeeWare và phát hiện ra những điểm bất tiện hoặc tính năng còn thiếu. Việc hiểu rõ những khó khăn mà quý vị có thể gặp phải khi sử dụng các công cụ này trong thực tế là vô cùng hữu ích đối với chúng tôi.

Hãy nghĩ về thứ mà bạn luôn mong muốn được tạo ra, và thử thực hiện nó xem sao. Nếu cuối cùng bạn có thể hoàn thành dự án của mình, xin chúc mừng! Bạn đã có được thứ mà mình luôn mong muốn.

Tuy nhiên, nếu bạn gặp khó khăn, hãy cho chúng tôi biết vấn đề nằm ở đâu. Có phải thiếu một tính năng nào đó không? Tài liệu hướng dẫn có gây nhầm lẫn hoặc thiếu sót ở khía cạnh nào không? Việc chia sẻ trải nghiệm của bạn sẽ cung cấp cho chúng tôi những thông tin hữu ích để từ đó điều chỉnh quá trình lập kế hoạch của mình.

Nếu bạn gặp bất kỳ vấn đề nào, hãy tạo một chủ đề thảo luận mới, vì đó có thể là khởi đầu cho một vấn đề mới hoặc đề xuất tính năng.

Thống kê việc sử dụng công cụ

Gửi báo cáo sự cố mới

Gửi báo cáo sự cố mới

Việc soạn thảo một báo cáo sự cố hoặc lỗi chi tiết và rõ ràng có thể đóng vai trò quyết định trong việc khắc phục sự cố. Dưới đây là hướng dẫn cách gửi một báo cáo lỗi chi tiết và rõ ràng đến BeeWare Docs Tools.

Tìm kiếm các vấn đề hiện có

Trước khi gửi một vấn đề mới, hãy tìm kiếm trong danh mục các vấn đề hiện có tương tự với vấn đề của bạn. Nếu có một vấn đề đang mở nào đó dường như trùng khớp với vấn đề của bạn, hãy thêm bình luận vào vấn đề đó kèm theo bất kỳ thông tin bổ sung nào về trường hợp cụ thể của bạn. Ví dụ: nếu bạn gặp vấn đề này trên một phiên bản Python khác hoặc hệ điều hành khác, những thông tin bổ sung đó có thể hữu ích trong việc xác định mức độ ảnh hưởng hoặc nguyên nhân của vấn đề.

Nếu bạn tìm thấy một vấn đề đã đóng có vẻ trùng khớp với vấn đề của bạn, hãy kiểm tra xem vấn đề đó mới được đóng cách đây bao lâu. Nếu vấn đề đó mới được đóng gần đây, điều đó có nghĩa là lỗi của bạn đã được khắc phục và sẽ được sửa trong bản phát hành tiếp theo. Nếu vấn đề đó đã được đóng cách đây hơn 4 tháng, rất có thể vấn đề bạn đang gặp phải là một vấn đề khác — dù thông báo lỗi có vẻ giống nhau đến đâu đi chăng nữa.

Nếu bạn không tìm thấy vấn đề nào phù hợp với tình huống bạn đang gặp phải, bạn nên tạo một vấn đề mới.

Bắt đầu bằng một cuộc thảo luận

Trước khi gửi báo cáo lỗi trên GitHub, bạn nên cân nhắc bắt đầu bằng một cuộc thảo luận để xác định xem vấn đề bạn đang gặp phải thực sự là một lỗi hay chỉ là sự cố liên quan đến cấu hình hoặc quy trình của bạn. Trừ khi bạn gặp phải hành vi trái ngược hoàn toàn với những gì đã được ghi chép, thì tốt nhất bạn nên đặt câu hỏi trước khi vội vàng gửi báo cáo lỗi. Nếu hóa ra bạn thực sự đã phát hiện ra một lỗi, chủ đề thảo luận đó có thể dễ dàng được chuyển thành một báo cáo lỗi.

Việc mở một cuộc thảo luận cũng có thể giúp đảm bảo rằng bạn đang báo cáo sự cố tại nơi thích hợp nhất. Mặc dù bạn có thể đã gặp phải sự cố khi sử dụng BeeWare Docs Tools, nhưng nguyên nhân có thể là do một lỗi trong một dự án khác thuộc hệ sinh thái BeeWare.

Cách viết một báo cáo lỗi hiệu quả

Nếu thực sự cần tạo một báo cáo lỗi mới, điều quan trọng là phải cung cấp càng nhiều chi tiết càng tốt. Một báo cáo lỗi tốt cần bao gồm tất cả thông tin có thể liên quan đến lỗi, cũng như ví dụ tái hiện đơn giản nhất có thể.

Ví dụ tái hiện lỗi cần phải ngắn gọn và súc tích nhất có thể, đồng thời vẫn thể hiện được lỗi. Việc cung cấp một ví dụ quá dài dòng sẽ khiến việc khắc phục sự cố trở nên khó khăn hơn đáng kể, đặc biệt nếu ví dụ đó phụ thuộc vào các thư viện khác hoặc đòi hỏi kiến thức sâu rộng về hành vi dự kiến hoặc logic nội bộ của ví dụ.

Chúng tôi cần quý vị cung cấp càng nhiều chi tiết càng tốt. Điều này bao gồm, nhưng không chỉ giới hạn ở:

  • Phiên bản hệ điều hành của bạn – bao gồm cả phiên bản phụ (ví dụ: macOS 15.7.2).
  • Phiên bản Python của bạn, bao gồm cả phiên bản phụ (ví dụ: 3.14.1).
  • Bạn đã cài đặt Python như thế nào? Bạn đã tải xuống từ python.org chưa? Bạn đã sử dụng Homebrew chưa? uv? pyenv? conda? Hay cách nào khác?
  • Bạn đang sử dụng phiên bản cụ thể nào của bộ công cụ BeeWare (ví dụ: Toga 0.5.3)? Nếu bạn đang sử dụng phiên bản phát triển, mã băm Git cụ thể là gì? Chỉ nói "nhánh chính hiện tại" là chưa đủ, vì nhánh này có thể thay đổi hàng ngày.
  • Các phiên bản cụ thể của các gói phần mềm khác cần phải được cài đặt để tái hiện sự cố. Bạn có thể đính kèm kết quả của lệnh python -m pip freeze để cung cấp thông tin này.
  • Nếu tệp nhật ký đã được tạo, thì đó là toàn bộ tệp nhật ký.
  • Nếu đã tạo được bản ghi dấu vết ngăn xếp, hãy cung cấp toàn bộ bản ghi đó. Đừng chỉ cung cấp thông báo lỗi cuối cùng – bối cảnh đầy đủ của bản ghi dấu vết ngăn xếp là rất quan trọng. Tốt nhất là bạn nên cung cấp thông tin này dưới dạng văn bản, không phải dưới dạng ảnh chụp màn hình.
  • Còn điều gì khác liên quan đến cấu hình máy tính hoặc mạng của bạn có thể ảnh hưởng đến vấn đề này không? Máy tính của bạn có phải là máy cũ hoặc chạy chậm không? Đây có phải là máy tính công sở có cài đặt tường lửa, phần mềm diệt virus hoặc các hạn chế khác không? Mạng của bạn có đặc biệt chậm không? Bạn có đang sử dụng hệ điều hành với các cài đặt mặc định bất thường (chẳng hạn như phông chữ rất lớn hoặc đã kích hoạt một số công nghệ hỗ trợ khác) không?

Hãy thử suy nghĩ một cách sáng tạo và liệt kê tất cả những yếu tố mà bạn có thể nghĩ ra có thể ảnh hưởng đến vấn đề bạn đang gặp phải. Nếu bạn cung cấp cho chúng tôi nhiều thông tin hơn mức cần thiết, chúng tôi có thể dễ dàng loại bỏ những thông tin không cần thiết. Chúng tôi không thể tự mình nghĩ ra những điều mà bạn đã bỏ sót.

Một ví dụ đơn giản

Phần quan trọng nhất của một báo cáo lỗi là trường hợp tái hiện tối thiểu. Một bên thứ ba phải có thể đọc hướng dẫn về trường hợp tái hiện của bạn, làm theo các hướng dẫn đó và quan sát thấy cùng một vấn đề. Điều này có thể có nghĩa là cung cấp một dự án mẫu thể hiện vấn đề — hoặc, tốt hơn nữa, sử dụng một ví dụ có sẵn (chẳng hạn như một hướng dẫn hoặc dự án mẫu là một phần của cơ sở mã hiện có).

Toàn bộ dự án của bạn không phải là một trường hợp tái hiện tối thiểu. Một trường hợp tái hiện tối thiểu không được chứa bất kỳ đoạn mã nào không thực sự cần thiết để tái hiện lỗi. Hãy thật khắt khe khi xây dựng trường hợp tái hiện của bạn — nếu một nút bấm không cần thiết để tái hiện lỗi, đừng đưa nút đó vào.

Thông thường, quá trình xây dựng trường hợp tái hiện tối thiểu này sẽ giúp làm rõ nguyên nhân gốc rễ của vấn đề, bởi vì việc tạo ra ví dụ tối thiểu buộc bạn phải xác định chính xác điều gì đang gây ra sự cố, cho dù đó là lỗi trong mã nguồn hay xuất phát từ những giả định sai lầm hoặc cách sử dụng API không đúng.

Bạn cũng nên nêu rõ ràng các hướng dẫn để tái hiện sự cố. Câu nói "Đóng ứng dụng mẫu" có thể có nghĩa là nhấp vào nút đóng trên cửa sổ, chọn "Thoát" từ menu hoặc nhấn phím tắt Control-C trong cửa sổ terminal. Báo cáo của bạn không nên để lại bất kỳ sự mơ hồ nào về những bước cần thực hiện để tái hiện sự cố.

Gửi báo cáo

Truy cập vào BeeWare Docs Tools danh sách các vấn đề, nhấp vào nút "Tạo vấn đề mới" và chọn "Báo cáo lỗi" để bắt đầu quy trình.

Bạn phải điền đầy đủ tất cả các mục trong mẫu báo cáo sự cố. Chúng tôi cung cấp mẫu này như một hướng dẫn để giúp bạn cung cấp các thông tin cần thiết. Hãy nhớ rằng, bạn luôn có thể (và nên!) cung cấp thêm thông tin ngoài những gì mẫu yêu cầu, nhưng ít nhất, chúng tôi cần tất cả các thông tin có trong mẫu.

Khi đính kèm mã nguồn, nếu bạn có thể tái hiện vấn đề bằng một ví dụ có sẵn, chẳng hạn như hướng dẫn của BeeWare, bạn có thể cung cấp liên kết. Nếu không, hãy đính kèm mã nguồn trực tiếp trong báo cáo. Mã nguồn cần được định dạng theo cú pháp Markdown; mỗi khối mã cần có ba dấu gạch chéo ngược (```) ở đầu và cuối.

Nếu bạn cần chèn một đoạn văn bản dài, bạn có thể ẩn đoạn văn bản đó đi bằng cách sử dụng cú pháp sau:

<details>
<summary>Tiêu đề nội dung đã thu gọn</summary>
Đoạn văn bản dài.
</details>

Sau khi đã cung cấp đầy đủ thông tin nhất có thể, hãy nhấp vào "Tạo" để gửi báo cáo.

Sử dụng GitHub CLI để tạo một vấn đề

Việc sử dụng trực tiếp GitHub CLI (gh) sẽ bỏ qua các mẫu mà chúng ta đã tạo. Các mẫu này được thiết kế để đảm bảo rằng chúng ta sẽ có đầy đủ thông tin cần thiết để xử lý vấn đề.

Nếu bạn định sử dụng gh để tạo một vấn đề mới, vui lòng làm theo hướng dẫn sau:

gh issue create --web

Sử dụng --web sẽ mở trình duyệt đến trang mẫu vấn đề và cho phép bạn tạo một vấn đề bằng cách sử dụng mẫu phù hợp.

Đề xuất một tính năng 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.