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

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

🤝 행동 강령#

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

🚀 Pull Request를 통한 기여#

풀 리퀘스트(PR) 형태의 기여에 깊이 감사드립니다. 원활한 검토 과정을 위해 다음 단계를 따라 주시기 바랍니다:

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

📚 문서 변경 사항#

문서 소스는 docs/en/ 경로에 있습니다. 리포지토리 루트에서 개발 의존성을 설치하고 PR을 열기 전에 전체 엄격 유효성 검사를 실행하세요:

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

이 유효성 검사는 zensical build --strict을(를) 실행하기 전에 생성된 참조, 매크로 및 비교 페이지를 준비합니다. 매크로를 사용하지 않는 페이지를 더 빠르게 실시간 미리 보려면 zensical serve을(를) 실행하세요.

📝 CLA 서명#

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

Pull Request를 제출한 후, CLA 봇이 서명 과정을 안내할 것입니다. CLA에 서명하려면 PR에 다음과 같은 댓글을 작성하십시오:

I have read the CLA Document and I sign the CLA

✍️ Google 스타일 독스트링(Docstrings)#

새로운 함수나 클래스를 추가할 때, 명확하고 표준화된 문서를 위해 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와 같은 도구는 스타일의 일관성을 유지하는 데 도움이 됩니다.
• 적절한 테스트 추가하기: 새로운 기능이 예상대로 작동하는지 확인하기 위해 테스트를 포함하세요.

👀 Pull Request 검토#

Pull Request를 검토하는 것도 기여할 수 있는 소중한 방법입니다. PR을 검토할 때:

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

🐞 버그 보고#

저희는 프로젝트의 품질과 신뢰성을 높이는 데 도움이 되는 버그 신고를 매우 중요하게 생각합니다. GitHub Issues를 통해 버그를 신고할 때:

• 기존 이슈 확인: 버그가 이미 보고되었는지 먼저 검색해보십시오.
• 최소 재현 가능 예제(Minimum Reproducible Example) 제공하기: 문제를 일관되게 재현하는 작고 독립적인 코드 스니펫을 만드세요. 이는 효율적인 디버깅을 위해 매우 중요합니다.
• 환경 설명하기: 운영 체제, Python 버전, 관련 라이브러리 버전(예: torch, ultralytics), 및 하드웨어(CPU/GPU)를 명시하세요.
• 기대 동작과 실제 동작 설명: 발생할 것으로 기대했던 일과 실제로 일어난 일을 명확하게 명시하십시오. 오류 메시지나 추적(traceback) 내용을 포함하십시오.

📜 라이선스#

Ultralytics는 저장소에 GNU Affero General Public License 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 라이선스 코드를 사용하면 프로젝트가 해당 약관에 구속됩니다.
• 협업 촉진: 공유와 투명성을 장려합니다.

프로젝트를 오픈소스화하고 싶지 않으신 경우, 기업용 라이선스(Enterprise License) 취득을 고려해 보세요.

AGPL-3.0 준수 방법#

준수한다는 것은 귀하 프로젝트의 완전한 상응 소스 코드를 AGPL-3.0 라이선스 하에 공개적으로 이용 가능하게 만드는 것을 의미합니다.

1. 시작점 선택:

   • Ultralytics YOLO 포크하기: 긴밀하게 기반하여 구축하는 경우 Ultralytics YOLO 저장소를 직접 포크하세요.
   • Ultralytics 템플릿 사용하기: YOLO를 통합하는 깔끔하고 모듈화된 설정을 위해 Ultralytics 템플릿 저장소로 시작하세요.

2. 프로젝트 라이선스 지정:

   • AGPL-3.0 license의 전체 텍스트가 포함된 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#