Hướng dẫn cho người đóng góp
Cách hoàn thành pull request đầu tiên của bạn
Con đường ngắn nhất mà vẫn đáng tin cậy: từ lúc tìm được một issue phù hợp với người mới đến khi pull request của bạn sẵn sàng cho maintainer và được merge.
Bắt đầu từ đây
Chọn điểm xuất phát của bạn
Chọn mức đúng với tình trạng hiện tại của bạn, rồi đi theo cùng các giai đoạn bên dưới.
Hoàn toàn mới
Bắt đầu với công cụ, thuật ngữ và một thay đổi chỉ liên quan đến tài liệu. Mục tiêu của bạn là đi trọn một vòng an toàn.
PR đầu tiên trong đời
Chọn một issue thật nhỏ, còn mới, và giữ cho diff tập trung. Hãy hỏi xác nhận trước khi bắt tay vào viết code.
Người đóng góp quay lại
Dùng bản hướng dẫn này như một checklist, rồi dồn phần lớn sức lực vào việc tái hiện lỗi và kiểm thử bản sửa.
Giai đoạn 0
Cài các công cụ cơ bản
Bạn chỉ cần đủ công cụ trên máy để clone kho mã nguồn, tạo một branch, chạy các bước kiểm tra của dự án và push phần việc của mình.
git
Git theo dõi công việc của bạn và cho maintainer thấy chính xác những gì đã thay đổi.
git --versiongh
GitHub CLI giúp bạn fork, clone, xác thực và mở pull request mà không cần rời terminal.
gh auth login
gh repo fork OWNER/REPO --clone --remoteTrình soạn thảo
Dùng một trình soạn thảo có thể tìm kiếm trong toàn bộ kho mã nguồn, chạy formatter và hiển thị rõ các tệp đã thay đổi.
code .Giai đoạn 1
Chọn đúng issue
Một good first issue không chỉ là nhỏ. Nó còn phải còn hiệu lực, dễ hiểu, và có thể được review bởi người đang thực sự bảo trì dự án.
-
Nhận việc
Để lại một bình luận ngắn, nêu đúng issue bạn muốn làm và hỏi xem phạm vi đó còn hợp lý không.
-
Đọc các quy định
Đọc CONTRIBUTING, README, các pull request đang mở, lệnh chạy test và ghi chú về phong cách code trước khi sửa code.
-
Fork + branch
Tạo bản sao của riêng bạn và làm việc trên một branch đặt tên theo nhiệm vụ, đừng làm trên main.
-
Cài đặt + tái hiện
Cài các phụ thuộc, tái hiện vấn đề, và ghi lại câu lệnh hoặc màn hình nơi bạn thấy nó.
-
Gửi một diff thật nhỏ
Chỉ sửa lượng code tối thiểu cần thiết. Tránh tiện tay refactor, nâng cấp phụ thuộc hay định dạng lại những chỗ không liên quan.
-
Mở PR
Giải thích bạn đã thay đổi gì, đã kiểm thử ra sao và còn giới hạn nào. Hãy làm cho lượt đọc đầu tiên của người review thật nhẹ nhàng.
Điểm dừng
Dấu hiệu cảnh báo trước khi bạn bỏ thêm thời gian
Dừng sớm vẫn tốt hơn là cố ép ra một pull request không thể review được.
- Bạn không chạy được dự án trên máy dù đã làm theo đúng hướng dẫn cài đặt.
- Bản sửa buộc bạn phải đoán hành vi của sản phẩm mà không có ý kiến từ maintainer.
- Issue yêu cầu một tính năng lớn, một đợt thiết kế lại, một cuộc di trú hay một quyết định về kiến trúc.
- Maintainer đã đề nghị người đóng góp lần đầu không làm ở khu vực này.
Tra cứu
Thuật ngữ
- Fork
- Bản sao riêng của bạn từ một kho mã nguồn. Bạn push branch của mình lên đó trước khi mở pull request.
- Branch
- Một mạch công việc có thể di chuyển. Hãy dùng một branch cho mỗi issue để thay đổi của bạn luôn dễ review.
- Pull request
- Lời đề nghị để maintainer review và merge branch của bạn vào kho mã nguồn của dự án.
- Diff
- Tập thay đổi nhỏ nhất mà vẫn có ý nghĩa, giải quyết được issue và không kèm dọn dẹp ngoài lề.
- CONTRIBUTING
- Checklist riêng của từng dự án về cài đặt, phong cách code, test và những gì dự án mong đợi ở một pull request.
FAQ
Những câu hỏi thường gặp về PR đầu tiên
Nếu sau một tuần maintainer vẫn chưa trả lời thì sao?
Hãy gửi một lời nhắc ngắn gọn, nêu tình trạng hiện tại và một câu hỏi trực tiếp. Nếu vẫn không có hồi âm, hãy chọn issue khác thay vì chờ đợi vô thời hạn.
Tôi nên làm gì khi cài đặt thất bại?
Nói rõ bạn đã thử những gì, dán nguyên văn thông báo lỗi, kèm hệ điều hành và phiên bản công cụ, rồi hỏi bước gỡ lỗi tiếp theo.
PR đầu tiên của tôi có thể chỉ sửa tài liệu không?
Được, nếu kho mã nguồn hoan nghênh các thay đổi về tài liệu. Làm tài liệu rõ hơn, thêm ví dụ, sửa lỗi chính tả và liên kết hỏng đều là những đóng góp chính đáng.