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

환영합니다! Ultralytics 오픈 소스 프로젝트에 기여해 주시려는 여러분의 뜻을 기쁘게 생각합니다. 여러분의 참여는 저장소의 품질을 높이는 데 도움이 될 뿐만 아니라 전체 컴퓨터 비전 커뮤니티에도 도움이 됩니다. 이 가이드에서는 기여를 시작하는 데 필요한 명확한 지침과 모범 사례를 제공합니다.

행동 강령#

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

풀 리퀘스트로 기여하기#

풀 리퀘스트(PR) 형식의 기여를 매우 환영합니다. 리뷰 과정을 최대한 원활하게 진행하려면 다음 단계를 따르세요.

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

개발 환경 설치#

포크(또는 메인 저장소)를 클론하고 editable 모드(-e)로 설치하면, Python이 로컬 파일을 실행하고 재설치 없이 모든 변경 사항을 반영합니다.

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

다른 프로젝트가 PyPI 패키지 대신 포크에 의존하도록 하려면 pip 또는 requirements.txt이 포크의 브랜치를 가리키도록 설정합니다.

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

문서 변경#

문서 소스는 docs/en/ 아래에 있습니다. 저장소 루트에서 개발용 종속 항목을 설치하고 PR을 열기 전에 전체 엄격 검증을 실행합니다.

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

검증 과정에서는 zensical build --strict을 실행하기 전에 생성된 참조 자료, 매크로, 비교 페이지를 준비합니다. 매크로를 사용하지 않는 페이지를 더 빠르게 실시간 미리 보려면 zensical serve을 실행합니다.

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)).

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

GitHub Actions CI 테스트#

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

코드 기여 모범 사례#

Ultralytics 프로젝트에 코드를 기여할 때 다음 모범 사례를 염두에 두세요.

• 코드 중복 방지: 가능한 한 기존 코드를 재사용하고 불필요한 인수를 최소화합니다.
• 작고 명확한 범위의 변경: 대규모 변경보다 범위를 명확히 한 수정에 집중합니다.
• 가능한 경우 단순화: 코드를 단순화하거나 불필요한 부분을 제거할 방법을 찾습니다.
• 호환성 고려: 변경하기 전에 Ultralytics를 사용하는 기존 코드가 영향을 받을지 고려합니다.
• 일관된 형식 사용: Ruff Formatter와 같은 도구를 사용하면 스타일의 일관성을 유지할 수 있습니다.
• 적절한 테스트 추가: 새로운 기능이 예상대로 작동하는지 확인하기 위해 테스트를 포함합니다.

풀 리퀘스트 리뷰#

풀 리퀘스트를 리뷰하는 것도 가치 있는 기여 방법입니다. PR을 리뷰할 때는 다음을 확인하세요.

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

버그 보고#

버그 보고는 프로젝트의 품질과 신뢰성을 개선하는 데 도움이 되므로 매우 중요하게 생각합니다. GitHub Issues를 통해 버그를 보고할 때는 다음 사항을 지켜 주세요.

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

라이선스#

Ultralytics는 저장소에 GNU Affero 일반 공중 사용 허가서 버전 3.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을 준수하려면 프로젝트의 전체 대응 소스 코드를 AGPL-3.0 라이선스에 따라 공개적으로 제공해야 합니다.

1. 시작 방식 선택:

   • Ultralytics YOLO 포크: Ultralytics YOLO를 기반으로 프로젝트를 구축하는 경우 Ultralytics YOLO 저장소를 직접 포크합니다.
   • Ultralytics 템플릿 사용: YOLO를 통합하는 깔끔하고 모듈화된 설정으로 시작하려면 Ultralytics 템플릿 저장소를 사용합니다.

2. 프로젝트에 라이선스 적용:

   • 전체 AGPL-3.0 라이선스 내용이 포함된 LICENSE 파일을 추가합니다.
   • 각 소스 파일의 맨 위에 라이선스를 표시하는 고지를 추가합니다.

3. 소스 코드 공개:

   • 프로젝트 전체의 소스 코드를 공개적으로 액세스할 수 있도록 합니다(예: GitHub에 게시). 여기에는 다음이 포함됩니다.
     • YOLO 모델 또는 코드를 포함하는 전체 대규모 애플리케이션이나 시스템.
     • 원본 Ultralytics YOLO 코드에 적용한 모든 수정 사항.
     • 학습, 검증, 추론용 스크립트.
     • 수정하거나 파인 튜닝한 경우 모델 가중치.
     • 구성 파일, 환경 설정(requirements.txt, Dockerfiles).
     • 웹 애플리케이션의 일부인 경우 백엔드 및 프런트엔드 코드.
     • 수정한 타사 라이브러리.
     • 실행/재학습에 필요하고 재배포가 가능한 경우 학습 데이터.

4. 명확하게 문서화:

   • 프로젝트가 AGPL-3.0 라이선스에 따라 제공된다는 내용을 명시하도록 README.md을 업데이트합니다.
   • 소스 코드에서 프로젝트를 설정, 빌드, 실행하는 방법을 명확하게 안내합니다.
   • 원본 저장소로 연결하여 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 프로젝트에 관심을 가져 주셔서 감사합니다. 여러분의 참여는 소프트웨어의 미래를 만들어 가고 혁신과 협업이 활발한 커뮤니티를 구축하는 데 필수적입니다. 코드를 개선하거나, 버그를 보고하거나, 새로운 기능을 제안하는 등 여러분의 기여는 매우 소중합니다.

여러분의 아이디어가 실현되기를 기대하며 객체 탐지 기술 발전에 기여해 주셔서 감사합니다. 함께 이 흥미로운 오픈 소스 여정을 이어가며 성장과 혁신을 계속해 나가겠습니다.

자주 묻는 질문#