Đóng góp vào các Dự án Mã nguồn mở Ultralytics

Q: How can I ensure my changes pass the GitHub Actions CI tests?

Trước khi yêu cầu pull của bạn được chấp nhận, 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à sửa mọi sự cố. Để 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 Kiểm tra CI của GitHub Actions.

Chào mừng! Chúng tôi rất vui vì bạn đang cân nhắc đóng góp cho các dự án Ultralytics mã nguồn mở 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 phương pháp hay nhất để giúp bạn bắt đầu.

Xem: Cách Đóng Góp vào Kho Lưu Trữ Ultralytics | Các Mô Hình, Bộ Dữ Liệu và Tài Liệu Ultralytics 🚀

🤝 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ả những người đóng góp phải tuân thủ Quy tắc ứng xử của chúng tôi. Tôn trọ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á cao những đóng góp dưới hình thức yêu cầu kéo (PR). Để quá trình xem xét 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ữ 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: Tạo một nhánh mới trong kho lưu trữ đã phân nhánh của bạn với một tên rõ ràng, mô tả phản ánh các thay đổi của bạ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 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ề kiểu của dự án và không đưa 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 thay đổi của bạn cục bộ để xác nhận rằng chúng hoạt động như mong đợi và không gây ra 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 các thay đổi của bạn: Commit các thay đổi của bạn với các commit message ngắn gọn và mô tả. 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ố của vấn đề đó (ví dụ: Fix #123: Corrected calculation error.).
Tạo yêu cầu kéo: Gửi một pull request từ nhánh của bạn đến main nhánh của kho lưu trữ Ultralytics ban đầu. Cung cấp một tiêu đề rõ ràng và một 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ể 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 đú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 yêu cầu kéo của bạn, bot CLA sẽ hướng dẫn bạn quy trình ký kết. Để ký CLA, chỉ cần thêm một nhận xét trong PR của bạn có nội dung:

I have read the CLA Document and I sign the CLA

✍️ Google-Style Docstrings

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

Ví dụ về Docstring

Kiểu GoogleTrả về có tên theo kiểu GoogleTrả về nhiều giá trị theo kiểu GoogleKiểu Google với gợi ý kiểuMột dòng

Ví dụ này minh họa định dạng docstring kiểu Google tiêu chuẩn. Lưu ý cách nó phân tách rõ ràng mô tả hàm, đối số, giá trị trả về và ví dụ để 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

Ví dụ này minh họa cách ghi lại các biến trả về được đặt tên. Sử dụng các giá trị trả về được đặt tên có thể làm cho mã của bạn tự ghi lại và dễ hiểu hơn, đặc biệt đối với các hàm phức tạp.

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

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

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

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

Ví dụ này cho thấy cách ghi lại các hàm trả về nhiều giá trị. Mỗi giá trị trả về phải được ghi lại riêng biệt với kiểu và mô tả riêng để rõ ràng.

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

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

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Lưu ý: Ngay cả khi Python trả về nhiều giá trị dưới dạng một bộ (ví dụ: return masks, scores), luôn ghi lại từng giá trị riêng biệt để rõ ràng và tích hợp công cụ tốt hơn. Khi ghi lại các hàm trả về nhiều giá trị:

✅ Good - Document each return value separately:

Returns:
   (np.ndarray): Predicted masks with shape HxWxN.
   (list): Confidence scores for each instance.

❌ Bad - Don't document as a tuple with nested elements:

Returns:
   (tuple): Tuple containing:
       - (np.ndarray): Predicted masks with shape HxWxN.
       - (list): Confidence scores for each instance.

Ví dụ này kết hợp docstring kiểu Google với gợi ý kiểu Python. Khi sử dụng gợi ý kiểu, bạn có thể bỏ qua thông tin kiểu trong phần đối số docstring, vì nó đã được chỉ định trong chữ ký hàm.

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

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

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

Đối với các hàm nhỏ hơn hoặc đơn giản hơn, một docstring một dòng có thể là đủ. Chúng nên là những câu ngắn gọn nhưng đầy đủ, bắt đầu bằng chữ 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 thử CI 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 GitHub Actions Tích hợp Liên tục (CI) trước khi chúng có thể được hợp nhất. 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 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.

✨ Các phương pháp hay nhất để đóng góp code

Khi đóng góp code cho các dự án Ultralytics, hãy ghi nhớ những phương pháp hay 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 đố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ì các 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.
Cân nhắc khả năng tương thích: Trước khi thực hiện thay đổi, hãy cân nhắc xem chúng có thể phá vỡ 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ề mặt phong cách.
Thêm các kiểm tra phù hợp: Bao gồm các 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 Pull Request

Xem xét các pull request là một cách có giá trị khác để đóng góp. Khi xem xét PR:

Kiểm tra unit test: Xác minh rằng PR bao gồm các thử nghiệm 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 hiệu suất: Cân nhắc xem các thay đổi có thể ảnh hưởng đến hiệu suất như thế nào.
Xác minh các kiểm thử CI: Xác nhận tất cả các kiểm thử Tích hợp Liên tục đều vượt qua.
Đưa ra 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ì một 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ó: Tìm kiếm trước để xem lỗi đã được báo cáo hay chưa.
Cung cấp Ví dụ tái tạo tối thiểu: Tạo một đoạn mã nhỏ, khép kín, tái tạo nhất quán sự cố. Đ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 và 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 dự kiến 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 mọi thông báo lỗi hoặc dấu vết.

📜 Giấy phép

Ultralytics sử dụng Giấy phép Công cộng GNU Affero phiên bản 3.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 dựa trên sự 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ả 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 một cách hiệu quả và có đạo đức cho cộng đồng mã nguồn mở Ultralytics.

🌍 Mã nguồn mở dự án YOLO của bạn theo giấy phép AGPL-3.0

Sử dụng các mô hình hoặc mã 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ở nguồn 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 nguồn mở vẫn mở.

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

Duy trì phần mềm mở: Đảm bảo rằng những cải tiến và các sản 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 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 có được 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 toàn bộ mã nguồn tương ứng của dự án của bạn theo giấy phép AGPL-3.0.

Chọn Điểm Bắt Đầ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 nó một cách chặt chẽ.
- Sử dụng Ultralytics Template: Bắt đầu với Ultralytics template repository để có một thiết lập sạch sẽ, theo mô-đun tích hợp YOLO.
Cấp phép cho Dự án của bạn:
- Thêm một LICENSE tệp chứa toàn bộ nội dung 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 cho biết giấy phép.
Công bố Mã nguồn của bạn:
- Tạo toàn bộ mã nguồn của dự án có thể truy cập công khai (ví dụ: trên GitHub). Bao gồm:
  - Ứng dụng hoặc hệ thống lớn hơn hoàn chỉnh tích 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 script để huấn luyện, xác thực, suy luận.
  - Trọng số mô hình (Model weights) 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 bên thứ ba nào bạn đã sửa đổi.
  - Dữ liệu huấn luyện nếu cần để 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 để tuyên bố rằng 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 Ultralytics YOLO một cách thích hợp, liên kết trở 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 để 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 nguyên tắc 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 đến việc đóng góp cho các dự án Ultralytics mã nguồn mở YOLO. Sự tham gia của bạn rất cần thiết trong việc định hình tương lai của phần mềm 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ã, 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ô giá.

Chúng tôi rất vui mừng được thấy những ý 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, 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 viết code vui vẻ! 🚀🌟

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

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

Đóng góp vào kho mã nguồn mở Ultralytics YOLO giúp cải thiện phần mềm, làm cho 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ã, 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, đó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à danh tiếng của bạn. Để biết chi tiết về cách bắt đầu, hãy tham khảo phần Đóng góp qua Yêu cầu Kéo.

Làm cách nào để 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 bot CLA 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 nhận xét vào pull request của bạn có 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 kiểu Google là gì và tại sao chúng lại cần thiết cho các đóng góp của Ultralytics YOLO?

Docstring kiểu Google cung cấp tài liệu rõ ràng, ngắn gọn cho các hàm và lớp, cải thiện khả năng đọc và bảo trì mã. 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 vào Ultralytics YOLO, việc tuân theo docstring kiểu Google đảm bảo rằng các bổ sung của bạn được ghi lại đầy đủ và dễ hiểu. Để biết các ví dụ và hướng dẫn, hãy truy cập phần Docstring Kiểu Google.

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

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, unit test 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à các mẹo khắc phục sự cố, hãy xem phần Kiểm tra CI của GitHub Actions.

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

Để báo cáo lỗi, hãy cung cấp một Ví dụ Tái tạo Tối thiểu 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 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 đề. Để 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.

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ã 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 (công việc 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 rằng bản chất mã 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 có được Giấy phép Doanh nghiệp. Xem phần Mở mã nguồn dự án của bạn để biết chi tiết.

📅 Đã tạo 1 năm trước ✏️ Cập nhật 2 tháng trước