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

Chào mừng! Chúng tôi rất vui khi bạn cân nhắc đóng góp cho các dự án mã nguồn mở của Ultralytics. Sự tham gia của bạn không chỉ giúp nâng cao chất lượng các 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à phương pháp tốt nhất để giúp bạn bắt đầu.

Quy tắc ứng xử#

Để đảm bảo môi trường thân thiện và hòa nhập cho 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. Tôn trọng, tử tế và tính chuyên nghiệp là những giá trị cốt lõi của cộng đồng.

Đóng góp thông qua Pull Request#

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

1. Fork repository: Bắt đầu bằng cách fork repository Ultralytics liên quan (ví dụ: ultralytics/ultralytics) vào tài khoản GitHub của bạn.
2. Tạo branch: Tạo branch mới trong repository đã fork, đặt tên rõ ràng và mô tả các thay đổi của bạn (ví dụ: fix-issue-123, add-feature-xyz).
3. Thực hiện thay đổi: Triển khai các cải tiến hoặc bản sửa lỗi. Đảm bảo code tuân thủ quy chuẩn định dạng của dự án và không gây ra lỗi hoặc cảnh báo mới.
4. Kiểm thử thay đổi: Trước khi gửi, hãy kiểm thử các thay đổi trên máy cục bộ để xác nhận chúng hoạt động như mong đợi và không gây lỗi hồi quy. Hãy bổ sung bài kiểm thử nếu bạn thêm chức năng mới.
5. Commit các thay đổi: Commit các thay đổi với thông điệp ngắn gọn, mô tả rõ nội dung. Nếu thay đổi giải quyết một issue cụ thể, hãy thêm số issue (ví dụ: Fix #123: Corrected calculation error.).
6. Tạo pull request: Gửi pull request từ branch của bạn đến branch main trong repository Ultralytics gốc. Đặt tiêu đề rõ ràng và viết mô tả chi tiết về mục đích cũng như phạm vi thay đổi.

Cài đặt môi trường phát triển#

Clone fork của bạn (hoặc repository chính) và cài đặt ở chế độ editable (-e) để Python chạy các file cục bộ và nhận mọi thay đổi mà không cần cài đặt lại:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

Để một dự án khác phụ thuộc vào fork thay vì package PyPI, hãy trỏ pip hoặc requirements.txt đến branch của fork:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

Thay đổi tài liệu#

Mã nguồn tài liệu nằm trong docs/en/. Từ thư mục gốc của repository, hãy cài đặt các dependency phát triển và chạy toàn bộ quy trình kiểm tra nghiêm ngặt trước khi mở PR:

uv pip install -e ".[dev]"
python docs/build_docs.py

Quy trình kiểm tra chuẩn bị các tài liệu tham chiếu, macro và trang so sánh được tạo tự động trước khi chạy zensical build --strict. Để xem trước trực tiếp nhanh hơn các trang không dùng macro, hãy chạy zensical serve.

Ký CLA#

Trước khi có thể merge pull request, bạn phải ký Thỏa thuận cấp phép cho người đóng góp (CLA). Thỏa thuận pháp lý này đảm bảo các đóng góp của bạn được cấp phép phù hợp, 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 hoàn tất quy trình ký. Để ký CLA, chỉ cần thêm một comment vào PR với nội dung:

I have read the CLA Document and I sign the CLA

Docstring theo phong cách Google#

Khi thêm hàm hoặc class mới, hãy viết docstring theo phong cách Google để tài liệu rõ ràng và nhất quán. Luôn đặt cả types đầu vào và đầu ra trong dấu ngoặc đơn (ví dụ: (bool), (np.ndarray)).

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 bằng GitHub Actions#

Tất cả pull request phải vượt qua các bài kiểm thử Tích hợp liên tục (CI) chạy bằng GitHub Actions trước khi được merge. Các bài kiểm thử này bao gồm lint, unit test và những bước kiểm tra khác để đảm bảo thay đổi đáp ứng tiêu chuẩn chất lượng của dự án. Hãy xem kết quả CI và xử lý mọi vấn đề phát sinh.

Phương pháp tốt nhất khi đóng góp code#

Khi đóng góp code cho các dự án Ultralytics, hãy ghi nhớ các phương pháp tốt nhất sau:

• Tránh trùng lặp code: Tái sử dụng code hiện có bất cứ khi nào có thể và giảm thiểu các tham số không cần thiết.
• Thực hiện thay đổi nhỏ, tập trung: Ưu tiên các chỉnh sửa có mục tiêu thay vì thay đổi trên quy mô lớn.
• Đơn giản hóa khi có thể: Tìm cơ hội đơn giản hóa code 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 thay đổi, hãy cân nhắc liệu chúng có thể làm hỏng code hiện có đang sử dụng Ultralytics hay không.
• Định dạng nhất quán: Các công cụ như Ruff Formatter có thể giúp duy trì sự nhất quán về phong cách.
• Bổ sung bài kiểm thử phù hợp: Thêm 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.

Review Pull Request#

Review pull request là một cách đóng góp hữu ích khác. Khi review PR:

• Kiểm tra unit test: Xác minh PR có bài kiểm thử cho các tính năng hoặc thay đổi mới.
• Review 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 các thay đổi có thể ảnh hưởng như thế nào đến hiệu năng.
• Xác minh các bài kiểm thử CI: Xác nhận tất cả bài kiểm thử Tích hợp liên tục đều thành công.
• Đưa ra phản hồi mang tính xây dựng: Nêu phản hồi cụ thể, rõ ràng về mọi vấn đề hoặc mối quan ngại.
• 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 rất coi trọng các báo cáo lỗi vì chúng giúp cải thiện chất lượng và độ tin cậy của dự án. Khi báo cáo lỗi qua GitHub Issues:

• Kiểm tra các issue hiện có: Trước tiên, hãy tìm kiếm để xem lỗi đã được báo cáo chưa.
• Cung cấp Ví dụ tối thiểu có thể tái hiện: Tạo một đoạn mã nhỏ, độc lập có thể tái hiện lỗi một cách ổn định. Đây là điều thiết yếu để gỡ lỗi hiệu quả.
• Mô tả môi trường: Nêu hệ điều hành, phiên bản Python, phiên bản các 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 và thực tế: Nêu rõ điều bạn mong đợi sẽ xảy ra và điều thực sự đã xảy ra. Đính kèm mọi thông báo lỗi hoặc traceback.

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 repository của mình. Giấy phép này thúc đẩy tính cởi mở, tính minh bạch và cải tiến hợp tác trong quá trình phát triển phần mềm. Giấy phép bảo đảm mọi người dùng đều có quyền sử dụng, sửa đổi và chia sẻ phần mềm, qua đó thúc đẩy một cộng đồng hợp tác và đổi mới vững mạnh.

Chúng tôi khuyến khích tất cả cộng tác viên tìm hiểu kỹ các điều khoản của giấy phép AGPL-3.0 để đóng góp hiệu quả và có trách nhiệm cho cộng đồng mã nguồn mở Ultralytics.

Phát hành dự án YOLO dưới dạng mã nguồn mở theo AGPL-3.0#

Bạn đang sử dụng model hoặc mã nguồn Ultralytics YOLO trong dự án của mình? 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 phát hành dưới dạng mã nguồn mở theo AGPL-3.0. Điều này bảo đảm các sửa đổi và dự án lớn hơn được xây dựng trên nền tảng mã nguồn mở tiếp tục được duy trì ở dạng mở.

Vì sao việc tuân thủ AGPL-3.0 quan trọng#

• Giữ phần mềm ở dạng mở: Bảo đảm 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ý: Việc sử dụng mã nguồn được cấp phép theo AGPL-3.0 khiến dự án của bạn phải tuân theo các điều khoản của giấy phép.
• Thúc đẩy hợp tác: Khuyến khích chia sẻ và minh bạch.

Nếu không muốn phát hành dự án dưới dạng mã nguồn mở, hãy cân nhắc mua Giấy phép Enterprise.

Cách tuân thủ AGPL-3.0#

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

1. Chọn điểm khởi đầu:

   • Fork Ultralytics YOLO: Fork trực tiếp repository Ultralytics YOLO nếu bạn đang xây dựng dựa sát trên repository này.
   • Sử dụng template Ultralytics: Bắt đầu với repository template Ultralytics để có cấu trúc gọn gàng, mô-đun và tích hợp YOLO.

2. Cấp phép cho dự án:

   • Thêm tệp LICENSE chứa toàn văn giấy phép AGPL-3.0.
   • Thêm thông báo về giấy phép ở đầu mỗi tệp mã nguồn.

3. Phát hành mã nguồn:

   • Công khai toàn bộ mã nguồn dự án (ví dụ: trên GitHub). Nội dung này bao gồm:
     • Ứng dụng hoặc hệ thống lớn hoàn chỉnh tích hợp model hoặc mã nguồn YOLO.
     • Mọi sửa đổi đối với mã nguồn Ultralytics YOLO ban đầu.
     • Các script huấn luyện, xác thực và suy luận.
     • Trọng số model nếu đã được sửa đổi hoặc fine-tune.
     • Tệp cấu hình, cấu hình môi trường (requirements.txt, Dockerfiles).
     • Mã nguồn backend và frontend nếu thuộc một ứng dụng web.
     • Mọi thư viện bên thứ ba mà 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 phép phân phối lại.

4. Tài liệu rõ ràng:

   • Cập nhật README.md để nêu rõ dự án được cấp phép theo AGPL-3.0.
   • Cung cấp hướng dẫn rõ ràng về cách thiết lập, build và chạy dự án từ mã nguồn.
   • Ghi công Ultralytics YOLO phù hợp và dẫn liên kết đến repository 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 repository mẫu#

Tham khảo Repository Template Ultralytics để xem một cấu trúc mẫu 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 bảo đảm tuân thủ AGPL-3.0 và hỗ trợ hệ sinh thái mã nguồn mở giúp tạo nên những 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 các dự án YOLO Ultralytics mã nguồn mở. Sự tham gia của bạn đóng vai trò thiết yếu trong việc định hình tương lai phần mềm và xây dựng một cộng đồng đổi mới, hợp tác sôi nổi. Dù bạn cải tiến mã nguồn, báo cáo lỗi hay đề xuất tính năng mới, mọi đóng góp của bạn đều vô cùng quý giá.

Chúng tôi rất mong được thấy các ý tưởng của bạn 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. Hãy cùng tiếp tục phát triển và đổi mới trong hành trình mã nguồn mở đầy hứng khởi này.

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