Đóng góp cho các dự án mã nguồn mở Ultralytics#

Chào mừng! Chúng tôi rất vui mừng khi bạn đang cân nhắc đóng góp cho các dự án open-source của Ultralytics. Sự tham gia của bạn không chỉ giúp nâng cao chất lượng các kho lưu trữ của chúng tôi mà còn mang lại lợi ích cho toàn bộ cộng đồng computer vision. Hướng dẫn này cung cấp các nguyên tắc rõ ràng và các phương pháp hay nhất để giúp bạn bắt đầu.

🤝 Bộ Quy tắc Ứng xử#

Để đảm bảo một môi trường chào đón và hòa nhập cho tất cả mọi người, mọi cộng tác viên phải tuân thủ Bộ quy tắc ứng xử của chúng tôi. Sự tôn trọng, lòng tốt và tính chuyên nghiệp là cốt lõi của cộng đồng chúng ta.

🚀 Đóng góp thông qua Pull Request#

Chúng tôi rất trân trọng những đóng góp dưới dạng pull request (PR). Để quá trình xem xét diễn ra suôn sẻ nhất có thể, vui lòng thực hiện các bước sau:

1. Fork kho lưu trữ: Bắt đầu bằng cách fork kho lưu trữ Ultralytics liên quan (ví dụ: ultralytics/ultralytics) sang tài khoản GitHub của bạn.
2. Tạo một nhánh: Tạo một nhánh mới trong kho lưu trữ đã fork của bạn với tên gọi rõ ràng, mô tả đúng các thay đổi của bạn (ví dụ: fix-issue-123, add-feature-xyz).
3. Thực hiện các thay đổi: Triển khai các cải tiến hoặc sửa lỗi của bạn. Đảm bảo mã của bạn tuân thủ các nguyên tắc về phong cách của dự án và không gây ra lỗi hoặc cảnh báo mới.
4. Kiểm tra các thay đổi của bạn: Trước khi gửi, hãy kiểm tra các thay đổi cục bộ để xác nhận chúng hoạt động như mong đợi và không gây ra regression. Thêm các bài kiểm tra nếu bạn giới thiệu tính năng mới.
5. Commit các thay đổi của bạn: Commit các thay đổi với thông điệp súc tích và mô tả rõ ràng. Nếu các thay đổi của bạn liên quan đến một vấn đề cụ thể, hãy đính kèm số hiệu vấn đề đó (ví dụ: Fix #123: Corrected calculation error.).
6. Tạo một pull request: Gửi một pull request từ nhánh của bạn đến nhánh main của kho lưu trữ Ultralytics gốc. Cung cấp tiêu đề rõ ràng và mô tả chi tiết giải thích mục đích và phạm vi thay đổi của bạn.

📝 Ký CLA#

Trước khi chúng tôi có thể gộp pull request của bạn, bạn phải ký Thỏa thuận Cấp phép Cộng tác viên (CLA). Thỏa thuận pháp lý này đảm bảo rằng các đóng góp của bạn được cấp phép đúng cách, cho phép dự án tiếp tục được phân phối theo giấy phép AGPL-3.0.

Sau khi gửi pull request, CLA bot sẽ hướng dẫn bạn quy trình ký kết. Để ký CLA, chỉ cần thêm một bình luận trong PR của bạn với nội dung:

I have read the CLA Document and I sign the CLA

✍️ Docstring theo phong cách Google#

Khi thêm hàm hoặc lớp mới, hãy bao gồm docstring theo phong cách Google để có tài liệu rõ ràng và chuẩn hóa. Luôn đặt cả đầu vào và đầu ra types trong dấu ngoặc đơn (ví dụ: (bool), (np.ndarray)).

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

✅ Kiểm thử CI GitHub Actions#

Tất cả các pull request phải vượt qua các bài kiểm tra Continuous Integration (CI) trên GitHub Actions trước khi có thể được merge. Các bài kiểm tra này bao gồm kiểm tra linter, unit test và các bước kiểm tra khác để đảm bảo các thay đổi của bạn đáp ứng các tiêu chuẩn chất lượng của dự án. Hãy xem lại kết quả đầu ra của CI và giải quyết mọi vấn đề phát sinh.

✨ Các phương pháp thực hành tốt nhất cho đóng góp mã#

Khi đóng góp mã cho các dự án Ultralytics, hãy ghi nhớ các phương pháp thực hành tốt nhất sau:

• Tránh trùng lặp mã: Tái sử dụng mã hiện có ở bất cứ đâu có thể và giảm thiểu các tham số không cần thiết.
• Thực hiện các thay đổi nhỏ, tập trung: Tập trung vào các chỉnh sửa có mục tiêu thay vì những thay đổi quy mô lớn.
• Đơn giản hóa khi có thể: Tìm kiếm cơ hội để đơn giản hóa mã hoặc loại bỏ các phần không cần thiết.
• Xem xét khả năng tương thích: Trước khi thực hiện thay đổi, hãy cân nhắc liệu chúng có làm hỏng mã hiện có đang sử dụng Ultralytics hay không.
• Sử dụng định dạng nhất quán: Các công cụ như Ruff Formatter có thể giúp duy trì tính nhất quán về phong cách.
• Thêm các bài kiểm tra thích hợp: Bao gồm các bài kiểm tra cho các tính năng mới để đảm bảo chúng hoạt động như mong đợi.

👀 Đánh giá Pull Request#

Đánh giá pull request là một cách đóng góp giá trị khác. Khi đánh giá PR:

• Kiểm tra kiểm thử đơn vị: Xác minh rằng PR bao gồm các bài kiểm thử cho các tính năng hoặc thay đổi mới.
• Xem lại các cập nhật tài liệu: Đảm bảo tài liệu được cập nhật để phản ánh các thay đổi.
• Đánh giá tác động đến hiệu năng: Cân nhắc cách các thay đổi có thể ảnh hưởng đến hiệu năng.
• Xác minh các bài kiểm tra CI: Xác nhận tất cả các bài kiểm tra Continuous Integration đều đang vượt qua.
• Cung cấp phản hồi mang tính xây dựng: Đưa ra phản hồi cụ thể, rõ ràng về bất kỳ vấn đề hoặc lo ngại nào.
• Ghi nhận nỗ lực: Công nhận công việc của tác giả để duy trì bầu không khí hợp tác tích cực.

🐞 Báo cáo lỗi#

Chúng tôi đánh giá rất cao các báo cáo lỗi vì chúng giúp chúng tôi cải thiện chất lượng và độ tin cậy của các dự án. Khi báo cáo lỗi qua GitHub Issues:

• Kiểm tra các vấn đề hiện có: Tìm kiếm trước xem lỗi đã được báo cáo hay chưa.
• Cung cấp một Ví dụ Tối thiểu Có thể Tái tạo: Tạo một đoạn mã nhỏ, độc lập có thể tái tạo vấn đề một cách nhất quán. Điều này rất quan trọng để gỡ lỗi hiệu quả.
• Mô tả môi trường: Chỉ định hệ điều hành, phiên bản Python, các phiên bản thư viện liên quan (ví dụ: torch, ultralytics), và phần cứng (CPU/GPU).
• Giải thích hành vi mong đợi so với thực tế: Nêu rõ những gì bạn mong đợi xảy ra và những gì đã thực sự xảy ra. Bao gồm bất kỳ thông báo lỗi hoặc dấu vết (traceback) nào.

📜 Giấy phép#

Ultralytics sử dụng GNU Affero General Public License v3.0 (AGPL-3.0) cho các kho lưu trữ của mình. Giấy phép này thúc đẩy sự cởi mở, tính minh bạch và cải tiến hợp tác trong phát triển phần mềm. Giấy phép này đảm bảo rằng tất cả người dùng đều có quyền tự do sử dụng, sửa đổi và chia sẻ phần mềm, nuôi dưỡng một cộng đồng hợp tác và đổi mới mạnh mẽ.

Chúng tôi khuyến khích tất cả các cộng tác viên tự làm quen với các điều khoản của giấy phép AGPL-3.0 để đóng góp hiệu quả và có đạo đức cho cộng đồng mã nguồn mở Ultralytics.

🌍 Mã nguồn mở cho Dự án YOLO của bạn theo AGPL-3.0#

Sử dụng các mô hình hoặc mã nguồn Ultralytics YOLO trong dự án của bạn? Giấy phép AGPL-3.0 yêu cầu toàn bộ tác phẩm phái sinh của bạn cũng phải là mã nguồn mở theo AGPL-3.0. Điều này đảm bảo các bản sửa đổi và các dự án lớn hơn được xây dựng trên nền tảng mã nguồn mở vẫn giữ được tính mở.

Tại sao việc tuân thủ AGPL-3.0 lại quan trọng#

• Giữ cho Phần mềm ở dạng Mã nguồn mở: Đảm bảo rằng các cải tiến và tác phẩm phái sinh mang lại lợi ích cho cộng đồng.
• Yêu cầu Pháp lý: Sử dụng mã được cấp phép AGPL-3.0 sẽ ràng buộc dự án của bạn với các điều khoản của nó.
• Thúc đẩy Hợp tác: Khuyến khích sự chia sẻ và tính minh bạch.

Nếu bạn không muốn công khai mã nguồn dự án của mình, hãy cân nhắc việc mua Giấy phép Doanh nghiệp.

Cách Tuân thủ AGPL-3.0#

Tuân thủ có nghĩa là cung cấp toàn bộ mã nguồn tương ứng của dự án của bạn ra công chúng theo giấy phép AGPL-3.0.

1. Chọn Điểm bắt đầu của bạn:

   • Fork Ultralytics YOLO: Trực tiếp fork kho lưu trữ Ultralytics YOLO nếu xây dựng dựa trên nó một cách chặt chẽ.
   • Sử dụng Mẫu Ultralytics: Bắt đầu với kho lưu trữ mẫu Ultralytics để có một thiết lập sạch sẽ, dạng mô-đun tích hợp YOLO.

2. Cấp phép cho Dự án của bạn:

   • Thêm một tệp LICENSE chứa toàn bộ văn bản của giấy phép AGPL-3.0.
   • Thêm một thông báo ở đầu mỗi tệp nguồn chỉ ra giấy phép.

3. Công khai Mã nguồn của bạn:

   • Làm cho toàn bộ mã nguồn dự án của bạn có thể truy cập công khai (ví dụ: trên GitHub). Điều này bao gồm:
     • Ứng dụng hoặc hệ thống lớn hơn hoàn chỉnh kết hợp mô hình hoặc mã YOLO.
     • Bất kỳ sửa đổi nào được thực hiện đối với mã Ultralytics YOLO gốc.
     • Các tập lệnh để huấn luyện, xác thực và suy luận (inference).
     • Trọng số mô hình nếu đã sửa đổi hoặc tinh chỉnh.
     • Tệp cấu hình, thiết lập môi trường (requirements.txt, Dockerfiles).
     • Mã backend và frontend nếu nó là một phần của ứng dụng web.
     • Bất kỳ thư viện của bên thứ ba nào mà bạn đã sửa đổi.
     • Dữ liệu huấn luyện nếu bắt buộc để chạy/huấn luyện lại và có thể phân phối lại.

4. Ghi tài liệu Rõ ràng:

   • Cập nhật README.md của bạn để nêu rõ dự án được cấp phép theo AGPL-3.0.
   • Bao gồm các hướng dẫn rõ ràng về cách thiết lập, xây dựng và chạy dự án của bạn từ mã nguồn.
   • Ghi nhận nguồn Ultralytics YOLO thích hợp, liên kết ngược lại kho lưu trữ gốc. Ví dụ:

     This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

Ví dụ về Cấu trúc Kho lưu trữ#

Tham khảo Kho lưu trữ mẫu Ultralytics để biết cấu trúc ví dụ thực tế:

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

Bằng cách tuân theo các nguyên tắc này, bạn đảm bảo sự tuân thủ AGPL-3.0, hỗ trợ hệ sinh thái mã nguồn mở cho phép các công cụ mạnh mẽ như Ultralytics YOLO tồn tại.

Kết luận#

Cảm ơn bạn đã quan tâm đóng góp cho các dự án YOLO open-source của Ultralytics. Sự tham gia của bạn rất thiết yếu trong việc định hình tương lai của phần mềm chúng tôi và xây dựng một cộng đồng đổi mới và cộng tác sôi động. Cho dù bạn đang cải thiện mã nguồn, báo cáo lỗi hay đề xuất tính năng mới, các đóng góp của bạn đều vô cùng quý giá.

Chúng tôi rất hào hứng khi thấy các ý tưởng của bạn thành hiện thực và đánh giá cao cam kết của bạn trong việc thúc đẩy công nghệ phát hiện đối tượng. Cùng nhau, hãy tiếp tục phát triển và đổi mới trong hành trình mã nguồn mở thú vị này.

Câu hỏi thường gặp#

Tại sao tôi nên đóng góp cho các kho lưu trữ mã nguồn mở Ultralytics YOLO?#

Đóng góp cho các kho lưu trữ mã nguồn mở Ultralytics YOLO giúp cải thiện phần mềm, làm cho nó trở nên mạnh mẽ hơn và giàu tính năng hơn cho toàn bộ cộng đồng. Các đóng góp có thể bao gồm cải tiến mã nguồn, sửa lỗi, cải thiện tài liệu và triển khai tính năng mới. Ngoài ra, việc đóng góp cho phép bạn cộng tác với các nhà phát triển lành nghề và chuyên gia khác trong lĩnh vực, nâng cao kỹ năng và uy tín của chính bạn. Để biết chi tiết về cách bắt đầu, hãy tham khảo phần Đóng góp qua Pull Request.

Làm cách nào để tôi ký Thỏa thuận Cấp phép Người đóng góp (CLA) cho Ultralytics YOLO?#

Để ký Thỏa thuận Cấp phép Người đóng góp (CLA), hãy làm theo các hướng dẫn được cung cấp bởi CLA bot sau khi gửi pull request của bạn. Quá trình này đảm bảo rằng các đóng góp của bạn được cấp phép phù hợp theo giấy phép AGPL-3.0, duy trì tính toàn vẹn pháp lý của dự án mã nguồn mở. Thêm một bình luận trong pull request của bạn với nội dung:

I have read the CLA Document and I sign the CLA

Để biết thêm thông tin, hãy xem phần Ký CLA.

Docstring theo phong cách Google là gì và tại sao chúng lại cần thiết cho các đóng góp vào Ultralytics YOLO?#

Docstring theo phong cách Google cung cấp tài liệu rõ ràng, súc tích cho các hàm và lớp, cải thiện khả năng đọc và bảo trì mã nguồn. Các docstring này phác thảo mục đích, đối số và giá trị trả về của hàm với các quy tắc định dạng cụ thể. Khi đóng góp cho Ultralytics YOLO, việc tuân theo các docstring theo phong cách Google đảm bảo các phần bổ sung của bạn được tài liệu hóa tốt và dễ hiểu. Để biết các ví dụ và hướng dẫn, hãy truy cập phần Docstring theo phong cách Google.

Làm thế nào để đảm bảo các thay đổi của tôi vượt qua các bài kiểm tra CI của GitHub Actions?#

Trước khi pull request của bạn có thể được gộp, nó phải vượt qua tất cả các bài kiểm tra Continuous Integration (CI) của GitHub Actions. Các bài kiểm tra này bao gồm kiểm tra lỗi cú pháp (linting), unit test và các kiểm tra khác để đảm bảo mã nguồn đáp ứng tiêu chuẩn chất lượng của dự án. Xem lại đầu ra của CI và khắc phục mọi vấn đề. Để biết thông tin chi tiết về quy trình CI và mẹo khắc phục sự cố, hãy xem phần Kiểm tra CI trên GitHub Actions.

Làm cách nào để báo cáo lỗi trong các repository YOLO của Ultralytics?#

Để báo cáo lỗi, hãy cung cấp một Ví dụ Tối thiểu Có thể Tái tạo rõ ràng và súc tích cùng với báo cáo lỗi của bạn. Điều này giúp các nhà phát triển nhanh chóng xác định và khắc phục sự cố. Đảm bảo ví dụ của bạn là tối thiểu nhưng đủ để tái tạo vấn đề. Để có thêm các bước chi tiết về việc báo cáo lỗi, hãy tham khảo phần Báo cáo lỗi.

Giấy phép AGPL-3.0 có ý nghĩa gì nếu tôi sử dụng Ultralytics YOLO trong dự án của riêng mình?#

Nếu bạn sử dụng mã nguồn hoặc mô hình Ultralytics YOLO (được cấp phép theo AGPL-3.0) trong dự án của mình, giấy phép AGPL-3.0 yêu cầu toàn bộ dự án của bạn (tác phẩm phái sinh) cũng phải được cấp phép theo AGPL-3.0 và mã nguồn hoàn chỉnh của nó phải được cung cấp công khai. Điều này đảm bảo tính chất mã nguồn mở của phần mềm được duy trì trong suốt các sản phẩm phái sinh của nó. Nếu bạn không thể đáp ứng các yêu cầu này, bạn cần phải mua Giấy phép Doanh nghiệp. Xem phần Mở nguồn mở dự án của bạn để biết chi tiết.