Lời khuyên quý giá khi phải commit code vào project của người khác?

Tôi từng nghĩ rằng việc thay đổi chỉ “một dòng code” để fix một bug nhỏ sẽ không ảnh hưởng đến toàn bộ chương trình lớn. Tuy nhiên việc này có lẽ là chưa đúng, nhất là khi project đó có tuổi đời lớn và sự thay đổi của các nền tảng và hệ thống thì sẽ sinh ra hàng loạt các công việc khác phát sinh.

Vấn đề gần đây nhất tôi gặp phải đó là với Snyk:

Tôi đọc và nhanh chóng nhận ra rằng dòng code ở trên giúp tôi fix một bug nhỏ trong chương trình. Tuy nhiên, để chứng minh là nó hoàn toàn đúng và không phát sinh lỗi trong tương lai, tôi phải có được một bộ test cases thực sự hoàn chỉnh để chạy thử.

Tất cả các project của tôi đều sử dụng semantic release để tự động hóa quá trình kiểm duyệt dựa trên commit message. Do đó, những việc còn lại phải làm, là đưa hết các dependencies vào Snyk, commit và đảm bảo rằng commit message phải đúng format để semantic có thể hoạt động.

Và bạn thấy đấy, việc thay đổi một dòng code không đơn giản chỉ như vậy: một dòng code mới -> cần một bộ test mới -> test trên cả 4 phiên bản của node -> đưa hết các dependencies vào project thứ cấp -> đảm bảo rằng commit messages đúng -> chờ đợi project thứ cấp vượt qua tất cả các test trước khi nó tự động được đưa lên

... thường là rất mệt mỏi, nhất là khi bạn đang pull request vào project của một người khác. Ngay chính tôi, một người có khá nhiều kinh nghiệm, cũng không ít lần bỏ cuộc khi phải tuân thủ cả đống những yêu cầu quá phức tập của owner. Thử đặt mình vào vị trí của contributor, chắc chắn là các bạn cũng sẽ có cảm giác tương tự như tôi.

Tôi đã làm những gì để thay đổi điều đó?

Thật may mắn là gần đây, Github có một bài hướng dẫn cho người dùng để tự lập một form biểu mẫu về những yêu cầu cần được thông qua mỗi khi thực hiện một pull request hay report một vấn đề với owner (issue and pull request template).

Dưới đây là một template được tôi dùng cho Snyk:

-[ ]Sẵn sàng để review

-[ ]Tuân thủ đúng quy tắc contributing

-[ ]Đã được review bởi @remy(Snyk team)

##Mục đích của pull request là gì?

##Người xem nên bắt đầu từ đâu

##Làm sao để có thể kiểm tra bằng tay

##Bạn có bất cứ thông tin nào muốn cung cấp thêm

##

##Ảnh chụp màn hình

Câu hỏi thêm cho owner

Template này được tôi lập dựa trên template mẫu trên QuickLeft. Những yêu cầu ở trên đây đều không quá khó khăn để thực hiện nhưng vẫn đảm bảo cung cấp cho tôi một lượng thông tin cần thiết trước khi đưa ra quyết định cho mình

Ngoài ra, việc có tệp tin CONTRIBUTING.md ở trong thư mục gốc của repository (hoặc trong .github) thì mỗi khi có các issues hay pull requests mới, thông báo sẽ xuất hiện ngay trên header.

Trong bối cảnh này: semantic release sẽ đọc các cam kết trong một nỗ lực để làm chủ, và nếu có một kỳ tích, cam kết sẽ trở thành một phiên bản thứ yếu. Nếu có sự chỉnh sửa, nó sẽ trở thành một phiên bản thay thế. Nếu văn bản có sự thay đổi lớn, nó sẽ xuất hiện trong phần thân của bản cam kết, nó sẽ là bản chính.

Việc sử dụng semantic release trong tất cả các project của mình giúp tôi chỉ cần đảm bảo rằng, chừng nào commit message còn đúng theo format của semantic release thì mọi công việc sẽ đều được thực hiện một cách tự động

Vậy làm sao để đảm bảo commit message của contributor đều sẽ đúng format?

Ghooks là một trong những giải pháp hữu hiệu cho việc đó, sử dụng commit-msg để kích hoạt validate-commit-msg. Bạn không cần tốn quá nhiều thời gian để cài đặt và sử dụng nó để hướng dẫn người dùng sử dụng câu lệnh commit theo đúng format.

Dưới đây là giao diện của ghook trên command line:

... còn đây là những gì hiện trên giao diện của người dùng:

Việc này giúp cho công việc của cả tôi và contributors trở nên đơn giản và dễ hiểu hơn nhiều. Ngoài ra, tôi còn cẩn thận thêm vào một pre-push hook để đảm bảo chương trình đó phải vượt qua tất cả các test trước khi được push lên Github.

Việc tạo test cho chương trình là không hề đơn giản, nhất là đối với những người không hoàn toàn tạo nên chương trình đó. Ví dụ như bạn phải hiểu rõ cấu trúc của một bộ test (input, output), nắm được code của ứng dụng,  phương thức test, mô phỏng môi trường test,vv..

Để xử lý việc này, bạn có thể không cần yêu cầu contributor phải nhất viết tự viết test code, thay vào đó hãy tự viết một chương trình tự động “sinh” tests  dùng nó để kiểm tra độ chính xác của chương trình. Nếu bạn vẫn muốn yêu cầu contributor tự tạo test, hãy thêm những ví dụ cụ thể về một test cụ thể, tốt hơn nữa là bạn hãy tạo sẵn form để họ  thêm input và output tương ứng vào.

Một điều tôi phải thừa nhận đó là thường thì dân coder sẽ bỏ qua bước đọc hướng dẫn trước khi commit. WTF, việc đóng góp cho các mã nguồn mở đâu có dễ như ăn cháo !!@#. Tôi nghĩ đến ý tưởng sẽ khiến họ đọc những văn bản đó một cách “thụ động”

Tôi bắt đầu bằng việc thêm một văn bản ngắn về việc làm sao để fix những lỗi thường gặp ở trong các pull requests. Việc này vừa giúp tôi lưu lại các văn bản một cách dễ dàng, vừa là một cách giúp người dùng dễ dàng theo dõi và sửa lỗi, cải thiện tiến độ commit một cách đáng kể

Tất cả những côn đoạn tôi đã đề cập khá đơn giản và sẽ không tốn quá nhiều thời gian để làm. Tuy nhiên bạn cũng đừng nên xử lý các pull requests cho những projects khác nhau trong cùng một lúc, hãy “chia để trị” từng project một và chắc chắn là công việc sẽ suôn sẻ

Những giải pháp được tôi đề cập trong bài viết

1. Sử dụng issue and pull request templates
2. Sử dụng ghooks và validate-commit-msg
3. Không yêu cầu quá cao cho test của contributor và thêm các sample tests để hướng dẫn cách tạo test
4. Thêm các hướng dẫn về commit format, tests và bất cứ thứ gì có  giúp cho quá trình commit của người dùng trở nên thật dễ dàng

Cuối cùng, chúng ta đều nên nhớ một điều rằng, khi có một ai đó đã dành thời gian quý báu của họ để đóng góp code của họ cho project của chúng ta, bất cứ nó lớn hay nhỏ, đúng hay sai, cũng rất đáng để chúng ta trân trọng và ghi nhận. Đừng quên cảm ơn họ vì điều đó :)

Người dịch: Phạm Quang Huy.

Nguồn: alistapart.com.