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

Chào mừng bạn! Chúng tôi rất vui khi 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 các repository 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 nguyên tắc rõ ràng và phương pháp tốt nhất để giúp bạn bắt đầu.

Bộ quy tắc ứng xử#

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

Đóng góp qua PR#

Chúng tôi đánh giá rất cao các đóng góp dưới hình thức pull request (PR). Để quy trình review diễn ra suôn sẻ nhất có thể, vui lòng thực hiện các bước sau:

1. Fork repository: Bắt đầu bằng cách fork repository Ultralytics phù hợp (ví dụ: ultralytics/ultralytics) vào tài khoản GitHub của bạn.
2. Tạo branch: Tạo một branch mới trong repository đã fork với tên rõ ràng, mô tả đúng 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. Bảo đảm code của bạn tuân thủ quy ước style của project và không tạo thêm lỗi hoặc cảnh báo mới.
4. Kiểm thử các thay đổi: Trước khi gửi, hãy kiểm thử các thay đổi locally để xác nhận chúng hoạt động như mong đợi và không gây ra regression. Hãy thêm test nếu bạn giới thiệu chức năng mới.
5. Commit các thay đổi: Commit các thay đổi với message ngắn gọn và có tính mô tả. Nếu thay đổi của bạn xử lý 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 của repository Ultralytics gốc. Cung cấp tiêu đề rõ ràng và mô tả chi tiết giải thích mục đích cũng như phạm vi thay đổi.

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

Sao chép bản rẽ nhánh (hoặc kho lưu trữ chính) và cài đặt ở chế độ chỉnh sửa (-e) để Python chạy các tệp cục bộ và nhận diệ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 .

Để cấu hình một dự án khác phụ thuộc vào một bản rẽ nhánh thay vì gói PyPI, hãy trỏ pip hoặc requirements.txt đến nhánh của bản rẽ nhánh:

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

Thay đổi tài liệu#

Source của tài liệu nằm trong docs/en/. Từ root của repository, hãy cài đặt các dependency phát triển và chạy toàn bộ quy trình validation strict trước khi mở PR:

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

Quy trình validation sẽ chuẩn bị các reference, macro và trang so sánh được sinh tự động trước khi chạy zensical build --strict. Để preview live nhanh hơn đối với các trang không sử dụng macro, hãy chạy zensical serve.

Ký thỏa thuận đóng góp CLA#

Trước khi chúng tôi có thể merge pull request của bạn, bạn phải ký Thỏa thuận cấp phép Contributor (CLA) của chúng tôi. Thỏa thuận pháp lý này bảo đảm các đóng góp của bạn được cấp phép phù hợp, cho phép project 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 qua quy trình ký. Để ký CLA, chỉ cần thêm một comment trong PR của bạn 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 function hoặc class mới, hãy bao gồm docstring theo phong cách Google để cung cấp tài liệu rõ ràng, thống nhất. 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 trên GitHub Actions#

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

Các phương pháp hay nhất cho đóng góp mã nguồn#

Khi đóng góp code cho các project 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 argument không cần thiết.
• Thực hiện các thay đổi nhỏ, tập trung: Tập trung vào những 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 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.
• 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ề style.
• Thêm test phù hợp: Bao gồm test cho các tính năng mới để bảo đảm chúng hoạt động như mong đợi.

Xem xét các PR#

Review pull request là một cách đóng góp có giá trị khác. Khi review PR:

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

• Kiểm tra issue hiện có: Tìm kiếm trước để xem bug đã được báo cáo hay chưa.
• Cung cấp Ví dụ tối thiểu có thể tái hiện: Tạo một đoạn code nhỏ, độc lập, luôn tái hiện được issue. Đây là yếu tố quan trọng để debug 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 library liên quan (ví dụ: torch, ultralytics) và hardware (CPU/GPU).
• Giải thích hành vi kỳ vọng so với thực tế: Nêu rõ điều bạn mong đợi sẽ xảy ra và điều thực tế đã xảy ra. Bao gồm mọi error message hoặc traceback.

License#

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 phát triển phần mềm. Giấy phép bảo đảm mọi người dùng có quyền tự do sử dụng, sửa đổi và chia sẻ phần mềm, từ đó 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ả contributor 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ó trách nhiệm cho cộng đồng mã nguồn mở Ultralytics.

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

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

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

• Duy trì phần mềm 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 code được cấp phép theo AGPL-3.0 ràng buộc project của bạn với các điều khoản của giấy phép.
• Thúc đẩy cộng tác: Khuyến khích chia sẻ và minh bạch.

Nếu không muốn phát hành project 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 project theo giấy phép AGPL-3.0.

1. Chọn điểm bắt đầu:

   • Fork Ultralytics YOLO: Fork trực tiếp repository Ultralytics YOLO nếu project được xây dựng gần như dựa trên repository này.
   • Sử dụng Template của Ultralytics: Bắt đầu với repository template của Ultralytics để có cấu trúc sạch, module hóa và tích hợp YOLO.

2. Cấp phép cho project của bạn:

   • Thêm file LICENSE chứa toàn văn giấy phép AGPL-3.0.
   • Thêm thông báo ở đầu mỗi file source để chỉ rõ giấy phép.

3. Công khai source code:

   • Công khai toàn bộ source code của project (ví dụ: trên GitHub). Nội dung này bao gồm:
     • Toàn bộ ứng dụng hoặc hệ thống lớn có tích hợp model hoặc code YOLO.
     • Mọi sửa đổi được thực hiện trên code Ultralytics YOLO gốc.
     • Các script dùng để training, validation và inference.
     • Model weight nếu đã được sửa đổi hoặc fine-tune.
     • File cấu hình, thiết lập môi trường (requirements.txt, Dockerfiles).
     • Code backend và frontend nếu là một phần của ứng dụng web.
     • Mọi library bên thứ ba mà bạn đã sửa đổi.
     • Dữ liệu training nếu cần để chạy/đào tạo lại và có thể tái phân phối.

4. Ghi tài liệu rõ ràng:

   • Cập nhật README.md để nêu rõ project đượ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, build và chạy project từ source code.
   • Ghi công Ultralytics YOLO phù hợp, kèm 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 ví dụ#

Tham khảo Ultralytics Template Repository để xem một cấu trúc 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 thủ 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ở, nền tảng cho những công cụ mạnh mẽ như Ultralytics YOLO.

Kết luận#

Cảm ơn bạn đã quan tâm đến các project 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 động. Dù bạn cải tiến code, báo cáo bug 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 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. Hãy cùng nhau tiếp tục phát triển và đổi mới trong hành trình mã nguồn mở đầy hào hứng này.

FAQ#