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

Chào mừng! Chúng tôi rất vui mừng khi bạn cân nhắc đóng góp cho các dự án mã nguồn mở Ultralytics 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 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 thị giác máy tính . Hướng dẫn này cung cấp các hướng dẫn rõ ràng và các biện pháp thực hành tốt nhất để giúp bạn bắt đầu.

Đồng hồ: Làm thế nào để đóng góp cho Ultralytics Kho lưu trữ | Ultralytics Mô hình, Bộ dữ liệu và Tài liệu 🚀

🤝 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ủ 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 tôi.

🚀 Đóng góp thông qua Yêu cầu kéo

Chúng tôi rất trân trọng những đóng góp dưới dạng yêu cầu kéo (PR) . Để quá 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 cách fork kho lưu trữ có liên quan Ultralytics kho lưu trữ (ví dụ: ultralytics / ultralytics ) vào 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ữ phân nhánh của bạn với tên rõ ràng, mô tả phản ánh những thay đổi của bạn (ví dụ: fix-issue-123, add-feature-xyz).
Thực hiện thay đổi của bạn: Triển khai các cải tiến hoặc 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 đưa 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ục bộ để xác nhận chúng hoạt động như mong đợi và không gây ra lỗi hồi quy . Thêm các bài kiểm tra nếu bạn đang giới thiệu chức năng mới.
Cam kết thay đổi của bạn : Cam kết thay đổi của bạn bằng các thông báo cam kết 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ố vấn đề (ví dụ: Fix #123: Corrected calculation error.).
Tạo yêu cầu kéo : Gửi yêu cầu kéo từ chi nhánh của bạn tới main nhánh của bản gốc Ultralytics kho lưu trữ. 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ý kết CLA

Trước khi chúng tôi có thể hợp nhất yêu cầu kéo của bạn, bạn phải ký Thỏa thuận cấp phép cho người đóng góp (CLA) của chúng tôi. 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 hợp lệ, 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 yêu cầu kéo của bạn, bot CLA sẽ hướng dẫn bạn qua quy trình ký. Để ký CLA, chỉ cần thêm bình luận vào PR của bạn nêu rõ:

I have read the CLA Document and I sign the CLA

✍️ Google - Chuỗi tài liệu kiểu

Khi thêm các hàm hoặc lớp mới, vui lòng bao gồm các docstring theo kiểu Google . Các docstring này cung cấp tài liệu rõ ràng, chuẩn hóa giúp các nhà phát triển khác hiểu và duy trì mã của bạn.

Ví dụ Docstrings

Google -phong cáchGoogle -phong cách với gợi ý loạiDòng đơn

Ví dụ này minh họa một Google -style docstring. Đảm bảo rằng cả đầu vào và đầu ra types luôn được đặt trong dấu ngoặc đơn, ví dụ, (bool).

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

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument, with a default value of 4.

    Returns:
        (bool): True if successful, False otherwise.

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

Ví dụ này bao gồm cả một Google - chuỗi doc theo kiểu và gợi ý kiểu cho các đối số và trả về, mặc dù sử dụng từng cái một cách độc lập cũng được chấp nhận.

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

    Args:
        arg1: The first argument.
        arg2: The second argument, with a default value of 4.

    Returns:
        True if successful, False otherwise.

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

Đối với các chức năng nhỏ hơn hoặc đơn giản hơn, một docstring một dòng có thể đủ. Docstring phải sử dụng ba dấu ngoặc kép, là một câu hoàn chỉnh, bắt đầu bằng chữ in hoa và kết thúc bằng dấu chấm.

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

✅ Kiểm tra CI của GitHub Actions

Tất cả các yêu cầu kéo phải vượt qua các bài kiểm tra Tích hợp liên tục (CI) của GitHub Actions trước khi có thể được hợp nhất. Các bài kiểm tra này bao gồm kiểm tra lỗi, kiểm tra đơn vị 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. Xem lại đầu ra CI và giải quyết mọi vấn đề phát sinh.

✨ Thực hành tốt nhất cho việc đóng góp mã

Khi đóng góp mã cho Ultralytics các dự án, hãy ghi nhớ những biện pháp tốt nhất sau:

Tránh trùng lặp mã: Sử 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 những thay đổi nhỏ hơn, có trọng tâm hơn: Tập trung vào những sửa đổi có mục tiêu thay vì những thay đổi trên 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 xem liệu chúng có thể phá vỡ mã hiện có hay không bằng cách sử dụng Ultralytics .
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 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.

👀 Xem xét các yêu cầu kéo

Xem lại các yêu cầu kéo là một cách đóng góp có giá trị khác. Khi xem lại các yêu cầu kéo:

Kiểm tra các bài kiểm tra đơn vị: Xác minh rằng PR bao gồm các bài kiểm tra cho các tính năng mới hoặc thay đổ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 những thay đổi.
Đánh giá tác động đến hiệu suất: Xem xét những thay đổi có thể ảnh hưởng đến hiệu suất như thế nào.
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 Tích hợp liên tục đề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 quan tâm nào.
Ghi nhận nỗ lực: Ghi nhận công sứ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á 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ó: Trước tiên, hãy tìm kiếm để xem lỗi đã được báo cáo hay chưa.
Cung cấp một ví dụ tái tạo tối thiểu : Tạo một đoạn mã nhỏ, độc lập, 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 của bạn, Python phiên bản, phiên bản thư viện có 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 hành vi 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 theo dõi 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 tính cởi mở , 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 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ả những người đóng góp 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 Ultralytics cộng đồng nguồn mở.

🌍 Mở nguồn của bạn YOLO Dự án đang trong quá trình AGPL-3.0

Sử dụng Ultralytics YOLO mô hình hoặc mã 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à nguồn mở theo AGPL-3.0 . Điều này đảm bảo các sửa đổi và dự án lớn hơn được xây dựng trên nền tảng nguồn mở vẫn được mở.

Tại sao AGPL-3.0 Vấn đề tuân thủ

Giữ phần mềm mở: Đảm bảo 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 AGPL-3.0 mã được cấp phép 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ự hợp tác: Khuyến khích chia sẻ và 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 xin Giấy phép Doanh nghiệp .

Làm thế nào để tuân thủ AGPL-3.0

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

Chọn điểm khởi đầu của bạn:
- Fork Ultralytics YOLO : Fork trực tiếp kho lưu trữ Ultralytics YOLO nếu xây dựng dựa trên kho lưu trữ này.
- Sử dụng Mẫu Ultralytics : Bắt đầu với kho lưu trữ mẫu Ultralytics để có thiết lập mô-đun sạch sẽ tích hợp YOLO .
Cấp phép cho dự án của bạn:
- Thêm một LICENSE tập tin chứa toàn văn của AGPL-3.0 giấy phép.
- Thêm thông báo ở đầu mỗi tệp nguồn để ghi rõ giấy phép.
Xuất bản mã nguồn của bạn:
- Làm cho bạn toàn bộ mã nguồn của dự á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 YOLO mô hình hoặc mã.
  - Bất kỳ sửa đổi nào được thực hiện đối với bản gốc Ultralytics YOLO mã số.
  - Các tập lệnh để đào tạo, xác thực, suy luận.
  - Trọng lượng mô hình nếu được sửa đổi hoặc tinh chỉnh.
  - Các tập tin 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 đào tạo nếu cần để chạy/đào tạo lại và có thể phân phối lại.
Tài liệu rõ ràng:
- Cập nhật của bạn README.md để nêu 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.
- Thuộc tính Ultralytics YOLO một cách thích hợp, liên kết trở lại vớ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.
```

Cấu trúc kho lưu trữ mẫu

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 hướng dẫn này, bạn đảm bảo tuân thủ AGPL-3.0 , hỗ trợ hệ sinh thái nguồn mở cho phép các công cụ mạnh mẽ như Ultralytics YOLO .

🎉 Kết luận

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

Chúng tôi rất vui mừng khi thấy ý tưởng của bạn trở thành hiện thực và trân trọng 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, chúng ta 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. Chúc bạn lập trình vui vẻ! 🚀🌟

CÂU HỎI THƯỜNG GẶP

Tại sao tôi nên đóng góp vào Ultralytics YOLO kho lưu trữ nguồn mở?

Đóng góp cho Ultralytics YOLO kho lưu trữ mã nguồn mở cải thiện phần mềm, giúp phần mềm mạnh mẽ hơn và có nhiều tính năng hơn cho toàn bộ cộng đồng. Đó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 tính năng mới. Ngoài ra, đó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 có kỹ năng khác trong lĩnh vực này, nâng cao kỹ năng và danh tiếng của riêng 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 Yêu cầu kéo .

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 cho người đóng góp (CLA), hãy làm theo hướng dẫn do bot CLA cung cấp sau khi gửi yêu cầu kéo 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 theo AGPL-3.0 giấy phép, duy trì tính toàn vẹn về mặt pháp lý của dự án nguồn mở. Thêm bình luận vào yêu cầu kéo của bạn nêu rõ:

I have read the CLA Document and I sign the CLA

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

Những gì là Google - chuỗi tài liệu theo phong cách và tại sao chúng lại cần thiết cho Ultralytics YOLO đóng góp?

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

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

Trước khi yêu cầu kéo 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, kiểm tra đơn vị và các kiểm tra khác để đảm bảo mã đáp ứng các tiêu chuẩn chất lượng của dự án. Xem lại đầu ra CI và khắc phục mọi sự cố. Để 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 của GitHub Actions .

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

Để báo cáo lỗi, hãy cung cấp Ví dụ có thể tái tạo tối thiểu 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 tối thiểu nhưng đủ để sao chép sự cố. Để biết các bước chi tiết hơn về báo cáo lỗi, hãy tham khảo phần Báo cáo lỗi .

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

Nếu bạn sử dụng Ultralytics YOLO mã hoặc mô hình (được cấp phép theo AGPL-3.0 ) trong dự án của bạn, AGPL-3.0 giấy phép 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 đầy đủ của nó phải được công khai. Điều này đảm bảo rằng bản chất nguồn mở của phần mềm được bảo toàn 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 có Giấy phép doanh nghiệp . Xem phần Nguồn mở cho dự án của bạn để biết chi tiết.

📅 Được tạo ra cách đây 1 năm ✏️ Đã cập nhật cách đây 16 ngày