Hướng dẫn bắt đầu cho người mới để đóng góp cho dự án trên GitHub

Đây là hướng dẫn để đóng góp vào các project mã nguồn mở sử dụng Github. Nó hầu hết được dựa trên cái cách mà tôi đã thấy Zend Framework, Slim Framework và joind.in hoạt động. Tuy nhiên, đây là một hướng dẫn chung, vì thể hãy đọc lại các file README của project để biết cụ thể hơn.

Step 1: Thiết lập working copy ở máy tính của bạn

Đầu tiên bạn cần local fork của project, vì thế hãy thực hiện bấm vào nút fork ở GitHub. Nó sẽ tạo ra một bản copy của repository trong tài khoản GitHub của chính bạn và bạn sẽ thấy một dòng chú thích nhỏ rằng nó đã bị fork ở bên dưới tên của project:

Giờ đây bạn cần copy locally, vì thế hãy tìm “SSH clone URL” ở phía bên phải và sử dụng clone locally sử dụng dòng lệnh:

$ git clone git@github.com:akrabat/zend-validator.git

Lệnh trên sẽ thực hiện một số việc như sau:

Di chuyển tới thư mục của project mới:

$ cd zend-validator

Cuối cùng, trong giai đoạn này, bạn cần thiết lập remote mới mà trỏ tới project gốc để bạn có thể lấy về bất kỳ thay đổi nào và chuyển nó về local copy của bạn. Đều tiên hãy vào link ở repository gốc, nó sẽ có nhãn là “Forked from” ở trên cùng của GitHub page. Nó sẽ đưa bạn trở lại trang GitHub chính của projects, vì thế bạn có thể tìm thấy “SSH clone URL” và sử dụng nó để tạo ra remote mới, cái này chúng ta sẽ gọi là upstream.

$ git remote add upstream git@github.com:zendframework/zend-validator.git

Bạn giờ đây sẽ có 2 remote cho project này trên ổ đĩa:

origin là trỏ về GitHub fork của project của bạn. Bạn có thể đọc và ghi vào remote này.
upstream trỏ tới kho Github của project chính. Bạn chỉ có thể đọc từ remote này.

Step 2: Do some work

Bước này bạn sẽ đóng góp vào project. Thường tốt nhất là nên bắt đầu fixing bug mà gây khó chịu với bạn hoặc bạn thấy trong issue tracker của project. Nếu bạn thấy chỗ đễ bắt đầu, rất nhiều project sử dụng “easy pick” label (hoặc một vài biến thể) để chỉ ra rằng issue này có thể được chỉ ra bởi một ai đó mới đối với project.

Hãy phân nhánh : Branch!

Luật lệ số một là hãy đưa từng phần công việc vào branch riêng của nó. Nếu project đang sử dụng git-flow, thì nó sẽ có cả branch master và develop. Luật lệ thông thường là nếu bạn là bug fixing, thì hãy tạo branch từ master và nếu bạn đang add thêm feature thì tạo branch từ develop. Nếu project chỉ có master branch, hãy tạo branch từ nó. Một vài project, như Slim sử dụng các branches được đánh tên đằng sau version number (2.x và 3.x trong trường hợp của Slim). Trong trường hợp này, hãy chọn branch mà có liên quan.

For this example, we’ll assume we’re fixing a bug in zend-validator, so we branch from master:

Đối với ví dụ này, ta sẽ giả sử rằng ta đang fixing bug trong zend-validator vì thế ta sẽ tạo branch từ master:

$ git checkout master
$ git pull upstream master && git push origin master
$ git checkout -b hotfix/readme-update

Đầu tiên chúng ta phải đảm bảo rằng chúng ta đang ở master branch. Sau đó lệnh git pull sẽ đồng bộ local copy của chúng ta với upstream project (lấy dữ liệu từ upstream project về) và git push sẽ đồng bộ (ghi vào) nó với project mà chúng ta đã fork. Cuối cùng, chúng ta tạo ra một branch mới. Bạn có thể đặt tên branch của bạn tùy ý thích, nhưng để giúp phân biệt nó nên được đặt có ý nghĩa. Thông thường tên của branch mà có chứa issue number là hữu ích. Nếu project mà sử dụng git-flow như là zend-validator đã sử dụng, thì chúng có các quy ước đặt tên cụ thể ở đó các branch được đặt tiền tố với “hotfix/“ hoặc là “feature/“.

