Quy Trình Sử Dụng Git

Dành cho Lập Trình Viên

Fork SINGA Github repository về tài khoản Github của bạn.

Clone repo (viết tắt của repository) từ tài khoản Github của bạn

git clone https://github.com/<Github account>/singa.git
git remote add upstream https://github.com/apache/singa.git

Tạo branch mới (vd., feature-foo hoặc fixbug-foo), chỉnh sửa và commit code của bạn ở đây .
```
git checkout dev
git checkout -b feature-foo
# write your code
git add <created/updated files>
git commit
```
Nội dung lệnh commit nên bao gồm:
- Tiêu đề (Title) mô tả.
- Mô tả chi tiết. Nếu lệnh commit là sửa lỗi (bugs), tốt nhất là nên bao gồm việc mô tả ngắn gọn lại vấn đề. Nếu thêm tính năng mới, có thể bao gồm động cơ thúc đẩy/mục đích của tính năng mới này.
Nếu branch của bạn có nhiều commits nhỏ, bạn cần súc tích lại các commits bằng cách
```
git rebase -i <commit id>
```
Bạn có thể squash và reword các commits.
Khi bạn đang xử lý các mã code, branch dev của SINGA có thể đang được cập nhật bởi người khác; Trong trường hợp này, bạn cần pull dev mới nhất
```
git checkout dev
git pull upstream dev:dev
```
Rebase feature-foo vào branch dev và push commits vào tài khoản Github của bạn ( branch mới). Lệnh rebase nhằm giúp cho lịch sử commit của bạn rõ ràng. Các lệnh git dưới đây nên được thực hiện sau khi bạn commit các việc làm của mình:
```
git checkout feature-foo
git rebase dev
git push origin feature-foo:feature-foo
```
Lệnh rebase thực hiện các bước sau: "Lệnh này thực hiện bắt đầu từ hình thái ban đầu của hai branches (mà bạn đang sử dụng hoặc bạn đang rebase vào), xác định sự khác nhau ở mỗi commit của branch bạn đang sử dụng, lưu các điểm khác nhau vào tập tin tạm thời, điều chỉnh branch hiện tại để có cùng commit với branch mà bạn đang rebase vào, rồi cuối cùng áp dụng từng thay đổi một theo thứ tự." Bởi vậy, sau khi thực hiện, bạn sẽ vẫn ở feature branch, nhưng commit IDs/hashes của bạn được thay đổi do các điểm khác nhau đã được commit trong quá trình rebase; và branch của bạn giờ đây chứa bản code cập nhật nhất từ branch dev và branch của bạn.
Tạo một pull request (PR) vào branch dev của apache/singa trên website Github. Nếu bạn muốn thông báo cho các thành viên khác đang làm việc trên cùng một tập tin, bạn có thể tìm tập tin đó trên Github và nhấn vào "Blame" để xem chú thích từng dòng một ai đã thay đổi code lần cuối cùng. Sau đó, bạn có thể thêm @username trong mục mô tả PR để nhắc họ. Hãy nói rõ rằng những đóng góp này là công sức của bạn và rằng bạn cấp bản quyền công sức này cho dự án theo dạng bản quyền dự án mở. Những commits khác (vd., sửa lỗi) vào branch mới này sẽ được tự động cập nhật vào pull request của bạn bởi Github.
Đợi thành viên xét duyệt PR. Trong quá trình này, dev branch của SINGA có thể được những người khác cập nhật, do vậy bạn cần phải merge the latest dev để xử lý các conflicts. Một số người rebase PR vào branch dev mới nhất thay vì merging. Tuy nhiên, nếu các thành viên khác fetch PR này để thêm các tính năng mới rồi gửi PR, việc rebase sẽ gây ra duplicate commits (với hash khác) ở PR mới. Xem Nguyên tắc vàng để Rebasing để biết thêm chi tiết khi nào cần tránh rebase. Một giải pháp đơn giản để cập nhật PR (nhằm xử lý conflicts hay lỗi commit) là checkout một branch mới từ branch dev cập nhật nhất của Apache SINGAS repo; copy và paste các mã code được cập nhật/thêm vào; commit và gửi một PR mới.

Dành cho commiters

Commiters có thể merge pull requests (PRs) vào dev branch của repo upstream. Trước khi merge mỗi PR, committer nên

kiểm tra thông điệp commit (nội dung và định dạng)
kiểm tra những thay đổi so với code hiện tại. Thay đổi về API nên được ghi lại.
kiểm tra kết quả Travis testing cho định dạng mã code/tài liệu và unit tests

Có hai cách để merge một pull request:

Trên Github. Làm theo hướng dẫn để kết nối tài khoản Apache với tài khoản Github của bạn. Sau đó bạn có thể trực tiếp merge PRs trên GitHub.

Để merge pull request https://github.com/apache/singa/pull/xxx qua command line, thực hiện theo hướng dẫn sau:

git clone https://github.com/apache/singa.git
git remote add asf https://gitbox.apache.org/repos/asf/singa.git
git fetch origin pull/xxx/head:prxxx
git checkout dev
git merge --no-ff prxxx
git push asf dev:dev

Không sử dụng rebase để merge PR; và vô hiệu hoá fast forward.