Bỏ qua nội dung

Đó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. 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.

Ultralytics những người đóng góp mã nguồn mở

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. Để 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:

  1. Phân nhánh kho lưu trữ : Bắt đầu bằng cách phân nhánh Ultralytics YOLO kho lưu trữ vào tài khoản GitHub của bạn.

  2. Tạo 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.

  3. Thực hiện thay đổi: Đảm bảo mã của bạn tuân thủ theo hướng dẫn về phong cách của dự án và không gây ra bất kỳ lỗi hoặc cảnh báo mới nào.

  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 bất kỳ sự cố mới nào.

  5. Cam kết thay đổi của bạn : Cam kết thay đổi của bạn bằng một 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 đề trong thông báo cam kết của bạn.

  6. Tạo yêu cầu kéo : Gửi yêu cầu kéo từ kho lưu trữ phân nhánh của bạn tới kho lưu trữ chính Ultralytics YOLO kho lưu trữ. Cung cấp lời giải thích rõ ràng và chi tiết về những thay đổi của bạn và cách chúng cải thiện dự á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 AGPL-3.0 giấy phép.

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

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.

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 duy trì chất lượng của các dự án. Khi báo cáo lỗi, vui lòng cung cấp Ví dụ có thể tái tạo tối thiểu —một ví dụ mã đơn giản, rõ ràng, tái tạo vấn đề một cách nhất quán. Điều này cho phép chúng tôi nhanh chóng xác định và giải quyết vấn đề.

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 AGPL-3.0 giấy phép đóng góp hiệu quả và có đạo đức cho Ultralytics cộng đồng nguồn mở.

Mở nguồn các dự án của bạn với YOLO Và AGPL-3.0 Sự tuân thủ

Nếu bạn đang có kế hoạch phát triển và phát hành dự án của riêng mình bằng cách sử dụng YOLO mô hình, Giấy phép Công cộng GNU Affero v3.0 ( AGPL-3.0 ) đảm bảo rằng tất cả các tác phẩm phái sinh vẫn mở và có thể truy cập được. Phần này cung cấp hướng dẫn, bao gồm các bước, phương pháp hay nhất và yêu cầu, để giúp bạn mã nguồn mở cho dự án của mình trong khi tuân thủ AGPL-3.0 .

Các tùy chọn để bắt đầu dự án của bạn

Bạn có thể khởi động dự án của mình bằng một trong những cách sau:

  1. Fork kho lưu trữ YOLO Ultralytics
    Fork chính thức Ultralytics YOLO kho lưu trữ trực tiếp từ https://github.com/ ultralytics / ultralytics .

    • Sử dụng tùy chọn này nếu bạn có kế hoạch xây dựng trực tiếp trên phiên bản mới nhất YOLO thực hiện.
    • Sửa đổi mã phân nhánh khi cần thiết trong khi vẫn đảm bảo tuân thủ AGPL-3.0 .

  2. Bắt đầu từ Kho lưu trữ mẫu Ultralytics
    Sử dụng Ultralytics kho lưu trữ mẫu có sẵn tại https://github.com/ ultralytics /template .

    • Thích hợp để bắt đầu một dự án sạch, theo mô-đun với các phương pháp hay nhất được cấu hình sẵn.
    • Tùy chọn này cung cấp điểm khởi đầu nhẹ cho các dự án tích hợp hoặc mở rộng YOLO mô hình.

Những gì bạn cần để mở nguồn

