GitHub에서 페이지 편집 (EN)

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

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

Ultralytics 오픈 소스 기여자



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

🤝 행동 강령

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

🚀 Pull Request를 통한 기여

Pull Request(PR) 형태의 기여를 매우 환영합니다. 원활한 검토 절차를 위해 다음 단계를 따라주시기 바랍니다:

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

📝 CLA 서명

Pull Request를 병합하기 전에 기여자 라이선스 계약(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 테스트

모든 Pull Request는 병합되기 전에 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)를 명시하십시오.
  • 예상 결과와 실제 결과 설명: 무엇을 기대했는지와 실제로 어떤 결과가 나왔는지 명확히 진술하십시오. 오류 메시지나 트레이스백을 포함하십시오.

📜 라이선스

Ultralytics는 리포지토리에 GNU Affero General Public License v3.0 (AGPL-3.0)을 사용합니다. 이 라이선스는 소프트웨어 개발에서 개방성(openness), 투명성(transparency), 협업적 개선(collaborative improvement)을 촉진합니다. 이는 모든 사용자가 소프트웨어를 사용, 수정 및 공유할 자유를 누릴 수 있게 하여 강력한 협업과 혁신의 커뮤니티를 조성합니다.

모든 기여자가 Ultralytics 오픈 소스 커뮤니티에 효과적이고 윤리적으로 기여할 수 있도록 AGPL-3.0 라이선스 약관을 숙지할 것을 권장합니다.

🌍 YOLO 프로젝트를 AGPL-3.0으로 오픈 소스화하기

Ultralytics YOLO 모델이나 코드를 프로젝트에 사용하십니까? AGPL-3.0 라이선스는 귀하의 전체 파생 작업물 또한 AGPL-3.0 하에 오픈 소스로 공개할 것을 요구합니다. 이는 오픈 소스 기반으로 구축된 수정 사항 및 대규모 프로젝트가 계속해서 오픈 상태로 유지되도록 보장합니다.

AGPL-3.0 준수가 중요한 이유

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

프로젝트를 오픈 소스로 공개하고 싶지 않다면 엔터프라이즈 라이선스 구매를 고려하십시오.

AGPL-3.0 준수 방법

준수란 프로젝트의 전체 대응 소스 코드를 AGPL-3.0 라이선스 하에 공개적으로 이용할 수 있도록 만드는 것을 의미합니다.

  1. 시작점 선택:

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

    • Add a LICENSE file containing the full text of the AGPL-3.0 license.
    • 각 소스 파일 상단에 라이선스를 명시하는 고지 사항을 추가하십시오.

  3. 소스 코드 게시:

  4. 명확한 문서화:

    • 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 프로젝트에 관심을 가져주셔서 감사합니다. 귀하의 참여는 소프트웨어의 미래를 설계하고 혁신과 협업의 활기찬 커뮤니티를 구축하는 데 필수적입니다. 코드 개선, 버그 신고, 새로운 기능 제안 등 귀하의 모든 기여는 매우 소중합니다.

귀하의 아이디어가 현실화되는 것을 보게 되어 기쁘며, 객체 탐지(object detection) 기술 발전을 위한 귀하의 헌신에 감사드립니다. 이 흥미로운 오픈 소스 여정에서 함께 계속 성장하고 혁신해 나갑시다.

FAQ

왜 Ultralytics YOLO 오픈 소스 리포지토리에 기여해야 합니까?

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

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 테스트를 통과하려면 어떻게 해야 합니까?

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

Ultralytics YOLO 저장소에서 버그를 보고하려면 어떻게 해야 합니까?

버그를 보고하려면 명확하고 간결한 최소 재현 가능 예제(Minimum Reproducible Example)를 함께 제공해 주십시오. 이는 개발자가 문제를 신속하게 파악하고 수정하는 데 도움이 됩니다. 예제는 문제를 재현하기에 충분하면서도 최소한의 수준이어야 합니다. 버그 보고에 대한 자세한 단계는 Reporting Bugs 섹션을 참조하십시오.

내 프로젝트에 Ultralytics YOLO를 사용할 경우 AGPL-3.0 라이선스는 어떤 의미를 갖습니까?

귀하의 프로젝트에 AGPL-3.0 라이선스가 적용된 Ultralytics YOLO 코드나 모델을 사용하는 경우, AGPL-3.0 라이선스에 따라 귀하의 전체 프로젝트(파생 저작물)도 반드시 AGPL-3.0 라이선스를 따라야 하며 전체 소스 코드를 공개해야 합니다. 이는 소프트웨어의 오픈 소스 본질이 파생물 전체에 걸쳐 유지되도록 하기 위함입니다. 이러한 요구 사항을 충족할 수 없는 경우 Enterprise License를 취득해야 합니다. 자세한 내용은 Open-Sourcing Your Project 섹션을 참조하십시오.

Contributors
GitHub에서 페이지 편집 (EN)
GLglenn-jocher22RIRizwanMunawar3PDpderrenger1Y-Y-T-G1WIWillie Maddox1LEleonnil1MAMatthewNoyce1BUBurhan-Q1

댓글