Ultralytics 오픈 소스 프로젝트에 기여하기

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

풀 리퀘스트를 병합하려면 먼저 모든 GitHub Actions 지속적 통합(CI) 테스트를 통과해야 합니다. 이러한 테스트에는 코드가 프로젝트의 품질 표준을 충족하는지 확인하기 위한 린팅, 단위 테스트 및 기타 검사가 포함됩니다. CI 결과물을 검토하고 문제를 수정합니다. CI 프로세스 및 문제 해결 팁에 대한 자세한 내용은 GitHub Actions CI 테스트 섹션을 참조하세요.

환영합니다! 저희 Ultralytics 오픈 소스 프로젝트에 기여하는 것을 고려해 주셔서 매우 기쁩니다. 여러분의 참여는 저희 저장소의 품질을 향상시킬 뿐만 아니라 전체 컴퓨터 비전 커뮤니티에도 도움이 됩니다. 이 가이드는 시작하는 데 도움이 되는 명확한 지침과 모범 사례를 제공합니다.

Watch: Ultralytics 리포지토리에 기여하는 방법 | Ultralytics 모델, 데이터 세트 및 설명서 🚀

🤝 행동 강령

모두를 위한 환영하고 포용적인 환경을 보장하기 위해 모든 기여자는 행동 강령을 준수해야 합니다. 우리 커뮤니티의 핵심은 존중, 친절, 전문성입니다.

🚀 Pull Requests를 통한 기여

Pull requests (PRs) 형태로 기여해 주시는 것에 대해 매우 감사드립니다. 검토 프로세스를 최대한 원활하게 진행하려면 다음 단계를 따르십시오.

