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

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

행동 규범#

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

풀 리퀘스트를 통한 기여#

풀 리퀘스트(PRs) 형태의 기여를 매우 소중하게 생각합니다. 검토 과정이 최대한 원활하게 진행되도록 다음 단계를 따라 주시기 바랍니다:

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

개발 설치#

포크(또는 메인 저장소)를 복제하고 편집 가능 모드(-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)에 서명해야 합니다. 이 법적 계약은 기여 내용에 적절한 라이선스가 부여되도록 하여 프로젝트가 AGPL-3.0 라이선스에 따라 계속 배포될 수 있도록 합니다.

풀 리퀘스트를 제출하면 CLA 봇이 서명 과정을 안내합니다. CLA에 서명하려면 PR에 다음 문구를 담은 댓글을 작성하면 됩니다:

I have read the CLA Document and I sign the CLA

구글 스타일 독스트링#

새 함수나 클래스를 추가할 때는 명확하고 표준화된 문서화를 위해 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 일반 공중 라이선스 v3.0(AGPL-3.0)을 사용합니다. 이 라이선스는 소프트웨어 개발에서 개방성, 투명성 및 협업을 통한 개선을 촉진합니다. 모든 사용자가 소프트웨어를 자유롭게 사용, 수정 및 공유할 수 있도록 하여 강력한 협업과 혁신의 커뮤니티를 조성합니다.

모든 기여자가 AGPL-3.0 라이선스의 조건을 숙지하여 Ultralytics 오픈 소스 커뮤니티에 효과적이고 윤리적으로 기여하시기를 바랍니다.

AGPL-3.0 라이선스로 YOLO 프로젝트 오픈소스화하기#

프로젝트에서 Ultralytics YOLO 모델이나 코드를 사용하시나요? 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 프로젝트에 관심을 갖고 기여해 주셔서 감사합니다. 여러분의 참여는 소프트웨어의 미래를 만들어 가고 활기찬 혁신과 협업의 커뮤니티를 구축하는 데 필수적입니다. 코드를 개선하거나, 버그를 보고하거나, 새로운 기능을 제안하는 등 여러분의 기여는 매우 소중합니다.

여러분의 아이디어가 실현되는 모습을 기대하며 객체 검출 기술 발전을 위해 헌신해 주시는 데 감사드립니다. 함께 이 흥미로운 오픈 소스 여정에서 계속 성장하고 혁신해 나가겠습니다.

FAQ#