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

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

Watch: How to Contribute to Ultralytics Repository | Ultralytics Models, Datasets and Documentation 🚀

🤝 행동 강령#

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

🚀 Pull Request를 통한 기여#

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

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

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

독스트링 예시

이 예시는 표준 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

✅ 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 라이선스 하에 공개적으로 이용 가능하게 만드는 것을 의미합니다.

시작점 선택:
- Ultralytics YOLO 포크하기: 긴밀하게 기반하여 구축하는 경우 Ultralytics YOLO 저장소를 직접 포크하세요.
- Ultralytics 템플릿 사용하기: YOLO를 통합하는 깔끔하고 모듈화된 설정을 위해 Ultralytics 템플릿 저장소로 시작하세요.
프로젝트 라이선스 지정:
- AGPL-3.0 license의 전체 텍스트가 포함된 LICENSE 파일을 추가합니다.
- 각 소스 파일 상단에 라이선스를 나타내는 공지문을 추가하십시오.
소스 코드 게시:
- 프로젝트 전체의 소스 코드를 공개적으로 접근 가능하게 하십시오(예: GitHub). 여기에는 다음이 포함됩니다:
  - YOLO 모델이나 코드를 통합하는 더 큰 응용 프로그램 또는 시스템 전체.
  - 원본 Ultralytics YOLO 코드에 가해진 모든 수정 사항.
  - 학습, 검증 및 추론을 위한 스크립트.
  - 수정되거나 파인튜닝된 모델 가중치.
  - 설정 파일, 환경 설정 (requirements.txt, Dockerfiles).
  - 웹 애플리케이션의 일부인 백엔드 및 프론트엔드 코드.
  - 수정한 모든 서드파티 라이브러리.
  - 실행/재학습에 필요한 경우 및 재배포 가능한 학습 데이터.
명확하게 문서화:
- 프로젝트가 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#

왜 Ultralytics YOLO 오픈소스 저장소에 기여해야 합니까?#

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

Ultralytics YOLO를 위한 기여자 라이선스 계약(CLA)에는 어떻게 서명합니까?#

기여자 라이선스 계약(CLA)에 서명하려면 Pull Request 제출 후 CLA 봇이 제공하는 지침을 따르십시오. 이 과정은 귀하의 기여가 AGPL-3.0 라이선스하에 적절하게 라이선스되어 오픈소스 프로젝트의 법적 무결성을 유지하도록 보장합니다. Pull Request에 다음과 같이 댓글을 남기십시오:

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) 테스트를 통과해야 합니다. 이 테스트에는 코드가 프로젝트의 품질 표준을 충족하는지 확인하기 위한 린팅, 유닛 테스트 및 기타 검사들이 포함됩니다. 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)를 취득해야 합니다. 자세한 내용은 프로젝트 오픈소스화 섹션을 참조하세요.

기여자

GLglenn-jocher²⁴ RIRizwanMunawar³ RAraimbekovm¹ PDpderrenger¹ Y-Y-T-G¹ WIWillieMaddox¹ LEleonnil¹ MAMatthewNoyce¹ BUBurhan-Q¹

생성됨 2023년 11월 12일업데이트됨 3주 전