리포지토리 포크: GitHub 계정으로 관련 Ultralytics 리포지토리(예: ultralytics/ultralytics)를 포크하여 시작합니다.
브랜치 생성: 변경 사항을 반영하는 명확하고 설명적인 이름(예: )으로 포크된 리포지토리에서 새 분기를 만듭니다. fix-issue-123, add-feature-xyz).
변경 사항 적용: 개선 사항 또는 수정 사항을 구현합니다. 코드가 프로젝트의 스타일 지침을 준수하고 새로운 오류나 경고를 발생시키지 않는지 확인하십시오.
변경 사항 테스트: 제출하기 전에 변경 사항을 로컬에서 테스트하여 예상대로 작동하는지 확인하고 회귀를 일으키지 않는지 확인하십시오. 새로운 기능을 도입하는 경우 테스트를 추가하십시오.
변경 사항 커밋: 간결하고 설명적인 커밋 메시지와 함께 변경 사항을 커밋하십시오. 변경 사항이 특정 이슈를 해결하는 경우 이슈 번호를 포함하십시오 (예: Fix #123: Corrected calculation error.).
Pull Request 생성: 브랜치에서 풀 리퀘스트를 제출하여 main 원본 Ultralytics 저장소의 분기입니다. 변경 목적과 범위를 설명하는 명확한 제목과 자세한 설명을 제공하세요.

📝 CLA 서명

풀 리퀘스트를 병합하기 전에 기여자 라이선스 계약(CLA)에 서명해야 합니다. 이 법적 계약은 귀하의 기여가 적절하게 라이선스되어 프로젝트가 AGPL-3.0 라이선스에 따라 계속 배포될 수 있도록 보장합니다.

풀 리퀘스트를 제출하면 CLA 봇이 서명 절차를 안내합니다. CLA에 서명하려면 PR에 코멘트를 추가하기만 하면 됩니다:

I have read the CLA Document and I sign the CLA

✍️ Google 스타일 독스트링

새로운 함수나 클래스를 추가할 때는 다음 사항을 포함하세요. Google 스타일 독스트링 명확하고 표준화된 문서를 위해 항상 입력과 출력을 모두 묶으십시오. types 괄호 안에 있습니다(예: (bool), (np.ndarray)).

문서 문자열 예제

Google-스타일Google 스타일 명명된 반환Google 스타일 다중 반환Google-유형 힌트가 있는 스타일단일 라인

이 예제는 표준 Google 스타일 독스트링 형식을 보여줍니다. 함수 설명, 인수, 반환 값 및 예제를 명확하게 분리하여 가독성을 극대화하는 방법에 유의하십시오.

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

이 예제에서는 명명된 반환 변수를 문서화하는 방법을 보여줍니다. 명명된 반환 값을 사용하면 특히 복잡한 함수의 경우 코드를 더 쉽게 문서화하고 이해하기 쉽게 만들 수 있습니다.

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

이 예제에서는 여러 값을 반환하는 함수를 문서화하는 방법을 보여줍니다. 명확성을 위해 각 반환 값은 자체 타입 및 설명과 함께 별도로 문서화해야 합니다.

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

참고: python은 여러 값을 튜플로 반환하지만 (예: return masks, scores), 명확성과 더 나은 도구 통합을 위해 항상 각 값을 개별적으로 문서화하십시오. 여러 값을 반환하는 함수를 문서화할 때:

✅ 좋음 - 각 반환 값을 개별적으로 문서화합니다.

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

❌ 나쁨 - 중첩된 요소가 있는 튜플로 문서화하지 마십시오.

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

이 예제에서는 Google 스타일의 독스트링과 Python 타입 힌트를 결합합니다. 타입 힌트를 사용하는 경우 함수 시그니처에 이미 지정되어 있으므로 독스트링 인수 섹션에서 타입 정보를 생략할 수 있습니다.

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

더 작거나 간단한 함수의 경우, 한 줄의 독스트링으로도 충분할 수 있습니다. 이러한 독스트링은 대문자로 시작하고 마침표로 끝나는 간결하면서도 완전한 문장이어야 합니다.

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

✅ GitHub Actions CI 테스트

모든 Pull Request는 병합되기 전에 GitHub Actions 지속적 통합(CI) 테스트를 통과해야 합니다. 이러한 테스트에는 린팅, 단위 테스트 및 귀하의 변경 사항이 프로젝트의 품질 표준을 충족하는지 확인하기 위한 기타 검사가 포함됩니다. CI 출력을 검토하고 발생하는 모든 문제를 해결하십시오.

✨ 코드 기여에 대한 모범 사례

Ultralytics 프로젝트에 코드를 기여할 때는 다음 모범 사례를 염두에 두십시오.

코드 중복 방지: 가능한 한 기존 코드를 재사용하고 불필요한 인수를 최소화합니다.
더 작고 집중적인 변경 수행: 대규모 변경보다는 목표 수정에 집중하십시오.
가능하면 단순화하십시오: 코드를 단순화하거나 불필요한 부분을 제거할 기회를 찾으십시오.
호환성 고려: 변경하기 전에 Ultralytics를 사용하는 기존 코드를 손상시킬 수 있는지 고려하십시오.
일관된 형식 사용: Ruff Formatter와 같은 도구는 스타일 일관성을 유지하는 데 도움이 될 수 있습니다.
적절한 테스트 추가: 새로운 기능이 예상대로 작동하는지 확인하기 위해 테스트를 포함합니다.

👀 Pull Requests 검토

Pull Requests를 검토하는 것도 기여하는 또 다른 중요한 방법입니다. PR을 검토할 때:

단위 테스트 확인: PR에 새로운 기능 또는 변경 사항에 대한 테스트가 포함되어 있는지 확인하십시오.
문서 업데이트 검토: 변경 사항을 반영하도록 문서가 업데이트되었는지 확인합니다.
Evaluate performance impact: 변경 사항이 성능에 어떤 영향을 미칠 수 있는지 고려하십시오.
CI 테스트 확인: 모든 지속적 통합 테스트가 통과했는지 확인합니다.
건설적인 피드백 제공: 문제나 우려 사항에 대해 구체적이고 명확한 피드백을 제공하십시오.
노력 인정: 긍정적인 협업 분위기를 유지하기 위해 작성자의 작업을 인정합니다.

🐞 버그 신고

버그 보고서는 프로젝트의 품질과 안정성을 개선하는 데 도움이 되므로 매우 중요하게 생각합니다. GitHub Issues를 통해 버그를 보고할 때:

기존 이슈 확인: 버그가 이미 보고되었는지 먼저 검색하십시오.
최소 재현 가능 예제 제공: 문제를 일관되게 재현하는 작고 독립적인 코드 스니펫을 만드십시오. 이는 효율적인 디버깅에 매우 중요합니다.
환경 설명: 운영 체제, python 버전, 관련 라이브러리 버전(예: torch, ultralytics), 그리고 하드웨어(CPU/GPU).
예상 동작과 실제 동작 비교 설명: 예상되는 동작과 실제로 발생한 동작을 명확하게 설명하십시오. 오류 메시지 또는 트레이스백을 포함하십시오.

📜 라이선스

Ultralytics 리포지토리에 GNU Affero 일반 공중 라이선스 v3.0(AGPL-3.0) 을 사용합니다. 이 라이선스는 소프트웨어 개발의 개방성, 투명성, 협업적 개선을 촉진합니다. 모든 사용자가 소프트웨어를 자유롭게 사용, 수정, 공유할 수 있도록 보장하여 강력한 협업과 혁신의 커뮤니티를 조성합니다.

Ultralytics 오픈 소스 커뮤니티에 효과적이고 윤리적으로 기여하려면 모든 기여자가 AGPL-3.0 라이선스 약관을 숙지하는 것이 좋습니다.

🌍 AGPL-3.0 하에 YOLO 프로젝트 오픈 소싱하기

프로젝트에서 Ultralytics YOLO 모델 또는 코드를 사용하시나요? AGPL-3.0 라이선스에 따라 파생 저작물 전체를 AGPL-3.0으로 오픈 소스화해야 합니다. 이를 통해 오픈 소스 기반으로 구축된 수정 사항과 대규모 프로젝트가 계속 오픈 상태를 유지할 수 있습니다.

AGPL-3.0 규정 준수가 중요한 이유

소프트웨어를 개방적으로 유지: 개선 사항 및 파생 저작물이 커뮤니티에 도움이 되도록 보장합니다.
법적 요구 사항: AGPL-3.0 라이선스 코드를 사용하면 프로젝트가 해당 조건에 구속됩니다.
협업 촉진: 공유와 투명성을 장려합니다.

프로젝트를 오픈 소스로 공개하고 싶지 않다면 엔터프라이즈 라이선스를 획득하는 것을 고려해 보십시오.

AGPL-3.0 준수 방법

규정 준수는 프로젝트의 완전한 해당 소스 코드를 AGPL-3.0 라이선스 하에 공개적으로 사용할 수 있도록 하는 것을 의미합니다.

시작점 선택:
- Ultralytics YOLO 포크: Ultralytics YOLO 저장소를 기반으로 빌드하는 경우 직접 포크하십시오.
- Ultralytics 템플릿 사용: YOLO를 통합하는 깔끔하고 모듈식 설정을 위해 Ultralytics 템플릿 저장소로 시작하십시오.
프로젝트 라이선스:
- 다음 LICENSE 전체 텍스트가 포함된 파일 AGPL-3.0 라이선스.
- 각 소스 파일 상단에 라이선스 고지를 추가합니다.
소스 코드 게시:
- 다음을 만드세요 전체 프로젝트의 소스 코드 공개적으로 액세스 가능합니다 (예: GitHub). 여기에는 다음이 포함됩니다.
  - YOLO 모델 또는 코드를 통합하는 더 크고 완전한 애플리케이션 또는 시스템입니다.
  - 원본 Ultralytics YOLO 코드에 대한 모든 수정 사항.
  - 학습, 유효성 검사, 추론을 위한 스크립트.
  - 수정되거나 미세 조정된 경우 모델 가중치.
  - 구성 파일, 환경 설정(requirements.txt, Dockerfiles).
  - 웹 애플리케이션의 일부인 경우 백엔드 및 프론트엔드 코드.
  - 수정된 타사 라이브러리입니다.
  - 재학습 및 재배포를 실행하는 데 필요한 학습 데이터입니다.
명확하게 문서화:
- 다음 항목 업데이트: README.md 프로젝트가 AGPL-3.0에 따라 라이선스되었음을 명시합니다.
- 소스 코드에서 프로젝트를 설정, 빌드 및 실행하는 방법에 대한 명확한 지침을 포함합니다.
- Ultralytics YOLO의 출처를 적절히 밝히고 다음으로 링크하십시오. 원본 저장소. 예제:
```
This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.
```

리포지토리 구조 예시

실용적인 예제 구조는 Ultralytics 템플릿 저장소를 참조하십시오.

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

이러한 지침을 따르면 AGPL-3.0을 준수하여 Ultralytics YOLO와 같은 강력한 도구를 지원하는 오픈 소스 에코시스템을 지원할 수 있습니다.

🎉 결론

오픈소스 프로젝트에 관심을 가져주셔서 감사합니다. Ultralytics 오픈소스 YOLO 프로젝트에 기여해 주셔서 감사합니다. 여러분의 참여는 소프트웨어의 미래를 만들고 혁신과 협업의 활기찬 커뮤니티를 구축하는 데 필수적입니다. 코드를 개선하거나 버그를 보고하거나 새로운 기능을 제안하는 등 여러분의 기여는 매우 소중합니다.

여러분의 아이디어가 실현되는 것을 보게 되어 기쁘고, 물체 인식 기술을 발전시키기 위한 여러분의 노력에 감사드립니다. 여러분과 함께 이 흥미진진한 오픈소스 여정에서 계속 성장하고 혁신해 나갑시다. 행복한 코딩! 🚀🌟

자주 묻는 질문

Ultralytics YOLO 오픈소스 리포지토리에 기여해야 하는 이유는 무엇인가요?

Ultralytics YOLO 오픈 소스 리포지토리에 기여하면 소프트웨어가 개선되어 전체 커뮤니티를 위해 더욱 강력하고 풍부한 기능을 제공합니다. 기여에는 코드 개선, 버그 수정, 문서 개선 및 새로운 기능 구현이 포함될 수 있습니다. 또한, 기여를 통해 해당 분야의 다른 숙련된 개발자 및 전문가와 협업하여 자신의 기술과 평판을 높일 수 있습니다. 시작하는 방법에 대한 자세한 내용은 풀 리퀘스트를 통해 기여하기 섹션을 참조하세요.

Ultralytics YOLO 에 대한 기여자 라이선스 계약(CLA)에 어떻게 서명하나요?

기여자 라이선스 계약(CLA)에 서명하려면 풀 리퀘스트를 제출한 후 CLA 봇이 제공하는 지침을 따르세요. 이 프로세스를 통해 여러분의 기여가 AGPL-3.0 라이선스에 따라 적절하게 라이선스가 부여되어 오픈소스 프로젝트의 법적 무결성을 유지할 수 있습니다. 풀 리퀘스트에 다음과 같은 코멘트를 추가하세요:

I have read the CLA Document and I sign the CLA

자세한 내용은 CLA 서명 섹션을 참조하세요.

Google-스타일 문서 문자열이란 무엇이며 Ultralytics YOLO 기여에 필요한 이유는 무엇인가요?

Google-스타일 독스트링은 함수와 클래스에 대한 명확하고 간결한 문서를 제공하여 코드 가독성과 유지보수성을 향상시킵니다. 이러한 독스트링은 함수의 목적, 인수, 반환값을 특정 서식 규칙과 함께 간략하게 설명합니다. Ultralytics YOLO 에 기여하실 때 Google-스타일의 문서 문자열을 따르면 추가한 내용이 잘 문서화되고 쉽게 이해될 수 있습니다. 예제와 가이드라인은 Google-스타일 독스트링 섹션을 참조하세요.

내 변경 사항이 GitHub Actions CI 테스트를 통과하려면 어떻게 해야 하나요?

풀 리퀘스트가 병합되기 전에 모든 GitHub Actions CI(Continuous Integration) 테스트를 통과해야 합니다. 이러한 테스트에는 린팅, 단위 테스트 및 코드가 프로젝트의 품질 표준을 충족하는지 확인하기 위한 기타 검사가 포함됩니다. CI 출력을 검토하고 문제를 해결하십시오. CI 프로세스 및 문제 해결 팁에 대한 자세한 내용은 GitHub Actions CI 테스트 섹션을 참조하십시오.

Ultralytics YOLO 리포지토리에서 버그를 신고하려면 어떻게 하나요?

버그를 신고하려면 버그 신고와 함께 명확하고 간결한 최소 재현 가능한 예시를 제공하세요. 이렇게 하면 개발자가 문제를 빠르게 파악하고 수정하는 데 도움이 됩니다. 최소한의 예제이지만 문제를 재현하기에 충분한지 확인하세요. 버그 신고에 대한 자세한 단계는 버그 신고하기 섹션을 참조하세요.

Ultralytics YOLO를 자체 프로젝트에서 사용하는 경우 AGPL-3.0 라이선스는 무엇을 의미합니까?

프로젝트에서 Ultralytics YOLO 코드 또는 모델(AGPL-3.0 라이선스)을 사용하는 경우, AGPL-3.0 라이선스에 따라 전체 프로젝트(파생 저작물) 또한 AGPL-3.0 라이선스로 사용 허가되어야 하며, 전체 소스 코드를 공개적으로 제공해야 합니다. 이는 소프트웨어의 오픈 소스 특성이 파생물 전체에서 유지되도록 보장합니다. 이러한 요구 사항을 충족할 수 없는 경우, Enterprise License를 획득해야 합니다. 자세한 내용은 프로젝트 오픈 소싱 섹션을 참조하십시오.

📅1 년 전 생성됨 ✏️ 1개월 전 업데이트됨