Để tuân thủ AGPL-3.0 , bạn phải công khai các thành phần sau của dự án:

  1. Toàn bộ mã nguồn dự án của bạn :

    • Bao gồm tất cả mã cho dự án lớn hơn có chứa của bạn YOLO mô hình, tập lệnh và tiện ích.

  2. Trọng lượng mô hình (nếu đã sửa đổi):

    • Chia sẻ bất kỳ trọng số mô hình được tinh chỉnh hoặc sửa đổi nào như một phần của dự án nguồn mở.

  3. Tệp cấu hình :

    • Cung cấp các tập tin cấu hình như .yaml hoặc .json xác định thiết lập đào tạo, siêu tham số hoặc cấu hình triển khai.

  4. Dữ liệu đào tạo (nếu có thể phân phối lại) :

    • Nếu bạn bao gồm dữ liệu được xử lý trước hoặc tạo ra có thể phân phối lại, hãy đảm bảo dữ liệu đó là một phần của kho lưu trữ hoặc được liên kết rõ ràng.

  5. Thành phần ứng dụng web :

    • Bao gồm tất cả mã nguồn phía sau và phía trước nếu dự án của bạn là ứng dụng web, đặc biệt là các thành phần phía máy chủ.

  6. Tài liệu :

    • Bao gồm tài liệu hướng dẫn rõ ràng về cách sử dụng, xây dựng và mở rộng dự án của bạn.

  7. Xây dựng và triển khai tập lệnh :

    • Chia sẻ các tập lệnh để thiết lập môi trường, xây dựng ứng dụng và triển khai ứng dụng, chẳng hạn như Dockerfiles, requirements.txt, hoặc Makefiles.

  8. Khung thử nghiệm :

    • Mở mã nguồn các trường hợp thử nghiệm của bạn, chẳng hạn như thử nghiệm đơn vị và tích hợp, để đảm bảo khả năng tái tạo và độ tin cậy.

  9. Sửa đổi của bên thứ ba :

    • Cung cấp mã nguồn cho bất kỳ thư viện của bên thứ ba nào mà bạn đã sửa đổi.

Các bước để mở nguồn dự án của bạn

  1. Chọn điểm khởi đầu của bạn :

    • Nĩa cái Ultralytics YOLO kho lưu trữ hoặc bắt đầu từ Ultralytics kho lưu trữ mẫu.

  2. Thiết lập giấy phép của bạn :

    • Thêm một LICENSE tập tin chứa AGPL-3.0 chữ.

  3. Đóng góp tín dụng thượng nguồn :

    • Bao gồm ghi nhận cho Ultralytics YOLO trong README của bạn. Ví dụ: 
      This project builds on [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

  4. Công khai mã của bạn :

    • Đẩy toàn bộ dự án của bạn (bao gồm các thành phần được liệt kê ở trên) lên kho lưu trữ GitHub công khai.

  5. Ghi lại dự án của bạn :

    • Viết rõ ràng README.md có hướng dẫn thiết lập, sử dụng và đóng góp.

  6. Cho phép đóng góp :

    • Thiết lập trình theo dõi vấn đề và hướng dẫn đóng góp để thúc đẩy sự hợp tác.

Bằng cách làm theo các bước này và đảm bảo bạn bao gồm tất cả các thành phần cần thiết, bạn sẽ tuân thủ AGPL-3.0 và đóng góp có ý nghĩa cho cộng đồng nguồn mở. Chúng ta hãy cùng nhau tiếp tục thúc đẩy sự hợp tác và đổi mới trong lĩnh vực thị giác máy tính! 🚀

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

Dưới đây là một cấu trúc ví dụ cho một AGPL-3.0 dự án. Xem https://github.com/ ultralytics /template để biết chi tiết.

my-yolo-project/
│
├── LICENSE               # AGPL-3.0 license text
├── README.md             # Project overview and license information
├── src/                  # Source code for the project
│   ├── model.py          # YOLO-based model implementation
│   ├── utils.py          # Utility scripts
│   └── ...
├── pyproject.toml        # Python dependencies
├── tests/                # Unit and integration tests
├── .github/              # GitHub Actions for CI
│   └── workflows/
│       └── ci.yml        # Continuous integration configuration
└── docs/                 # Project documentation
    └── index.md

Bằng cách làm theo hướng dẫn này, bạn có thể đảm bảo dự án của mình vẫn tuân thủ AGPL-3.0 trong khi đóng góp cho cộng đồng nguồn mở. Sự tuân thủ của bạn củng cố tinh thần hợp tác, minh bạch và khả năng tiếp cận thúc đẩy sự thành công của các dự án như YOLO .

Phần 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

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 tạo ra cách đây 1 năm ✏️ Đã cập nhật cách đây 15 ngày
glenn-jocher MatthewNoyce Trợ lý Ultralytics RizwanMunawar Burhan-Q

Bình luận