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

Welcome! We're thrilled that you're considering contributing to our Ultralytics open-source projects. Your involvement not only helps enhance the quality of our repositories but also benefits the entire computer vision community. This guide provides clear guidelines and best practices to help you get started.

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

🤝 Quy tắc ứng xử

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

🚀 Đóng góp thông qua Pull Requests

Chúng tôi đánh giá rất cao các đóng góp dưới dạng pull requests (PRs). Để quy trình đánh giá diễn ra suôn sẻ nhất có thể, vui lòng làm theo các bước sau:

Fork kho lưu trữ: Bắt đầu bằng việc fork kho lưu trữ Ultralytics liên quan (ví dụ: ultralytics/ultralytics) về tài khoản GitHub của bạn.
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ả chính xác những thay đổi bạn thực hiện (ví dụ: fix-issue-123, add-feature-xyz).
Thực hiện các thay đổi của bạn: Triển khai các cải tiến hoặc bản sửa lỗi. Đả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.
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ủa bạn tại cục bộ để xác nhận chúng hoạt động như mong đợi và không gây ra hồi quy (regressions). Thêm các bài kiểm tra 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 thông điệp ngắn gọn và mô tả. Nếu 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 vấn đề đó (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 tới 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 các thay đổi của bạn.

📝 Ký CLA

Trước khi chúng tôi có thể gộp (merge) 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ý 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

✍️ Docstrings theo phong cách Google

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

Ví dụ về Docstrings

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, đối số, giá trị trả về và các ví dụ để tối đa hóa khả năng đọc.

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

All pull requests must pass the GitHub Actions Continuous Integration (CI) tests before they can be merged. These tests include linting, unit tests, and other checks to ensure that your changes meet the project's quality standards. Review the CI output and address any issues that arise.

✨ Các phương pháp tốt nhất khi đó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 tốt nhất sau:

Tránh lặp lại mã: Tận dụng lại mã hiện có bất cứ khi 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 mục tiêu thay vì các thay đổi quy mô lớn.
Đơn giản hóa khi có thể: Tì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.
Cân nhắc khả năng tương thích: Trước khi thực hiện thay đổi, hãy xem xét liệu chúng có làm hỏng mã hiện tại đ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 thử phù hợp: Bao gồm các bài kiểm thử cho các tính năng mới để đảm bảo chúng hoạt động như mong đợi.

👀 Đánh giá Pull Requests

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

Kiểm tra các bài 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 xét 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 suất: Xem xét cách các thay đổi có thể ảnh hưởng đến hiệu suất.
Xác minh các kiểm thử CI: Xác nhận tất cả các bài kiểm thử Tích hợp liên tục đều đã 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í cộng 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 liệu lỗi đã được báo cáo hay chưa.
Cung cấp Ví dụ tối thiểu có thể tái tạo: Tạo một đoạn mã nhỏ, độc lập giúp tái tạo lỗi 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 sẽ xảy ra và những gì thực tế đã xảy ra. Bao gồm bất kỳ thông báo lỗi hoặc 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 mang tính cộng 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ìm hiểu 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ã nguồn mở cho dự án YOLO của bạn theo AGPL-3.0

Đang sử dụng các mô hình hoặc mã YOLO của Ultralytics trong dự án của bạn? Giấy phép AGPL-3.0 yêu cầu toàn bộ công việc phái sinh của bạn cũng phải được cung cấp dưới dạng mã nguồn mở theo 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 giữ được tính chất mở.

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

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

Nếu bạn không muốn cung cấp dự án của mình dưới dạng mã nguồn mở, hãy cân nhắc việc sở hữu Giấy phép Doanh nghiệp (Enterprise License).

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.

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ự án dựa trên nó.
- Sử dụng Template của Ultralytics: Bắt đầu với kho lưu trữ template của Ultralytics để có một thiết lập sạch sẽ, dạng mô-đun tích hợp YOLO.
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 thông báo ở đầu mỗi tệp nguồn chỉ ra giấy phép.
Công bố 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 đối với mã Ultralytics YOLO gốc.
  - Các tập lệnh để huấn luyện, kiểm chứng và suy luận.
  - Trọng số mô hình nếu đã được sửa đổi hoặc tinh chỉnh.
  - Các 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 bên thứ ba nào mà bạn đã sửa đổi.
  - Dữ liệu huấn luyện nếu cần thiết để chạy/huấn luyện lại và có thể phân phối lại.
Tài liệu rõ ràng:
- Cập nhật README.md của bạn để 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, xây dựng và chạy dự án của bạn từ mã nguồn.
- Ghi công Ultralytics YOLO một cách phù hợp, liên kết 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ữ Template Ultralytics để có 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 hướng dẫn 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 phát triển.

Kết luận

Thank you for your interest in contributing to Ultralytics open-source YOLO projects. Your participation is essential in shaping the future of our software and building a vibrant community of innovation and collaboration. Whether you're enhancing code, reporting bugs, or suggesting new features, your contributions are invaluable.

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 công nghệ nhận diệ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 (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ó trở nê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ã, sửa lỗi, cải thiện tài liệu và triển khai các tính năng mới. Ngoài ra, việc đóng góp cho phép bạn hợp 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, từ đó 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 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 hướng dẫn do CLA bot cung cấp 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 phần Ký CLA.

Docstrings theo phong cách 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 theo phong cách Google cung cấp tài liệu rõ ràng, ngắn gọn cho các hàm và lớp, giúp cải thiện khả năng đọc và bảo trì mã. Những docstring này phác thảo mục đích của hàm, các đối số và giá trị trả về với các quy tắc định dạng cụ thể. Khi đóng góp cho Ultralytics YOLO, việc tuân thủ các docstring theo phong cách Google đảm bảo rằng các bổ sung của bạn được ghi tài liệu đầy đủ và dễ hiểu. Để xem các ví dụ và hướng dẫn, hãy truy cập phần Docstrings theo phong cách Google.

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

Trước khi pull request của bạn có thể được hợp nhất, 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. Hãy xem xét kết quả đầ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à các mẹo khắc phục sự cố, hãy xem phần GitHub Actions CI Tests.

Làm cách 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 tạo rõ ràng và ngắn gọn 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 xác định và sửa lỗi nhanh chóng. Hãy đảm bảo ví dụ của bạn tối thiểu nhưng đủ để tái tạo 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 phần Reporting Bugs.

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 công khai. Điều này đảm bảo rằng bản chất mã nguồn mở của phần mềm được duy trì xuyên 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 có Enterprise License. Xem phần Open-Sourcing Your Project để biết chi tiết.

Contributors

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

Created 12 thg 11, 2023Updated tuần trước