Bỏ qua

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.