1. Clone repository
2. Làm việc với repository
3. Cách PhysX-CNH hoạt động

Để bắt đầu làm việc với nền tảng PhysX-CNH, người dùng hoặc người đóng góp cần clone repository PhysX-CNH. Clone về cơ bản là một hành động để tạo một bản copy của repository trên máy tính cá nhân của người dùng.

Hiện nay người dùng có thể clone repository bằng Git CLI hoặc Github CLI, tuy người dùng có thể "clone" bằng cách tải repository về thông qua trình duyệt, nhưng dùng phương pháp này không đảm bảo người dùng có thể đóng góp cho dự án về sau do dù sao nếu thiếu các CLI thì cũng không thể làm việc với repo git được.

Bắt đầu với việc đi đến đường dẫn mà người dùng muốn lưu repository tại đó và khởi chạy Command Prompt hoặc khởi chạy Command Prompt rồi cd tới đường dẫn.

Đầu tiên ,bạn phải fork repo này thành một repo cá nhân của bạn, truy cập vào đường dẫn này. Sau khi đã fork repo, bạn sẽ clone repo này về máy

Clone repository chỉ cần sử dụng 1 dòng lệnh cơ bản

Với Git CLI, lệnh clone repository PhysX-CNH là

git clone https://github.com/<username>/physx-cnh.git

Với Github CLI, lệnh clone có khác biệt

gh repo clone <username>/physx-cnh

Với <username> là tên người dùng GitHub của bạn

Sau khi repository đã được clone hoàn chỉnh, sử dụng một trình IDE, có thể là Visual Studio Code và mở cả tệp của repository.

Đầu tiên, để việc người dùng thực hiện thay đổi lên phiên bản clone repository có ý nghĩa, người dùng cần tạo một branch riêng cho bản thân để thực hiện các thay đổi.

git checkout -b <branch_name> 

Khi thực hiện các thay đổi trên repository đã clone về, người dùng không thực hiện thay đổi trực tiếp lên repository PhysX-CNH mà chỉ đang thay đổi các tệp tin được lưu trên máy tính, nói cách khác là lên branch của bản thân. Tại thời điểm này, nếu thực hiện đóng góp nội dung hay sửa đổi, branch của người dùng sẽ cần được commit, push và merge vào repository gốc.

Nếu người dùng sử dụng các trình IDE có tính năng Source Control thì có thể dễ dàng theo dõi và quản lý các thay đổi này, ví dụ như với Visual Studio Code

Đối với Git và Github CLI, người dùng phải thêm các thay đổi một cách thủ công, sau đó mới có thể theo dõi thay đổi mình đã thực hiện (so sánh với branch gốc master trên repository PhysX-CNH)

Ví dụ, bổ sung một tệp tin test.txt vào thư mục chính của repository, người dùng cần thực hiện việc đẩy thay đổi vào staging area

git add test.txt

Sau đó, để có thể xem thay đổi mà mình đã thực hiện

git diff master

Kết quả của ví dụ trên sẽ nhìn thế này

D:\physx-cnh>git diff master
diff --git a/test.txt b/test.txt
new file mode 100644
index 0000000..e69de29

Nếu người dùng muốn huỷ bỏ thay đổi, tức là đưa tệp tin test.txt ra khỏi staging area

git reset HEAD test.txt

Nếu sử dụng IDE có Source Control, các bước trên sẽ hoàn toàn được làm tự động.

Sau khi đã thực hiện các thay đổi, để thực hiện việc commit dễ dàng nhất, khuyến cáo người dùng nên sử dụng lệnh stage

git add -p

Lệnh stage này sẽ chỉ đưa các thay đổi mà người dùng thực hiện vào staging area thay vì đưa vào toàn bộ repository.

Sau đó người dùng sẽ được review các thay đổi mình đã thực hiện, y để đồng ý stage thay đổi

Ví dụ với thay đổi lên tệp lessons.txt

D:\physx-cnh>git add -p
diff --git a/physics/lessons.txt b/physics/lessons.txt
index 52c0184..6c9adb6 100644
--- a/physics/lessons.txt
+++ b/physics/lessons.txt
@@ -8,4 +8,5 @@ Luyện tập<br>23/08/24| |/lessons/train_230824.pdf|
 Luyện tập<br>29/08/24| |/lessons/train_290824.pdf|
 Luyện tập<br>30/08/24| |/lessons/train_300824.pdf|
 Giải bài hạt mưa| |/lessons/exercise_raindrop.pdf|
-Giải bài căng dây - vòng 2 TP| |/lessons/exercise_tensionstring.pdf|
\ No newline at end of file
+Giải bài căng dây - vòng 2 TP| |/lessons/exercise_tensionstring.pdf|
+ádasdasd
\ No newline at end of file
(1/1) Stage this hunk [y,n,q,a,d,e,p,?]?

Sau khi đã xem lại toàn bộ thay đổi và stage những thay đổi, người dùng sẽ commit thay đổi này lên branch riêng của bản thân

git commit -m "Change"

Và push thay đổi này lên hệ thống của Github

git push

Cuối cùng ,các bạn quay lại nền tảng Github, tới branch của bạn vừa push và tạo pull request, chọn branch của bạn là nguồn (source) và branch master của tôi là target. Thực hiện yêu cầu pull request rồi Submit.

Ví dụ dưới là giao diện của một pull request

Người dùng khi đóng góp nội dung cần nêu rõ mình thay đổi những gì. Sau khi thực hiện Submit pull request, cá nhân Văn Thành Duy sẽ review thay đổi mà người dùng đã thực hiện, nếu đạt yêu cầu, branch của người dùng sẽ được merge vào branch chính.

Người dùng khi thực hiện thay đổi và muốn đóng góp vào branch chính master cần tuân thủ một số quy tắc để đóng góp có thể được thông qua.

• Chỉ đóng góp về mặt nội dung, tức là bổ sung các tệp PDF, web clone, và thực hiện các thay đổi phù hợp với đóng góp
• Không push lên các nội dung nhạy cảm không liên quan đến dự án
• Không thực hiện thay đổi lên codebase, tức là các file script PHP, style CSS, JavaScript, HTML.

Cụ thể cách thức thực hiện các đóng góp, vui lòng xem ở mục 3 wiki.