Bây giờ hãy làm công việc của bạn. Chỉnh sửa các thứ.

Đảm bảo rằng bạn chỉ fix các thứ bạn đang tập trung làm việc. Đừng cố gắng fix những thứ gì khác mà bạn thấy trong khi fix thứ ban đầu, bao gồm các vấn đề về định dạng, nếu làm vậy thì Pull Request của bạn có thể sẽ bị rejected.

Hãy đảo bảo rằng bạn commit trong các khối logic. Từng commit message nên rõ ràng. Hãy đọc thêm ghi chú của Tim Pope về Git Commit Messages

Step 3: Hãy tạo ra Pull Request

Để tạo ra PR bạn cần phải push branch của bạn lên origin remote và sau đó bấm vào một vài nút trên giao diện của Github.

Để push một branch mới:

$ git push -u origin hotfix/readme-update

Chúng sẽ tạo ra branch trên GitHub project của bạn. Tùy chọn flag -u sẽ link branch này với remote, vì thế trong tương lại, bạn có thể chỉ cần đơn giản là gõ git push origin.

Hãy trở lại trình duyệt và di chuyển tới fork của project (trong trường hợp này là https://github.com/akrabat/zend-validator) và bạn sẽ thẩy rằng branch mới được liệt kê lên đầu với một nút bấm tiện lợi “Compare & pull request”.

Hãy tiếp tục và bấm vào nút!

Bạn sẽ thấy một khung màu vàng như sau:

Click vào link sẽ đưa bạn tới file CONTRIBUTING của project và hãy đọc nó! Nó bao gồm nhiều thông tin giá trị về cách thức làm việc với project code base và sẽ giúp các đóng góp của bạn được chấp nhận.

Ở trang này, đảm bảo rằng “base fork” trỏ tới repository và branch chính xác. Sau đó đảm bảo rằng bạn cung cấp các tiêu để tốt, cô đọng cho pull request và giải thích tại sao bạn đã tạo ra nó trong phần mô tả bên dưới. Thêm vào bất kỳ các issue numbers nếu bạn có.

Nếu bạn cuộn xuống dưới, bạn sẽ thấy các diff thay đổi của bạn. Hãy kiểm tra lại rằng nó chứa những gì bạn mong đợi.

Một khi bạn đã “happy”, hãy bấm “Create pull request” và bạn đã xong công việc.

Step 4: Review by the maintainers

Step 4: Review lại bởi các maintainers

Đối với các công việc của bạn được tích hợp vào project, các người bảo trì (maintainers) sẽ review lại công việc của bạn và sẽ request change hoặc sẽ merge nó.

Bài viết của Lorna Mitchell Code Reviews: Before You Even Run The Code cover lại các việc mà các maintainer sẽ nhìn vào, vì thế hãy đọc nó và đảm bảo rằng bạn đã thực hiện chúng thuận lợi nhất có thể.

Tổng kết lại

Trên đây là toàn bộ về nó. Các bước cơ bản là:

1. Hãy fork project và clone nó về local.
2. Tạo ra các upstream remote vào sync nó với local copy trước khi bạn tạo branch.
3. Hãy tạo branch cho từng các phần công việc rời rạc.
4. Thực hiện công việc, viết các commit message tốt, và đọc file CONTRIBUTING nếu chúng tồn tại.
5. Push vào origin repository của bạn.
6. Hãy tạo ra PR mới trong Github.
7. Respond to any code review feedback.
8. Hãy trả lời bất kỳ code review feedback gửi tới.

Nếu bạn muốn đóng góp vào open source project, tốt nhất là bạn hãy chọn cái nào mà bạn đang sử dụng cho riêng mình. Các maintainers sẽ biết ơn về điều đó.


Nguồn:

https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/

​