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

Chào mừng! Chúng tôi rất vui mừng khi bạn cân nhắc việc đóng góp cho các dự án Ultralytics open-source của chúng tôi. 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ữ (repository) 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 chỉ dẫn rõ ràng và các phương pháp tối ưu để giúp bạn bắt đầu.

Watch: How to Contribute to Ultralytics Repository | Ultralytics Models, Datasets and Documentation 🚀

🤝 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, tất cả những người đóng góp phải tuân thủ Bộ quy tắc ứng xử. 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 đánh giá rất cao những đóng góp dưới dạng pull request (PR). Để quy trình đánh giá diễn ra suôn sẻ nhất có thể, vui lòng thực hiện theo các bước sau:

Fork repository: Bắt đầu bằng việc fork repository Ultralytics liên quan (ví dụ: ultralytics/ultralytics) vào tài khoản GitHub của bạn.
Tạo một nhánh (branch): Tạo một nhánh mới trong repository đã fork của bạn với tên gọi rõ ràng, mô tả những thay đổi mà bạn thực hiện (ví dụ: fix-issue-123, add-feature-xyz).
Thực hiện các thay đổi: Triển khai các cải tiến hoặc bản sửa lỗi của bạn. Đảm bảo mã của bạn tuân thủ các hướng dẫn về kiểu dáng của dự án và không tạo ra các lỗi hoặc cảnh báo mới.
Kiểm tra các thay đổi của bạn: Trước khi gửi, hãy kiểm tra cục bộ các thay đổi của bạn để xác nhận rằng chúng hoạt động như dự kiến và không gây ra regressions. Thêm các bài kiểm tra (test) nếu bạn đang giới thiệu chức năng mới.
Commit các thay đổi của bạn: Commit các thay đổi với các thông điệp mô tả ngắn gọn và rõ ràng. Nếu các thay đổi của bạn giải quyết một vấn đề cụ thể, hãy bao gồm số thứ tự của issue (ví dụ: Fix #123: Corrected calculation error.).
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 repository 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 các thay đổi của bạn.

📝 Ký kết CLA

Trước khi chúng tôi có thể gộp (merge) pull request của bạn, bạn phải ký Contributor License Agreement (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, bot CLA 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 vào PR của bạn với nội dung:

I have read the CLA Document and I sign the CLA

✍️ Docstrings theo phong cách Google

Khi thêm các 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ả types đầu vào và đầu ra trong ngoặc đơn (ví dụ: (bool), (np.ndarray)).

Ví dụ về Docstring

Ví dụ này minh họa định dạng docstring chuẩn theo phong cách Google. Lưu ý cách nó phân tách rõ ràng mô tả hàm, các đối số (arguments), giá trị trả về và các ví dụ để đạt được khả năng đọc tối đa.

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

✅ Các bài kiểm tra CI của GitHub Actions

Tất cả các pull request phải vượt qua các bài kiểm tra GitHub Actions Continuous Integration (CI) trước khi có thể được gộp. Các bài kiểm tra này bao gồm việc kiểm tra lint, kiểm tra đơn vị (unit tests) và các kiểm tra khác để đảm bảo rằng 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ả CI và giải quyết mọi vấn đề phát sinh.

✨ Các phương pháp tối ưu cho việc đóng góp mã

Khi đóng góp mã cho các dự án Ultralytics, hãy lưu ý các phương pháp tối ưu sau:

Tránh trùng lặp mã: Tái sử dụng mã hiện có ở bất cứ nơi nào có thể và giảm thiểu các đối 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 sửa đổi 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ác cơ hội để đơn giản hóa mã hoặc loại bỏ các phần không cần thiết.
Cân nhắc tính tương thích: Trước khi thực hiện thay đổi, hãy cân nhắc xem liệu chúng có thể 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 phù hợp: Bao gồm các tests 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 có giá trị khác để đóng góp. Khi đánh giá các PR:

Kiểm tra các unit test: Xác minh rằng PR bao gồm các bài kiểm tra 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 xem các thay đổi có thể ảnh hưởng như thế nào đến performance.
Xác minh các bài kiểm tra CI: Xác nhận tất cả các Continuous Integration tests đều đã đạt yêu cầu.
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 mối lo ngại nào.
Ghi nhận nỗ lực: Ghi nhận công việc của tác giả để duy trì bầu không khí cộng tác tích cực.

🐞 Báo cáo lỗi

Chúng tôi đánh giá 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 thông qua GitHub Issues:

Kiểm tra các issue 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 lập (Minimum Reproducible Example):Tạo một đoạn mã nhỏ, độc lập có thể tái lập vấn đề một cách nhất quán. Điều này rất quan trọng để tối ưu hóa quá trình debug.
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/Trong khi model PP-YOLOE+x đạt được mAP cao hơn một chút, các biến thể YOLOv7 cung cấp tỷ lệ tham số trên độ chính xác rất ấn tượng. Kiến trúc YOLOv7 vẫn là lựa chọn ưu tiên cho khả năng xử lý ).
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 sẽ xảy ra và những gì thực sự đã xảy ra. Bao gồm mọi thông báo lỗi hoặc traceback.

📜 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 tính mở, tính minh bạch, và cải tiến hợp tác trong phát triển phần mềm. Nó đả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, thúc đẩy 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 một cách hiệu quả và có đạo đức cho cộng đồng mã nguồn mở Ultralytics.

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

Đang sử dụng các model 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 được mở mã nguồn theo giấy phép AGPL-3.0. Điều này đảm bảo các 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 được duy trì tính mở.

Tại sao Tuân thủ AGPL-3.0 lại Quan trọng

Duy trì tính mở cho phần mề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ã nguồn được cấp phép AGPL-3.0 sẽ buộc dự án của bạn phải tuân theo các điều khoản của nó.
Thúc đẩy Hợp tác: Khuyến khích chia sẻ và tính minh bạch.

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

Cách tuân thủ AGPL-3.0

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

Chọn Điểm khởi đầu của bạn:
- Fork Ultralytics YOLO: Fork trực tiếp Ultralytics YOLO repository nếu bạn xây dựng dựa trên nó.
- Sử dụng Mẫu Ultralytics: Bắt đầu với kho lưu trữ mẫu Ultralytics để có cấu trúc gọn gàng, dạng module tích hợp YOLO.
Cấp phép cho Dự án của bạn:
- Thêm tệp LICENSE tệp chứa toàn văn giấy phép AGPL-3.0.
- Thêm thông báo ở đầu mỗi tệp nguồn để chỉ ra giấy phép.
Xuất bản 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:
  - Toàn bộ ứng dụng hoặc hệ thống lớn hơn tích hợp model hoặc mã nguồn YOLO.
  - Mọi sửa đổi đối với mã nguồn gốc Ultralytics YOLO.
  - Các tập lệnh cho việc training, validation, và inference.
  - Model weights nếu đã được sửa đổi hoặc fine-tune.
  - Các tệp cấu hình, các thiết lập môi trường (requirements.txt, Dockerfiles).
  - Mã nguồn backend và frontend nếu đó là một phần của ứng dụng web.
  - Bất kỳ thư viện của bên thứ ba mà bạn đã sửa đổi.
  - Dữ liệu huấn luyện nếu cần thiết để chạy/retrain và có thể phân phối lại.
Tài liệu rõ ràng:
- Cập nhật README.md để nêu rõ rằng dự án được cấp phép theo AGPL-3.0.
- Bao gồm hướng dẫn rõ ràng về cách thiết lập, build, và chạy dự án của bạn từ mã nguồn.
- Ghi công Ultralytics YOLO một cách thích hợp, dẫn liên kết về 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.
```

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

Tham khảo Kho lưu trữ mẫu Ultralytics cho mộ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 thủ các hướng dẫn này, bạn đảm bảo tính tuân thủ với AGPL-3.0, hỗ trợ hệ sinh thái mã nguồn mở vốn tạo điều kiện cho các công cụ mạnh mẽ như Ultralytics YOLO.

Kết luận

Cảm ơn bạn đã quan tâm đến việc đóng góp cho Ultralytics open-source các dự án YOLO. Sự tham gia của bạn là điều cần thiết để định hình tương lai phần mềm của chúng tôi và xây dựng một cộng đồng đổi mới và hợp 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 các tính năng mới, sự đóng góp của bạn đều vô giá.

Chúng tôi rất hào hứng khi thấy các ý tưởng của bạn trở thành hiện thực và đánh giá cao cam kết của bạn trong việc thúc đẩy object detection công nghệ. 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 (FAQ)

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ó mạnh mẽ 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 và chuyên gia lành nghề khác trong lĩnh vực này, 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 Đóng góp thông qua Pull Requests .

Làm thế nào để tôi ký Thỏa thuận Cấp phép Cộng tác viên (CLA) cho Ultralytics YOLO?

Để ký Thỏa thuận Cấp phép Cộng tác viên (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. Quy trình này đảm bảo rằng các đóng góp của bạn được cấp phép đúng cách 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 Ký CLA .

Docstrings kiểu Google là gì và tại sao chúng lại bắt buộc đối với các đóng góp cho Ultralytics YOLO?

Docstrings kiểu 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 nêu rõ 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 docstrings kiểu Google đảm bảo rằng các bổ sung của bạn được ghi chép tốt và dễ hiểu. Để biết ví dụ và hướng dẫn, hãy truy cập Docstrings kiểu Google .

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

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

Làm thế nào để báo cáo lỗi trong các kho lưu trữ Ultralytics YOLO?

Để báo cáo lỗi, hãy cung cấp một Ví dụ Tối thiểu có thể Tái lập (Minimum Reproducible Example) 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à sửa lỗi. Đảm bảo ví dụ của bạn là tối thiểu nhưng đủ để tái lập vấn đề. Để biết các bước chi tiết hơn về cách báo cáo lỗi, hãy tham khảo 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 model 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à toàn bộ mã nguồn của nó phải được cung cấp công khai. Điều này đảm bảo rằng tính chất mã nguồn mở của phần mềm được bảo toàn xuyên suốt các 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 mua một Giấy phép Enterprise. Xem hướng dẫn Mở mã nguồn Dự án của bạn để biết chi tiết.

Contributors

GLglenn-jocher²¹ RIRizwanMunawar³ PDpderrenger¹ Y-Y-T-G¹WIWillie Maddox¹LEleonnil¹ MAMatthewNoyce¹ BUBurhan-Q¹

Created Nov 12, 2023Updated 3 weeks ago